WhatsApp-oproep-webhooks: Calling API-events en oproepen op een Coexistence-nummer
Het calls-webhookveld meldt events van de WhatsApp Business Calling API: verbinden met een SDP-antwoord of -aanbod, oproepstatussen RINGING, ACCEPTED en REJECTED, beëindigen met COMPLETED of FAILED en de duur, en call_recording_available of call_transcription_available. In de Coexistence-gids van Meta staan spraak- en video-oproepen als ongewijzigd in de WhatsApp Business-app en niet ondersteund op de Cloud API, dus die oproepen blijven op de telefoon.
easyCoexistence koppelt je WhatsApp Business-app-nummer via Coexistence aan de Cloud API van Meta, zodat je AI en automatiseringen berichten beantwoorden en templates versturen, terwijl oproepen op de app op je telefoon blijven overgaan.
Spraak- en video-oproepen op de Cloud API voor een nummer dat met de WhatsApp Business-app is aangesloten; in de app blijven ze ongewijzigd.
Minimale dagelijkse berichtlimiet, in unieke ontvangers, die een nummer nodig heeft voordat het de Calling API kan gebruiken.
Hoe lang opnames en transcripties na levering van hun webhook downloadbaar blijven.
Het voorvoegsel van oproep-id's, de waarde die de connect-, status- en terminate-webhooks van één oproep aan elkaar koppelt.
De permissie die een app nodig heeft om calls-webhooks te ontvangen, dezelfde als voor berichten.
Wat meldt het calls-webhookveld?
Alles wat er gebeurt met een oproep die via de Calling API is geplaatst of ontvangen, als één veld met een event per fase. Een door het bedrijf gestarte oproep levert een connect-event, statusupdates en een terminate-event op. Oproepen die via SIP worden afgehandeld, melden call_created in plaats van connect, zonder de SDP-sessie. Eén verwant event staat elders: wanneer een klant een verzoek voor oproeprechtigheid beantwoordt, komt het antwoord binnen op het messages-veld als interactief bericht van het type call_permission_reply.
Hoe ziet een calls-webhook eruit?
Dezelfde envelop als elke WhatsApp-webhook, met een calls-array onder value en field ingesteld op calls. direction geeft BUSINESS_INITIATED of USER_INITIATED aan, from en to bevatten de telefoonnummers, to_user_id de BSUID van de klant, en een van de nummers kan ontbreken bij een klant die een gebruikersnaam gebruikt. metadata.phone_number_id identificeert je nummer, zoals bij elk ander veld. Dit is het Call Connect-voorbeeld van Meta, met de plaatsaanduidingen zoals Meta ze afdrukt:
{
"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"
}
]
}
]
}Welke velden voegt het terminate-event toe?
terminate is het event dat de meeste systemen opslaan, omdat het de oproep afsluit. De velden, volgens de referentie van Meta:
- status: COMPLETED wanneer de oproep eindigde zonder onverwachte fouten, ook onbeantwoorde oproepen; FAILED wanneer hij niet tot stand kwam of wegviel.
start_time,end_timeen duration in seconden: alleen aanwezig wanneer de andere partij de oproep aannam.- errors: code, message, href en
error_data.details bij een FAILED-oproep. biz_opaque_callback_data: je eigen trackingstring, wanneer je er een meegaf bij het starten of accepteren van de oproep.
Werken calls-webhooks op een Coexistence-nummer?
De Coexistence-gids van Meta beantwoordt dit in de functietabel: spraak- en video-oproepen ondergaan geen wijziging in de WhatsApp Business-app en worden niet ondersteund op de Cloud API voor een nummer dat zo is aangesloten. De voorwaarden van de Calling API zelf zeggen hetzelfde vanuit de andere kant: het bedrijfsnummer moet in gebruik zijn bij de Cloud API, niet bij de WhatsApp Business-app. Op een Coexistence-nummer bellen klanten dus zoals voorheen, de oproep gaat over in de app op de telefoon, en het calls-veld heeft niets te melden. Een bedrijf dat oproepen in software nodig heeft, gebruikt een nummer uitsluitend op de Cloud API.
Hoe horen de events van één oproep bij elkaar?
Via de oproep-id, die begint met wacid en op elk event van die oproep terugkomt. Een door het bedrijf gestarte oproep meldt connect met het SDP-antwoord, statussen RINGING en daarna ACCEPTED of REJECTED, en tot slot terminate. Een door de gebruiker gestarte oproep meldt connect met een SDP-aanbod dat je stack moet beantwoorden, daarna terminate. Opname- en transcriptie-events, wanneer ingeschakeld, komen na terminate. Sla events op met id plus event als sleutel, want herhalingen komen voor en de aankomstvolgorde is niet gegarandeerd. De volledige lijst met voorwaarden voor de Calling API staat op de pagina over oproepen op een Coexistence-nummer.
Wat kan je AI doen met oproepen op een Coexistence-nummer?
Werken in de chat, terwijl oproepen bij de persoon aan de telefoon blijven. easyCoexistence abonneert zich niet op het calls-veld en heeft geen oproeptools; de connector en automatiseringen dekken berichten en templates. In de praktijk betekent dat: een AI-antwoord kan een klant laten weten wanneer iemand beschikbaar is om te bellen en welk nummer hij moet bellen, een trefwoordautomatisering kan antwoorden op ‘bellen’ of ‘telefoon’ met die informatie, en de eigenaar neemt de oproep aan in de WhatsApp Business-app zoals voorheen.
Veelgemaakte fouten
- Abonneren op calls voor een Coexistence-nummer en wachten op events. Meta vermeldt bellen als niet ondersteund op de Cloud API voor deze nummers.
- Verwachten dat start_time en duration op elk terminate-event staan. Ze verschijnen alleen wanneer de oproep is beantwoord; een onbeantwoorde oproep eindigt toch op COMPLETED.
- Permissieantwoorden zoeken op het calls-veld. Die komen binnen op messages, als interactief call_permission_reply.
- Opnames en transcripties bij Meta laten staan. Beide kunnen 7 dagen na hun webhook worden gedownload, daarna zijn ze weg.
Elk nummer wordt 24/7 bewaakt, inclusief de regel van 14 dagen die een nummer loskoppelt waarvan de app niet wordt geopend. US$ 9 tot US$ 0.75 per nummer per maand, dalend naarmate je nummers toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Verliezen klanten de belknop wanneer een nummer via Coexistence op de API wordt aangesloten?
De Coexistence-gids van Meta vermeldt spraak- en video-oproepen als ongewijzigd in de WhatsApp Business-app. Klanten bellen hetzelfde nummer en de eigenaar neemt op in de app op de telefoon.
Is de Calling API geprijsd zoals berichten?
Nee. De prijspagina van Meta zegt dat de Calling API een andere prijsstelling heeft en verwijst naar een apart prijsdocument voor oproepen, dus oproepkosten verschijnen niet in het pricing-object van berichtstatussen.
Kan een Calling API-oproep worden opgenomen of getranscribeerd?
Ja, wanneer opname of transcriptie is ingeschakeld. Na de oproep stuurt Meta call_recording_available met een audio-media-id of call_transcription_available met een JSON-document-id, meestal binnen een minuut.
Kan een calls-webhook naar een ander endpoint gaan dan dat van de app?
Ja. calls is een van de velden die Meta een WhatsApp Business Account of telefoonnummer toestaat door te sturen naar een alternatieve callback-URL, naast messages en de Coexistence-velden.
Lees verder
Klaar om te beginnen?
Stel WhatsApp Coexistence in enkele minuten in, niet maanden. De app blijft op je telefoon werken.
Start je gratis proefperiodeGeverifieerd op