API et webhooks de Call pour développeurs : clés, portées, événements
Tour d'horizon de l'API REST de Call : clés d'API et portées, limites de débit, gestion des erreurs, webhooks signés et page Développeurs pour gérer les endpoints.
Tôt ou tard, un système téléphonique doit dialoguer avec autre chose : un CRM qui doit afficher un appel dès qu'il se termine, un outil de facturation qui veut savoir qui a appelé, un script qui déclenche un appel à l'envoi d'un formulaire. Call dispose précisément pour cela d'une API REST et de webhooks sortants. Ce guide explique comment les éléments s'articulent, ce qu'il faut demander avant d'écrire du code, et les erreurs qui coûtent le plus souvent un après-midi à un développeur.

Si votre objectif est simplement de transférer des contacts en masse, lisez d'abord Importer des contacts dans le CRM d'une équipe téléphonique ; un import est souvent plus simple qu'une intégration.
Par où commencer : la référence et la page Développeurs
Il y a deux endroits à connaître. La Référence de l'API se trouve sous Paramètres, ainsi que dans le menu Ressources de la page d'accueil. Elle se consulte sans connexion, ce qui est pratique pour cadrer un projet pour un client. La page Développeurs, également sous Paramètres, concerne votre propre espace de travail : elle affiche les identifiants de votre organisation et de vos agents, vos endpoints de webhook et une liste en lecture seule de vos clés.
Ce que vous trouvez à chaque endroit
- Pour commencerURL de base et conventions, authentification avec un tableau des portées, et erreurs avec les codes d'état.
- EndpointsChaque carte d'endpoint indique sa portée, ses paramètres, le corps de la requête, la réponse et les erreurs, avec des requêtes prêtes à copier en curl, JavaScript et Python.
- RechercheAppuyez sur / pour aller à la recherche d'endpoints et filtrer par méthode, chemin, portée ou résumé.
- OpenAPI JSONTélécharge toute la spécification en un seul fichier pour vos propres outils.
- ID d'agent / APIL'ID et le slug de votre organisation, le mode de l'API (Sandbox ou Live) et l'ID de l'agent IA choisi, chacun avec un bouton Copier.
- WebhooksVos endpoints, les événements que reçoit chacun, le dernier statut HTTP et les éventuelles livraisons en échec.
Lisez les sections sur les limites de débit et les webhooks sortants avant la mise en production, pas après. Elles décrivent des comportements faciles à manquer lors d'un test rapide.
Clés d'API et portées
Chaque requête transmet une clé dans un en-tête Authorization, sous forme de jeton bearer. Les clés ne se créent pas dans l'application : c'est l'opérateur de votre espace de travail qui les émet et vous indique leurs portées. La clé complète n'est affichée qu'une fois, au moment de son émission ; ensuite, seuls ses premiers caractères apparaissent. Rangez-la donc immédiatement dans votre propre coffre de secrets.
| Portée | Ce qu'elle permet |
|---|---|
| read | Lire les contacts, appels, files, membres de l'équipe, rapports et la liste d'opposition. |
| write | Créer et mettre à jour des contacts, enregistrer l'issue des appels, ajouter des numéros à la liste d'opposition. |
| calls | Passer et terminer des appels. |
| admin | Gérer les webhooks ; peut aussi appeler tous les autres endpoints. |
Demandez le plus petit ensemble qui permet de faire le travail. Un script de reporting n'a besoin que de read ; un bouton click-to-call a besoin de calls. Si une requête renvoie un 403 avec le code insufficient_scope, la clé ne dispose pas de la portée indiquée sur la carte de cet endpoint.
Sandbox et production
Les clés peuvent être émises pour un environnement sandbox, qui utilise un simulateur et ne passe aucun vrai appel, ou pour la production. Considérez le préfixe d'une clé comme une simple étiquette : une clé étiquetée « test » fonctionne sur les mêmes données et la même connexion téléphonique qu'une clé de production. Ne comptez donc pas sur le préfixe pour tenir vos expériences à l'écart des vrais clients. Fiez-vous au mode de l'API affiché sur la page Développeurs pour savoir où vous en êtes.
Passer des appels via l'API
Les endpoints publics couvrent l'essentiel : un contrôle de santé, la liste des appels, la lecture d'un appel, le lancement d'un appel, le raccrochage, la gestion des webhooks et la conversation avec un agent IA. Un appel sortant passé via l'API subit le même contrôle de conformité qu'un appel passé depuis le poste : un numéro figurant sur la liste d'opposition ou appelé en dehors des plages horaires autorisées est refusé, exactement comme pour un conseiller. Concevez votre code pour traiter ce refus comme une issue normale, pas comme un bug.
C'est important pour la conception. N'écrivez pas de boucle qui relance un appel refusé jusqu'à ce qu'il passe. Lisez la raison, journalisez-la et passez à la suite. Pour les règles à l'origine de ces refus, consultez La protection des plages horaires d'appel dans Call et La liste d'opposition dans Call.
Limites de débit et erreurs
Chaque clé a sa propre limite de requêtes par minute, fixée à son émission ; la valeur par défaut est de 120. Lorsqu'une clé a épuisé son quota de la minute, l'API répond 429 avec le code rate_limited et indique le délai d'attente dans l'en-tête X-RateLimit-Reset. Attendez ce délai, puis reprenez. Un client bien élevé ralentit de lui-même avant d'atteindre la limite.
- 429 rate_limited : patientez pendant la durée indiquée dans l'en-tête de réinitialisation, et étalez les traitements en masse dans le temps.
- 403 insufficient_scope : la clé ne dispose pas de la portée indiquée sur la carte de l'endpoint ; demandez une clé qui l'inclut.
- Autres erreurs : basez-vous sur le code d'erreur, pas sur le message. Les codes ne changent pas ; la formulation peut changer.
Traiter une requête en échec
- Lire le statutEst-ce une erreur client que vous pouvez corriger, ou une erreur serveur qui justifie une nouvelle tentative ?
- Lire le codeAiguillez votre logique sur le code, jamais sur le texte du message.
- TemporiserPour un 429, attendez selon l'en-tête de réinitialisation ; pour les erreurs serveur, réessayez quelques fois avec des délais croissants.
- Journaliser le détailConservez l'endpoint, le code et l'heure pour que l'assistance puisse retracer l'incident.
- S'arrêter sur les refusUn refus de conformité est une décision, pas un incident ; ne bouclez pas dessus.
Webhooks : recevoir des événements
Au lieu d'interroger l'API encore et encore pour savoir si quelque chose s'est produit, laissez Call vous prévenir. Sur la page Développeurs, appuyez sur Ajouter un endpoint, saisissez une adresse https publique et cochez les événements souhaités ; n'en cocher aucun revient à tous les recevoir. Le secret de signature s'affiche une seule fois, à l'ajout de l'endpoint. Copiez-le à ce moment-là. S'il est perdu, supprimez l'endpoint et ajoutez-le de nouveau pour en obtenir un autre.
Chaque livraison est signée. L'en-tête de signature contient un HMAC-SHA256 de l'horodatage et du corps séparés par un point, calculé avec votre secret de signature, et un en-tête distinct transporte l'horodatage. Recalculez-le de votre côté et comparez avant de vous fier au contenu. La référence de l'API inclut des exemples de code en Node.js et Python, et rejeter les horodatages trop anciens vous protège contre les requêtes rejouées.
Un bon et un mauvais récepteur de webhooks
| Bon | Mauvais | |
|---|---|---|
| Signature | Vérifiée à chaque requête | Acceptée sans contrôle |
| Réponse | 2xx en quelques secondes, traitement mis en file pour plus tard | Traitement lent avant de répondre |
| Doublons | Recevoir deux fois le même événement est sans danger | Crée deux enregistrements |
| Échecs | Alerte en cas d'échec des livraisons | Silence jusqu'à ce que quelqu'un s'en aperçoive |
Votre endpoint doit répondre avec un statut 2xx en moins de 10 secondes. Une livraison en échec est retentée, jusqu'à six tentatives au total, et un endpoint qui échoue 50 fois de suite est désactivé. Chaque ligne de la page Développeurs affiche le dernier statut HTTP et le nombre de livraisons en échec, et Envoyer un test déclenche un événement de test signé pour voir ce que répond votre serveur.
Liste de contrôle avant la mise en production
Avant d'activer une intégration
- Vous savez quelles portées a la clé, et elle n'en a pas plus que nécessaire
- La clé est rangée dans un coffre de secrets, pas dans le code source
- Les signatures des webhooks sont vérifiées et les horodatages trop anciens rejetés
- Le récepteur répond rapidement et gère les événements en double
- Les réponses de limite de débit et de refus sont traitées sans boucles de relance serrées
- Vous avez testé en mode sandbox et appuyé sur Envoyer un test sur l'endpoint
- Une personne est désignée pour recevoir une alerte si les livraisons commencent à échouer
Le faire dans Call
Dans Call, ouvrez Paramètres, puis Référence de l'API pour étudier les endpoints, et Paramètres, puis Développeurs pour copier l'ID de votre organisation, vérifier vos clés et ajouter un webhook. Les propriétaires, administrateurs et responsables peuvent ajouter, tester et supprimer des endpoints ; les autres voient la liste. Si vous utilisez aussi les fonctions d'agent IA, l'ID d'agent affiché sur la même page alimente l'endpoint de conversation. Pour la partie vocale du produit, consultez Configurer un agent IA dans Call.
Questions fréquentes
Comment obtenir une clé d'API ?
Les clés sont émises par l'opérateur de votre espace de travail ; elles ne peuvent pas être créées dans l'application. Demandez-en une en précisant les portées nécessaires. La clé complète n'est affichée qu'une fois, lors de son émission.
Que signifie une réponse 429 ?
La clé a épuisé ses requêtes pour la minute en cours. Attendez le nombre de secondes indiqué dans l'en-tête X-RateLimit-Reset, puis réessayez, et étalez les traitements en masse sur une période plus longue.
Comment vérifier qu'un webhook provient bien de Call ?
Calculez un HMAC-SHA256 de l'horodatage et du corps avec votre secret de signature et comparez-le à l'en-tête de signature. La référence de l'API fournit des exemples en Node.js et Python.
Puis-je envoyer des webhooks vers un serveur de développement local ?
Pas directement. Les endpoints doivent être des adresses https publiques : utilisez un outil de tunnel qui expose votre serveur local sur une telle adresse.
Pourquoi mon appel lancé via l'API a-t-il été refusé ?
Les appels passés via l'API subissent le même contrôle de conformité que ceux passés depuis le poste. Un numéro figurant sur la liste d'opposition ou appelé en dehors des plages horaires autorisées est refusé.
Qui peut voir et modifier les webhooks ?
Tout le monde peut consulter la liste, mais seuls les propriétaires, administrateurs et responsables peuvent ajouter, tester ou supprimer des endpoints.