Appeler les événements
Tous les événements représentant l'état des appels téléphoniques ont des champs et des significations communs, qu'ils soient délivrés en réponse à des méthodes de contrôle des appels, ou en interrogeant des événements, ou encore par le biais d'un webhook. Tous les événements d'appel ont les propriétés suivantes :
| Propriété | Description |
|---|---|
id |
L'identifiant unique de l'événement |
userId |
L'identifiant de l'utilisateur du VIS associé à l'événement |
accountId |
L'identifiant du compte VIS associé à l'événement |
externalId |
Identifiant du fournisseur de communications externes. Dans les charges utiles des webhooks, cet identifiant contient l'ID d'appel (parfois accompagné d'un _{extension} suffixe). |
direction |
Soit INBOUND soit OUTBOUND |
phoneNumber |
Le numéro de téléphone du correspondant distant |
callerId |
Le nom de la partie distante |
state |
L'état de l'appel, voir États des événements ci-dessous |
duration |
Durée de l'appel (en millisecondes) |
startTime |
Date/heure ISO-8601 à laquelle l'appel a commencé. Pour les appels sortants, l'heure de début marque le moment où l'appel est passé ; pour les appels entrants, elle marque le moment où l'appel a été reçu pour la première fois. |
answerTime |
Une date/heure ISO-8601 à laquelle l'appel a été pris |
endTime |
Date/heure ISO-8601 de la fin de l'appel |
Webhook externalId et l'identification de l'appelant
Pour les données utiles des webhooks, l'identifiant d'appel et externalId font référence au même identifiant d'appel.
externalId est généralement présenté sous la forme suivante : {call_id}_{extension}.
Exemple : abc1234-288c-40d3-8ec8-3618a3ae7698_123
Pour extraire l'identifiant d'appel à partir de externalId, séparé par un trait de soulignement (_) et récupérer le premier élément.
Dans l'exemple ci-dessus, l'identifiant d'appel est : abc1234-288c-40d3-8ec8-3618a3ae7698
Dans certains cas, externalId ne doit pas contenir de trait de soulignement. Dans ce cas, utilisez le nom complet externalId valeur comme identifiant d'appel.
États de l'événement
Les API VIS présentent un modèle d'état d'événement pour les appels téléphoniques, masquant les différences et les complexités de Vonage Business Communications et de Vonage Enterprise. Ces états d'événements sont fournis en réponse aux API de méthodes (telles que placer un appel, obtenir des appels) et inclus dans les notifications d'événements webhook. Il est essentiel de comprendre le modèle d'état d'événement pour créer des intégrations externes.
La machine à états finis suivante décrit les transitions d'état autorisées :
Le seul état initial est Initializing. Les seuls états finaux autorisés sont Answered, Cancelled, Rejectedet Missed. Les états d'appel se trouvant dans l'un des états finaux resteront toujours dans l'état final.
| État | Initiale | Finale | Direction | Transitions autorisées | Description |
|---|---|---|---|---|---|
| Initialisation | Oui | Non | Inbound | Sonnerie, réponse | Un appel a été passé mais le correspondant distant n'a pas encore été alerté. |
| Sonnerie | Non | Non | Entrant, sortant | Actif, Répondu, Annulé, Rejeté, Manquant | Le correspondant distant est alerté (appel sortant) ou un appel entrant est en cours. |
| Actif | Non | Non | Entrant, sortant | Répondu, tenu, tenu à distance | Un appel est actif et les participants sont en train de parler |
| Maintenu | Non | Non | Entrant, sortant | Actif | Un appel actif est actuellement en attente |
| Tenue à distance | Non | Non | Entrant, sortant | Actif | Un correspondant distant d'un appel actif est actuellement en attente |
| Répondu | Non | Oui | Entrant, sortant | Un appel d'une durée non nulle s'est terminé | |
| Annulé | Non | Oui | Sortie | Un appel sortant a été annulé avant que le correspondant distant ne réponde. | |
| Manqué | Non | Oui | Inbound | Un appel entrant n'a pas été pris | |
| Rejeté | Non | Oui | Inbound | Un appel entrant a été rejeté ou envoyé à la messagerie vocale sans avoir été pris. |
Pour chaque État, les valeurs de startTime, answerTime, endTimeet duration suivra certaines règles.
Tous les états d'appel auront un startTime. Seulement Active, Held, Remote Heldet Answered aura un answerTime.
Les endTime restera nulle jusqu'à ce que l'appel atteigne un état final (Answered, Cancelled, Missed, Rejected).
Seuls les appels qui ont atteint la finale Answered aura une durée non nulle.
Obtention des événements d'appel
L'API permet de récupérer les événements d'appel pour les appels actifs ou terminés. Le nombre d'enregistrements d'événements d'appel pouvant être élevé, la réponse peut être paginée. En règle générale, les applications récupèrent le nombre total d'enregistrements pour un ensemble particulier de paramètres de requête, puis récupèrent les événements au cours de plusieurs appels à l'API en utilisant le même ensemble de paramètres de requête et un nombre maximal d'événements à renvoyer par appel.