Événements vocaux

Bird émet des événements webhook au démarrage, à la prise en charge et à la fin d'un appel. Utilisez-les pour mettre à jour vos systèmes sans interrogation. Consultez Webhooks pour les abonnements, les signatures, les réessais et la rediffusion.

Parcours d'un appel à travers les types d'événements :

voice_call.initiated : Bird a accepté la demande d'établissement d'appel (un SIP INVITE) et a commencé le routage de l'appel
voice_call.answered : le numéro appelé a décroché. Seuls les appels pris en charge reçoivent cet événement
voice_call.ended : l'appel est terminé et l'événement contient le résultat

voice_call.initiated confirme qu'un appel existe, tandis que voice_call.ended rapporte son résultat. Un appel que Bird refuse après avoir accepté le INVITE émet quand même voice_call.ended avec status: "failed" et sip_response_code: 503.

Le type de l'événement est une énumération ouverte : Bird peut ajouter des types au fil du temps, donc gérez ceux que vous traitez et ignorez les autres au lieu de considérer un type inconnu comme une erreur.

L'enveloppe de l'événement

Les événements vocaux arrivent dans la même enveloppe imbriquée que tout autre événement Bird, décrite dans le guide Webhooks : type, timestamp et un objet data spécifique au type. L'identité de l'événement se trouve dans l'en-tête webhook-id HTTP plutôt que dans le corps.

Champ	Description
type	L'un des trois types de cette page, par exemple voice_call.ended
timestamp	Date de l'événement (RFC 3339). Triez par ce champ, jamais par l'ordre d'arrivée
data	Contenu spécifique à l'événement, contenant toujours les mêmes champs d'identité d'appel

Le data de chaque événement vocal contient les mêmes champs d'identité pour la corrélation. Les deux numéros utilisent le format E.164 : un + en tête, l'indicatif pays et le numéro national.

Champ	Description
call_id	L'identifiant de l'enregistrement d'appel (vcl_…), le même que celui affiché dans le Journal d'appels
session_id	Partagé par chaque segment d'un appel transféré ou multipartite (vcs_…). Null lorsqu'aucune corrélation de session ne s'applique
workspace_id	L'espace de travail auquel l'appel appartient
direction	outbound pour les appels passés par votre équipement
from	Le numéro appelant
to	Le numéro appelé

voice_call.initiated

Bird a reçu le INVITE et a commencé le routage.

Exemple de code

{
  "type": "voice_call.initiated",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
    "session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
    "workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
    "direction": "outbound",
    "from": "+14155551234",
    "to": "+16505559876"
  }
}

voice_call.answered

Le destinataire a décroché et le temps facturable a commencé. Un appel sans réponse ne génère pas cet événement.

Le contenu est constitué des champs d'identité d'appel présents dans chaque événement vocal, avec timestamp défini à l'instant de la prise en charge.

voice_call.ended

L'appel est terminé. Cet événement ajoute le résultat :

Champ	Description
status	Comment l'appel s'est terminé : answered, no_answer, failed, rejected ou unknown (voir Statuts)
sip_response_code	Le code SIP final de l'appel, par exemple 200 ou 486. Un appel Bird refusé contient 503 ; null lorsqu'aucun code final n'a été enregistré
duration_ms	Durée totale de l'appel en millisecondes, du moment où Bird a reçu l'appel jusqu'au raccroché
billable_ms	Durée en communication en millisecondes ; un appel sans réponse indique zéro

Exemple de code

{
  "type": "voice_call.ended",
  "timestamp": "2026-06-10T14:31:05Z",
  "data": {
    "call_id": "vcl_01krdgeqcxet5s7t44vh8rt9mg",
    "session_id": "vcs_01krdgeqcxet5s7t44vh8rt9mh",
    "workspace_id": "wsp_01krdgeqcxet5s7t44vh8rt9mj",
    "direction": "outbound",
    "from": "+14155551234",
    "to": "+16505559876",
    "status": "answered",
    "sip_response_code": 200,
    "duration_ms": 65000,
    "billable_ms": 60000
  }
}

L'enregistrement d'appel contient deux détails que cet événement omet : la raison du rejet et le coût. Ouvrez l'appel dans le journal d'appels pour distinguer un refus Bird d'une défaillance opérateur. Le coût apparaît une fois la tarification terminée.

Les consommer en toute sécurité

Dédupliquez sur webhook-id. Bird livre au moins une fois, et l'événement initiated d'un appel peut être publié plus d'une fois lorsqu'un réessai de signalisation le rediffuse. Même appel, même étape, même webhook-id : utiliser ce champ comme clé élimine le doublon.
Ne vous fiez pas à l'ordre. Les livraisons ne sont pas ordonnées : answered peut vous parvenir après ended. Triez par timestamp et laissez un événement arrivé plus tard mais avec un horodatage antérieur perdre.
Traitez ended comme le seul résultat fiable. C'est l'événement qui contient le statut et les durées, et c'est celui sur lequel baser vos propres enregistrements.
Réconciliez avec les enregistrements d'appels. Les événements fournissent des mises à jour en temps réel, tandis que le journal d'appels conserve l'enregistrement d'appel. Exportez les appels en CSV pour la réconciliation.

Étapes suivantes

Page	Ce qu'elle couvre
Webhooks et événements	Configuration de l'endpoint, vérification de la signature, réessais et rediffusion
Journal d'appels	Tous les champs d'un enregistrement d'appel et export CSV

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Comprendre le conceptWhat is a voice API?Explorer la fonctionnalitéVoice Guide d'implémentationVoice overview

Obtenir un guide d'implémentation