Référence des Webhooks de l'API Voice

Vonage utilise des webhooks avec son Voice API pour permettre à votre application d'interagir avec l'appel. Il existe deux points d'extrémité obligatoires et un point d'extrémité facultatif pour les webhooks :

  • Réponse webhook est envoyé lorsqu'un appel est pris. Cela vaut pour les appels entrants comme pour les appels sortants.
  • Crochet web d'événement est envoyé pour tous les événements qui se produisent au cours d'un appel. Votre application peut enregistrer chaque type d'événement, y réagir ou l'ignorer.
  • URL de repli est utilisé lorsque le webhook Answer ou Event échoue ou renvoie un statut d'erreur HTTP.
  • Erreurs sont également transmis au point de terminaison du webhook d'événement s'ils se produisent.

Pour plus d'informations générales, consultez notre guide webhooks.

Webhooks signés

Les webhooks signés sont un moyen de vérifier que la demande provient bien de Vonage et que sa charge utile n'a pas été altérée pendant le transit. Voice API, de même que Messages et Envoi prennent en charge les rappels signés par défaut. Voir Décodage des webhooks signés pour apprendre à décoder une signature JWT entrante.

Réponse Webhook

Lorsqu'un appel entrant est pris, une requête HTTP est envoyée à l'adresse suivante answer_url que vous avez spécifié lors de la configuration de l'application. Pour les appels sortants, spécifiez l'option answer_url lorsque vous passez l'appel.

Par défaut, le webhook de réponse sera un GET mais cette option peut être remplacée par POST en réglant le answer_method champ. Pour les appels entrants, vous configurez ces valeurs lorsque vous créez l'application. Pour les appels sortants, vous spécifiez ces valeurs lors de l'émission d'un appel.

Répondre aux champs de données du webhook

Champ d'application Exemple Description
to 442079460000 Le numéro qui a répondu à l'appel. (Il s'agit du numéro virtuel lié à votre Applications.)
from 447700900000 Le numéro qui a appelé to. Il peut s'agir d'un numéro de téléphone fixe ou mobile, ou d'un autre numéro virtuel si l'appel a été programmé.
from_user JaneDoe Le nom d'utilisateur qui a appelé to uniquement si l'appel a été effectué à l'aide du Client SDK. Dans ce cas, from seront absents (c'est-à-dire, from et from_user ne seront jamais présents tous les deux ensemble).
endpoint_type phone Le type de canal vocal qui a répondu à l'appel. Les valeurs possibles sont phone, sip, websocket, app, vbc.
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab Un identifiant unique pour cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab Un identifiant unique pour cette conversation
region_url https://api-ap-3.vonage.com Point de terminaison de l'API régionale qui doit être utilisé pour contrôler l'appel avec API RESTVoir la liste complète des régions ici
custom_data { "key": "value" } Un objet de données personnalisé, éventuellement transmis en tant que paramètre de la fonction serverCall lorsqu'un appel est lancé à partir d'une application utilisant la méthode Client SDK

Transmission de données supplémentaires avec les en-têtes SIP

En plus des champs ci-dessus, vous pouvez spécifier tous les en-têtes supplémentaires dont vous avez besoin lorsque vous utilisez SIP Connect. Tous les en-têtes fournis doivent commencer par X- et sera envoyé à votre answer_url avec un préfixe de SipHeader_. Par exemple, si vous ajoutez un en-tête de X-UserId avec une valeur de 1938ND9Vonage ajoutera SipHeader_X-UserId=1938ND9 à la demande faite à votre answer_url.

Avertissement : Les en-têtes qui commencent par X-Nexmo ne sera pas envoyé à votre answer_url

Vonage soutient à la fois X- et l'en-tête D'utilisateur à utilisateur l'en-tête. Ces mécanismes peuvent être utilisés individuellement ou conjointement dans le cadre d'un même appel.

L'en-tête User-to-User vous permet d'envoyer des données contextuelles pendant un appel de votre équipement SIP à votre application Voice API. Pour utiliser cet en-tête, votre équipement SIP doit envoyer un en-tête User-to-User à votre domaine SIP programmable. En outre, votre application Voice API devra recevoir le webhook de réponse qui contient le contenu de cet en-tête.

Les En-tête d'utilisateur à utilisateur doit être formaté comme suit : SipHeader_User-to-User=1234567890abcdef;encoding=hex

L'en-tête User-to-User est validé uniquement pour s'assurer qu'il contient des caractères valides et qu'il ne dépasse pas 256 caractères. Le contenu lui-même n'est pas validé par ailleurs.

Exemples de champs de données de webhook Answer

Pour un GET les variables seront dans l'URL, comme ceci :

/answer.php?to=442079460000&from=447700900000&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789ab&SipHeader_X-UserId=1938ND9

Si vous réglez le answer_method à POST vous recevrez alors la requête avec des données au format JSON dans le corps du message :

{
  "from": "442079460000",
  "to": "447700900000",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "SipHeader_X-UserId": "1938ND9"
}

Répondre au webhook de réponse

Vonage s'attend à ce que vous renvoyiez un BCN au format JSON contenant les actions à effectuer.

Crochet web d'événement

Les requêtes HTTP du webhook d'événement arriveront au point de terminaison du webhook d'événement en cas de changement d'état d'un appel. L'URL sera l'URL event_url que vous avez spécifiée lors de la création de votre application, à moins que vous ne la remplaciez en définissant une valeur spécifique de event_url lors du démarrage d'un appel.

Par défaut, les demandes entrantes sont POST avec un corps JSON. Vous pouvez surcharger la méthode pour GET en configurant le event_method en plus de la event_url. On s'attend à ce que votre système réponde à la requête HTTP. Si votre système n'accuse pas réception de l'événement ou s'il répond par 429, 502, 503 ou 504, une nouvelle tentative sera effectuée. Pour les événements nécessitant le renvoi d'un NCCO, l'URL de repli sera alors utilisée. Se référer à l'URL de repli URL de secours pour plus de détails.

Le format des données incluses dépend de l'événement qui s'est produit :

Commencé

Indique que l'appel a été créé.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status started Statut de l'appel
direction outbound La direction de l'appel peut être soit inbound ou outbound
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Sonnerie

La destination de l'appel sonne.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status ringing Statut de l'appel
direction outbound La direction de l'appel peut être soit inbound ou outbound
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Répondu

L'appel a été entendu.

Champ d'application Exemple Description
start_time null Ce champ n'est pas pris en charge actuellement.
rate 0.12 Coût de l'appel en euros
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status answered Statut de l'appel
direction inbound La direction de l'appel peut être soit inbound ou outbound
network null Type de réseau utilisé lors de l'appel
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Occupé

La destination est en ligne avec un autre appelant.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status busy Statut de l'appel
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
sip_code 404 Le code d'état SIP renvoyé (par exemple, 404, 480ou 487) par l'intermédiaire du event_urlLe code d'état SIP fournit des détails supplémentaires sur la raison de l'achèvement ou de l'échec de l'appel. Voir la description des codes d'état SIP ici.

Retour à la liste des webhooks d'événements

Annulé

Un appel sortant est annulé par son auteur avant d'être pris.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status cancelled Statut de l'appel
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Sans réponse

Soit le destinataire est injoignable, soit il a refusé l'appel.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status unanswered Statut de l'appel
detail unavailable Indique si l'abonné est temporairement indisponible (unavailable) ou le transporteur n'a pas pu fournir de réponse dans un délai approprié (timeout)
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
sip_code 404 Le code d'état SIP renvoyé (par exemple, 404, 480ou 487) par l'intermédiaire du event_urlLe code d'état SIP fournit des détails supplémentaires sur la raison de l'achèvement ou de l'échec de l'appel. Voir la description des codes d'état SIP ici.

Retour à la liste des webhooks d'événements

Déconnecté

Si la connexion WebSocket est interrompue du côté de l'application pour une raison quelconque, le rappel de l'événement de déconnexion est envoyé, si la réponse contient un NCCO, celui-ci est traité, si aucun NCCO n'est présent, l'exécution normale se poursuit.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status disconnected Statut de l'appel
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Rejeté

L'appel a été rejeté par Vonage avant d'être connecté.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status rejected Statut de l'appel
detail restricted Indique si to ou from ne sont pas valides (invalid_number), l'appel rejeté par le transporteur (restricted) ou rejetée par l'appelant (declined)
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
sip_code 404 Le code d'état SIP renvoyé (par exemple, 404, 480ou 487) par l'intermédiaire du event_urlLe code d'état SIP fournit des détails supplémentaires sur la raison de l'achèvement ou de l'échec de l'appel. Voir la description des codes d'état SIP ici.

Retour à la liste des webhooks d'événements

Échec

L'appel sortant n'a pas pu être connecté.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status failed Statut de l'appel
detail cannot_route Indique que la destination n'est pas prise en charge ou bloquée pour le compte (cannot_route), le numéro n'est pas disponible (number_out_of_service) ou une erreur de serveur s'est produite (internal_error)
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
sip_code 404 Le code d'état SIP renvoyé (par exemple, 404, 480ou 487) par l'intermédiaire du event_urlLe code d'état SIP fournit des détails supplémentaires sur la raison de l'achèvement ou de l'échec de l'appel. Voir la description des codes d'état SIP ici.

Retour à la liste des webhooks d'événements

Homme / Machine

Dans le cas d'un appel sortant effectué de manière programmatique, si le machine_detection est activée, un événement dont le statut est human ou machine sera envoyé selon que la personne a répondu ou non à l'appel.

Champ d'application Exemple Description
call_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel (Note call_uuid, pas uuid comme dans d'autres points finaux)
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
status human Statut de l'appel, peut être soit human si une personne a répondu ou machine si l'appel a été pris par une boîte vocale ou un autre service automatisé
sub_state beep_start État de la détection de la machine avancée, lorsque l'appel est pris par la messagerie vocale ou le télécopieur et que le bip est détecté. Les valeurs possibles sont beep_start pour la messagerie vocale, fax pour le télécopieur et beep_timeout.
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Délai d'attente

Si la durée de la phase de sonnerie dépasse le seuil spécifié ringing_timeout cet événement sera envoyé.

Champ d'application Exemple Description
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status timeout Statut de l'appel
direction outbound Direction de l'appel, ce sera outbound dans ce contexte
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

Terminé

L'appel est terminé, cet événement comprend également des données récapitulatives sur l'appel.

Champ d'application Exemple Description
end_time 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
network GB-FIXED Le type de réseau utilisé lors de l'appel
duration 2 Durée de l'appel (en secondes)
start_time 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
rate 0.00450000 Coût par minute de l'appel (EUR)
price 0.00015000 Coût total de l'appel (EUR)
from 442079460000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
status completed Statut de l'appel
direction entrant La direction de l'appel peut être soit inbound ou outbound
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
disconnected_by user Peut prendre l'une des deux valeurs suivantes :
platform - L'appel a été interrompu par la plateforme Voice API, par exemple le NCCO a terminé sa dernière action et l'appel a été déconnecté.
user - L'appel a été interrompu par l'utilisateur, par exemple l'utilisateur a raccroché, rejeté l'appel ou n'a pas répondu.
sip_code 404 Le code d'état SIP renvoyé (par exemple, 404, 480ou 487) par l'intermédiaire du event_urlLe code d'état SIP fournit des détails supplémentaires sur la raison de l'achèvement ou de l'échec de l'appel. Voir la description des codes d'état SIP ici.

Retour à la liste des webhooks d'événements

Enregistrer

Ce webhook arrive lorsqu'un NCCO avec une action "record" est terminé. Lors de la création d'une action d'enregistrement, vous pouvez définir une valeur de eventUrl pour que cet événement soit envoyé. Cela peut s'avérer utile si vous souhaitez utiliser un code distinct pour gérer ce type d'événement.

Champ d'application Exemple Description
start_time 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
recording_url https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab Où télécharger l'enregistrement
size 12222 Taille du fichier d'enregistrement (en octets)
recording_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab Un identifiant unique pour cet enregistrement
end_time 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Transcription

Champ d'application Exemple Description
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
type record L'action NCCO de type enregistrement
recording_uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab Un identifiant unique pour cet enregistrement
status transcribed État de la transcription
transcription_url https://api.nexmo.com/v1/files/bbbbbbbb-aaaa-cccc-dddd-0123456789ab L'URL du fichier contenant la transcription de l'enregistrement

Retour à la liste des webhooks d'événements

Entrée

Ce webhook est envoyé par Vonage lorsqu'un NCCO avec une action "input" est terminé.

Champ d'application Exemple Description
from 447700900000 Le numéro d'où provient l'appel
to 447700900000 Le numéro auquel l'appel a été passé
dtmf voir ci-dessous Résultats de la capture DTMF
speech voir ci-dessous Résultats de la reconnaissance vocale
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel. La propriété peut ne pas apparaître lorsqu'une entrée atteint un délai d'attente DTMF.
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Résultats de la capture DTMF

Champ d'application Exemple Description
digits 42 Les boutons pressés par l'utilisateur
timed_out true Si l'entrée DTMF a été interrompue : true si c'était le cas, false si ce n'est pas le cas

Résultats de la reconnaissance vocale

Champ d'application Exemple Description
timeout_reason end_on_silence_timeout Indique si la saisie s'est terminée lorsque l'utilisateur a cessé de parler (end_on_silence_timeout), par le délai d'attente de la durée maximale (max_duration) ou si l'utilisateur n'a rien dit (start_timeout)
results voir ci-dessous Tableau de objets textuels reconnus
error ERR1: Failed to analyze audio Message d'erreur.
recording_url https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab Enregistrement de la parole. Inclus si saveAudio est fixé à true dans le input action. Requiert une autorisation JWT pour le téléchargement, voir Télécharger un enregistrement.
Texte de la transcription
Champ d'application Exemple Description
text sales Texte de transcription représentant les mots prononcés par l'utilisateur.
confidence 0.9405097 L'estimation de confiance est comprise entre 0,0 et 1,0. Un chiffre plus élevé indique une plus grande probabilité que les mots reconnus soient corrects.

Voir aussi l'exemple complet de charge utile présenté dans Référence NCCO

Retour à la liste des webhooks d'événements

Transfert

Ce webhook est envoyé par Vonage lorsqu'un segment a été transféré d'une conversation à une autre. Ce transfert peut être effectué à l'aide d'un NCCO ou de la fonction transfer action

Champ d'application Exemple Description
conversation_uuid_from CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab La conversation ID que la jambe était à l'origine en
conversation_uuid_to CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'ID de conversation que la jambe a été transférée à
uuid aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cet appel
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)

Retour à la liste des webhooks d'événements

URL de repli

Le webhook de secours est accessible lorsque le webhook de réponse ou le webhook d'événement, alors que l'événement est censé répondre par un NCCO, renvoie un statut d'erreur HTTP ou est inaccessible. Les données renvoyées par l'URL de secours sont les mêmes que celles reçues dans l'URL de réponse ou l'URL d'événement d'origine, avec l'ajout de deux nouveaux paramètres, reason et original_request:

{
  "reason": "Connection closed.",
  "original_request": {
    "url": "https://api.example.com/webhooks/event",
    "type": "event"
  }
}

En cas de fermeture ou de réinitialisation de la connexion, de dépassement de délai ou de code d'état HTTP de 429, 503 ou 504 au cours de la phase initiale du NCCO, le answer_url est tentée deux fois, alors :

  1. Tenter d'atteindre le fallback_answer_url deux fois
  2. En cas d'échec, l'appel est interrompu.

En cas de fermeture ou de réinitialisation de la connexion, de dépassement de délai ou de code d'état HTTP de 429, 503 ou 504 pendant un appel en cours, le event_url pour les événements qui sont censés renvoyer un NCCO (par exemple, le retour d'un input ou notify ) est tentée deux fois, alors :

  1. Tenter d'atteindre le fallback_answer_url deux fois
  2. En cas d'échec, poursuivre le flux d'appels

Erreurs

Le point de terminaison de l'événement recevra également des webhooks en cas d'erreur. Cela peut être utile lors du débogage de votre application.

Champ d'application Exemple Description
reason Syntax error in NCCO. Invalid value type or action. Informations sur la nature de l'erreur
conversation_uuid CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab L'identifiant unique de cette conversation
timestamp 2020-01-01T12:00:00.000Z Horodatage (format ISO 8601)