Passer un premier appel par API
Ce guide montre comment déclencher un appel sortant avec l’API voix de démonstration, puis suivre son état. Tout est fictif : l’appel est une simulation tant qu’aucun fournisseur n’est configuré.
Mis à jour le
Avant de commencer
- Une clé de test. Dans ce guide : tq_test_EXEMPLE, une valeur fictive qui n’ouvre aucun accès.
- Un projet. Dans ce guide : prj_EXEMPLE_A (« Projet A »).
- Deux numéros au format E.164, sans espace. Dans ce guide : +33199001234 (appelant) et +33199005678 (appelé), pris dans une plage fictive.
- curl, ou tout client HTTP capable d’envoyer des en-têtes.
Lancer l’appel
- Générez un identifiant unique pour l’en-tête Idempotency-Key (un UUID). Il est obligatoire sur chaque requête POST.
- Envoyez POST /calls avec from, to et project_id. Ajoutez flow_id si vous voulez rattacher un scénario d’appel.
- Conservez l’identifiant id de la réponse : il sert à retrouver l’appel dans le journal.
curl -X POST https://api.example.test/v1/calls \
-H "Authorization: Bearer tq_test_EXEMPLE" \
-H "Idempotency-Key: 3f1c2a9e-5b7d-4e08-9a41-6d2b8c0e7f15" \
-H "Content-Type: application/json" \
-d '{"from":"+33199001234","to":"+33199005678","project_id":"prj_EXEMPLE_A"}'Lire la réponse
L’API répond tout de suite avec l’appel créé. Le statut ringing signifie que la sonnerie est demandée, pas que la personne a décroché. Le champ simulated: true rappelle qu’aucune communication réelle n’a été émise.
{
"id": "call_EXEMPLE_001",
"status": "ringing",
"simulated": true
}Suivre l’état de l’appel
Les statuts possibles sont ringing, connected, completed et failed. Interrogez le journal avec GET /calls pour voir l’évolution, ou abonnez-vous aux événements call.ringing, call.connected, call.completed et call.failed par webhook.
Le journal distingue la durée de conversation (duration_seconds) de la durée facturable (billable_seconds). Ce sont deux valeurs différentes : ne les confondez pas avec la durée de sonnerie.
curl "https://api.example.test/v1/calls?limit=5" \
-H "Authorization: Bearer tq_test_EXEMPLE"Erreurs fréquentes
| Symptôme | Cause probable | Que faire |
|---|---|---|
| 400 invalid_request | Numéro avec espaces ou sans le signe plus, champ manquant, Idempotency-Key absente. | Envoyez les numéros en E.164 sans espace et ajoutez l’en-tête Idempotency-Key. |
| 401 unauthorized | Clé absente, mal recopiée ou en-tête Authorization mal formé. | Vérifiez le schéma Bearer et la valeur de la clé. |
| 403 forbidden | La clé n’a pas accès au projet demandé. | Utilisez une clé rattachée au bon projet. |
| 409 idempotency_conflict | La même clé d’idempotence a servi pour un corps de requête différent. | Générez une nouvelle clé pour une nouvelle opération. Rejouez la même clé uniquement pour répéter la même requête. |
| 429 rate_limited | Trop de requêtes sur une courte période. | Attendez la durée indiquée par l’en-tête Retry-After avant de réessayer. |
| Statut failed | L’appel n’a pas abouti. | Le statut ne donne pas la cause. Ne la déduisez pas : consultez le détail de l’appel et les journaux. |
Ce que ce guide ne fait pas
- Il n’émet aucun appel réel : tant qu’aucun fournisseur n’est configuré, tout est simulé.
- Il ne garantit pas qu’un appel aboutisse. Une capacité dépend du pays, du fournisseur retenu et du contrat.
- Il ne couvre ni l’enregistrement, ni la transcription, ni les commandes d’appel avancées (menu vocal, conférence), qui dépendent du fournisseur.
- Un appel peut produire plusieurs lignes de consommation selon le contrat. Voir le guide « Lire ses consommations ».
Questions fréquentes
Puis-je rejouer la même requête sans créer deux appels ?
Oui, si vous renvoyez la même Idempotency-Key avec le même corps. C’est le but de l’en-tête : un double clic ou une nouvelle tentative réseau ne crée pas un second appel.
À quoi sert flow_id ?
Il rattache l’appel à un scénario d’appel conçu dans la console. Il est facultatif : sans lui, l’appel relie simplement les deux numéros.