Webhooks d'appels WhatsApp : événements Calling API et appels sur un numéro Coexistence
Le champ calls du webhook remonte les événements de la Calling API WhatsApp Business : connexion avec une réponse ou une offre SDP, statuts d'appel RINGING, ACCEPTED et REJECTED, fin avec COMPLETED ou FAILED et la durée, ainsi que call_recording_available ou call_transcription_available. Le guide Coexistence de Meta indique que les appels vocaux et vidéo restent inchangés dans l'application WhatsApp Business et ne sont pas pris en charge sur la Cloud API : ces appels restent donc sur le téléphone.
easyCoexistence relie votre numéro de l'application WhatsApp Business à la Cloud API de Meta via Coexistence, afin que votre IA et vos automatisations répondent aux messages et envoient des templates, tandis que les appels continuent de sonner dans l'application sur votre téléphone.
Appels vocaux et vidéo sur la Cloud API pour un numéro intégré avec l'application WhatsApp Business ; dans l'application, ils restent inchangés.
Limite quotidienne minimale de messagerie, en destinataires uniques, qu'un numéro doit atteindre avant de pouvoir utiliser la Calling API.
Durée pendant laquelle les enregistrements et transcriptions d'appels restent téléchargeables après la livraison de leur webhook.
Le préfixe des identifiants d'appel, la valeur qui relie les webhooks de connexion, de statut et de fin d'un même appel.
La permission qu'une application doit obtenir pour recevoir les webhooks d'appels, identique à celle des messages.
Que remonte le champ calls du webhook ?
Tout ce qui arrive à un appel passé ou reçu via la Calling API, dans un seul champ avec un événement par étape. Un appel initié par l'entreprise produit un événement de connexion, des mises à jour de statut et un événement de fin. Les appels gérés via SIP signalent call_created au lieu de connect, sans la session SDP. Un événement lié se trouve ailleurs : lorsqu'un client répond à une demande d'autorisation d'appel, la réponse arrive dans le champ messages, sous forme de message interactif de type call_permission_reply.
À quoi ressemble un webhook d'appel ?
La même enveloppe que tout webhook WhatsApp, avec un tableau calls sous value et field défini sur calls. direction indique BUSINESS_INITIATED ou USER_INITIATED, from et to contiennent les numéros de téléphone, to_user_id le BSUID du client, et l'un des numéros peut être absent pour un client qui utilise un nom d'utilisateur. metadata.phone_number_id identifie votre numéro, comme sur tout autre champ. Voici l'exemple Call Connect de Meta, avec les espaces réservés tels que Meta les affiche :
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
"changes": [
{
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "16315553601",
"phone_number_id": "<PHONE_NUMBER_ID>"
},
"contacts": [
{
"profile": {
"name": "<CALLEE_NAME>",
"username": "<USERNAME>"
},
"wa_id": "16315553602",
"user_id": "<BSUID>",
"parent_user_id": "<PARENT_BSUID>"
}
],
"calls": [
{
"id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
"to": "16315553601",
"to_user_id": "<BSUID>",
"to_parent_user_id": "<PARENT_BSUID>",
"from": "16315553602",
"event": "connect",
"timestamp": "1671644824",
"direction": "BUSINESS_INITIATED",
"session": {
"sdp_type": "answer",
"sdp": "<<RFC 8866 SDP>>"
}
}
]
},
"field": "calls"
}
]
}
]
}Quels champs l'événement terminate ajoute-t-il ?
terminate est l'événement que la plupart des systèmes stockent, car il clôt l'appel. Ses champs, selon la référence de Meta :
- status : COMPLETED lorsque l'appel s'est terminé sans erreur inattendue, y compris les appels sans réponse ; FAILED lorsqu'il n'a pas abouti ou s'est interrompu.
start_time,end_timeet duration en secondes : présents uniquement lorsque l'autre partie a décroché.- errors : code, message, href et
error_data.details sur un appel FAILED. biz_opaque_callback_data: votre propre chaîne de suivi, si vous en avez transmis une au lancement ou à l'acceptation de l'appel.
Les webhooks d'appel fonctionnent-ils sur un numéro Coexistence ?
Le guide Coexistence de Meta répond dans son tableau des fonctionnalités : pour un numéro intégré de cette façon, les appels vocaux et vidéo ne changent pas dans l'application WhatsApp Business et ne sont pas pris en charge sur la Cloud API. Les prérequis de la Calling API le confirment de l'autre côté : le numéro professionnel doit être utilisé avec la Cloud API, et non avec l'application WhatsApp Business. Sur un numéro Coexistence, les clients continuent donc d'appeler comme avant, l'appel sonne sur le téléphone dans l'application, et le champ calls n'a rien à remonter. Une entreprise qui a besoin des appels dans un logiciel utilise un numéro sur la Cloud API uniquement.
Comment les événements d'un même appel s'articulent-ils ?
Par l'identifiant d'appel, qui commence par wacid et se répète sur chaque événement de cet appel. Un appel initié par l'entreprise remonte une connexion avec la réponse SDP, les statuts RINGING puis ACCEPTED ou REJECTED, et enfin terminate. Un appel initié par l'utilisateur remonte une connexion avec une offre SDP que votre stack doit accepter, puis terminate. Les événements d'enregistrement et de transcription, lorsqu'ils sont activés, arrivent après terminate. Indexez les événements stockés sur id et event, car les tentatives répètent les envois et l'ordre d'arrivée n'est pas garanti. La liste complète des prérequis de la Calling API se trouve sur la page consacrée aux appels sur un numéro Coexistence.
Que peut faire votre IA pour les appels sur un numéro Coexistence ?
Travailler dans le chat, tandis que les appels restent avec la personne au téléphone. easyCoexistence ne s'abonne pas au champ calls et n'a aucun outil d'appel ; son connecteur et ses automatisations couvrent les messages et les templates. Concrètement, une réponse de l'IA peut indiquer au client quand quelqu'un est disponible pour parler et quel numéro appeler, une automatisation par mot-clé peut répondre « appel » ou « téléphone » avec ces informations, et le propriétaire prend l'appel dans l'application WhatsApp Business comme avant.
Erreurs courantes
- S'abonner à calls pour un numéro Coexistence et attendre des événements. Meta indique que les appels ne sont pas pris en charge sur la Cloud API pour ces numéros.
- Attendre start_time et duration sur chaque terminate. Ils n'apparaissent que si l'appel a reçu une réponse ; un appel sans réponse se termine tout de même en COMPLETED.
- Chercher les réponses d'autorisation dans le champ calls. Elles arrivent dans messages, sous forme de call_permission_reply interactif.
- Laisser les enregistrements et transcriptions chez Meta. Les deux peuvent être téléchargés pendant 7 jours après leur webhook, puis ils disparaissent.
Chaque numéro est surveillé 24/7, y compris la règle des 14 jours qui déconnecte un numéro dont l'application n'est pas ouverte. De US$ 9 à US$ 0,75 par numéro et par mois, dégressif à mesure que vous ajoutez des numéros, avec 3 jours d'essai gratuit.
Questions fréquemment posées
Les clients perdent-ils le bouton d'appel lorsqu'un numéro se connecte à l'API via Coexistence ?
Le guide Coexistence de Meta indique que les appels vocaux et vidéo restent inchangés dans l'application WhatsApp Business. Les clients appellent le même numéro, et le propriétaire répond depuis l'application sur son téléphone.
La Calling API est-elle tarifée comme les messages ?
Non. La page tarifaire de Meta indique que la Calling API a une tarification différente et renvoie vers un document distinct sur la tarification des appels ; les frais d'appel n'apparaissent donc pas dans l'objet pricing des statuts de message.
Un appel Calling API peut-il être enregistré ou transcrit ?
Oui, lorsque l'enregistrement ou la transcription est activé. Après l'appel, Meta envoie call_recording_available avec un identifiant de média audio, ou call_transcription_available avec un identifiant de document JSON, généralement dans la minute.
Un webhook d'appel peut-il être envoyé à un autre endpoint que celui de l'application ?
Oui. calls fait partie des champs que Meta permet à un compte WhatsApp Business ou à un numéro de téléphone d'acheminer vers une URL de rappel alternative, à côté de messages et des champs Coexistence.
Poursuivre la lecture
Prêt à commencer ?
Configurez WhatsApp Coexistence en quelques minutes, pas en quelques mois. L’application continue de fonctionner sur le téléphone.
Commencer l'essai gratuitVérifié le