WhatsApp calls webhooks: Calling API events, and calls on a Coexistence number
The calls webhook field reports WhatsApp Business Calling API events: connect with an SDP answer or offer, call statuses RINGING, ACCEPTED and REJECTED, terminate with COMPLETED or FAILED and the duration, and call_recording_available or call_transcription_available. Meta's Coexistence guide lists voice and video calls as unchanged in the WhatsApp Business app and not supported on the Cloud API, so those calls stay on the phone.
easyCoexistence connects your WhatsApp Business app number to Meta's Cloud API through Coexistence, so your AI and automations answer messages and send templates while calls keep ringing in the app on your phone.
Voice and video calls on the Cloud API for a number onboarded with the WhatsApp Business app; in the app they are unchanged.
Minimum daily messaging limit, in unique recipients, a number needs before it can use the Calling API.
How long call recordings and transcripts stay downloadable after their webhook is delivered.
The prefix of call ids, the value that ties a call's connect, status and terminate webhooks together.
The permission an app needs to receive calls webhooks, the same as for messages.
What does the calls webhook field report?
Everything that happens to a call placed or received through the Calling API, as one field with an event per stage. A business-initiated call produces a connect event, status updates and a terminate event. Calls handled over SIP report call_created instead of connect, without the SDP session. One related event lives elsewhere: when a customer answers a call permission request, the reply arrives on the messages field as an interactive message of type call_permission_reply.
What does a calls webhook look like?
The same envelope as every WhatsApp webhook, with a calls array under value and field set to calls. direction says BUSINESS_INITIATED or USER_INITIATED, from and to carry the phone numbers, to_user_id the customer's BSUID, and either number can be missing for a customer who uses a username. metadata.phone_number_id identifies your number, as on any other field. This is Meta's Call Connect example, placeholders as Meta prints them:
{
"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"
}
]
}
]
}Which fields does the terminate event add?
terminate is the event most systems store, because it closes the call. Its fields, per Meta's reference:
- status: COMPLETED when the call ended without unexpected errors, unanswered calls included; FAILED when it did not connect or broke.
start_time,end_timeand duration in seconds: present only when the other party picked up.- errors: code, message, href and
error_data.details on a FAILED call. biz_opaque_callback_data: your own tracking string, when you passed one when starting or accepting the call.
Do calls webhooks work on a Coexistence number?
Meta's Coexistence guide answers this in its feature table: voice and video calls see no change in the WhatsApp Business app and are not supported on the Cloud API for a number onboarded this way. The Calling API's own prerequisites say the same from the other side: the business number must be in use with the Cloud API, not the WhatsApp Business app. So on a Coexistence number customers keep calling as before, the call rings in the app on the phone, and the calls field has nothing to report. A business that needs calls in software uses a number on the Cloud API alone.
How do the events of one call fit together?
By the call id, which starts with wacid and repeats on every event of that call. A business-initiated call reports connect with the SDP answer, statuses RINGING and then ACCEPTED or REJECTED, and finally terminate. A user-initiated call reports connect with an SDP offer for your stack to answer, then terminate. Recording and transcript events, when enabled, come after terminate. Key stored events on id plus event, since retries repeat them and arrival order is not promised. The full list of Calling API prerequisites is on the page about calls on a Coexistence number.
What can your AI do about calls on a Coexistence number?
Work in the chat, while calls stay with the person on the phone. easyCoexistence does not subscribe to the calls field and has no call tools; its connector and automations cover messages and templates. In practice that means an AI reply can tell a customer when someone is available to talk and which number to call, a keyword automation can answer "call" or "phone" with that information, and the owner takes the call in the WhatsApp Business app as before.
Common mistakes
- Subscribing to calls for a Coexistence number and waiting for events. Meta lists calling as not supported on the Cloud API for these numbers.
- Expecting start_time and duration on every terminate. They appear only when the call was answered; an unanswered call still ends COMPLETED.
- Looking for permission replies on the calls field. They arrive on messages, as an interactive call_permission_reply.
- Leaving recordings and transcripts with Meta. Both can be downloaded for 7 days after their webhook, then they are gone.
Every number is monitored 24/7, including the 14-day rule that disconnects a number whose app is not opened. US$ 9 down to US$ 0.75 per number per month, falling as you add numbers, with the first 3 days free.
easyCoexistence is a multichannel API and MCP server that connects AI agents such as Claude and ChatGPT to WhatsApp, Instagram, TikTok, Facebook and more. On WhatsApp it uses Coexistence: the business keeps using its number in the WhatsApp Business app while the AI works through Meta's official API.
Frequently asked questions
Do customers lose the call button when a number connects to the API through Coexistence?
Meta's Coexistence guide lists voice and video calls as unchanged in the WhatsApp Business app. Customers call the same number, and the owner answers in the app on the phone.
Is the Calling API priced like messages?
No. Meta's pricing page says the Calling API has different pricing and points to a separate calling pricing document, so call charges do not appear in the pricing object of message statuses.
Can a Calling API call be recorded or transcribed?
Yes, when recording or transcription is enabled. After the call, Meta sends call_recording_available with an audio media id or call_transcription_available with a JSON document id, usually within a minute.
Can a call webhook go to a different endpoint than the app's?
Yes. calls is one of the fields Meta lets a WhatsApp Business Account or phone number route to an alternate callback URL, alongside messages and the Coexistence fields.
Keep reading
Ready to get started?
Set up WhatsApp Coexistence in minutes, not months. The app keeps working on the phone.
Start Free TrialVerified on