Bien démarrer avec l’API, le Playground et les webhooks

Retrouvez votre clé API, lancez une première requête sûre et configurez les notifications sans exposer vos identifiants.

Utiliser la référence API actuelle

Une fois connecté, ouvrez la documentation API. Elle présente les endpoints disponibles, les champs obligatoires et des exemples. Consultez-la pour les détails des requêtes : ce guide explique le parcours sans recopier les spécifications.

Préparer votre clé

Suivez la vérification d’identité pour afficher ou copier votre clé. La documentation autorise ensuite une période de cinq minutes pour consulter la clé et utiliser le Playground ; la génération ou régénération exige une nouvelle vérification. Protégez la clé comme un mot de passe : conservez-la sur le serveur de votre application, jamais dans un dépôt public, du code de navigateur ou une capture d’écran.

Effectuer une première requête sûre

Ouvrez le Playground et choisissez un exemple en lecture seule adapté à votre compte, comme la liste des identités SIP.
Vérifiez la méthode, le chemin et les paramètres. Utilisez les identifiants renvoyés pour votre compte, pas les valeurs d’exemple.
Choisissez Run request et examinez le statut HTTP ainsi que le corps de la réponse.
Reprenez l’exemple documenté dans votre application en stockant les identifiants de manière sécurisée.

Le Playground utilise votre compte. Envoyer des messages, passer des appels ou commander des services peut produire de vraies opérations facturées. Ce n’est pas un bac à sable gratuit.

Ajouter des notifications webhook

Dans les intégrations du compte, ajoutez un endpoint HTTPS et sélectionnez les événements utiles. Le secret de signature du webhook est distinct de votre clé API. Vérifiez les signatures, traitez chaque événement une seule fois et accusez réception rapidement. Consultez les journaux de livraison pour le diagnostic. Avant de répéter une opération payante, lisez les règles API de réessai et de doublons ; un délai dépassé ne prouve pas à lui seul un échec.

Guides associés

Choisir la bonne référence de service

La référence distingue Lookup, Pricing, SIP, SMS, Contacts, Speech API, Phone Numbers, Voice API et Calls & recordings. Consultez chaque endpoint pour ses prérequis, champs et frais exacts. Les appels depuis le navigateur ont leur propre guide Webphone SDK ; ils ne correspondent pas au contrôle d’appel Voice API côté serveur.

L’autorisation d’un agent de lire la documentation ne lui donne accès ni à la clé du propriétaire ni à l’exécution du Playground authentifiée par clé. Demandez au propriétaire de gérer les identifiants d’intégration plutôt que de partager sa connexion.

Utiliser les références renvoyées et la pagination

Traitez les références publiques d’appel comme des valeurs opaques : copiez la référence CALL- complète de votre réponse, sans en fabriquer une ni utiliser un identifiant téléphonique interne. Les appels passés et actifs sont deux listes différentes. Une commande exige aussi un état d’appel compatible ; une ligne d’historique n’est pas forcément contrôlable.

Pour l’historique, suivez pagination.next_cursor tant que pagination.has_more est vrai. Gardez les filtres days, limit et identité SIP d’origine. Ne décodez ni ne modifiez le curseur. S’il expire, relancez la liste et rapprochez les résultats par référence publique. Un horodatage API documenté en UTC doit être converti volontairement pour l’affichage ; il ne correspond pas automatiquement à l’heure locale du navigateur.

Gérer les erreurs sans doubler les opérations payantes

Lisez ensemble le statut HTTP et l’erreur structurée. Corrigez les erreurs de validation ou d’autorisation avant de réessayer. Respectez le délai documenté en cas de limite de débit. Après un timeout ou une erreur temporaire sur une opération payante, vérifiez son état et les règles de doublons de l’endpoint avant de renvoyer : changer les identifiants peut créer une nouvelle opération. Conservez pour le support la référence publique, l’heure et l’erreur sans données sensibles, jamais la clé API.