> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/messaging/calling/inbound-calls/how-to-handle-inbound-calls.md). # How to Handle Inbound Calls In this documentation, you will learn: * [How to receive inbound calls and handle the **CONNECT webhook**](#connect-webhook) * [How to **pre-accept**, **accept**, **reject**, or **terminate** a call](#recommended-pre-accept-call) * [How to handle the **Call Terminated webhook**](#call-terminated-webhook) * [How to use **interactive voice call buttons** and **templates** to let users call your business](#call-buttons) * [Common errors and troubleshooting steps](#troubleshooting) ## Receiving a call {% stepper %} {% step %} ### Connect Webhook The webhook `CONNECT` is sent in near real-time, when the business receives an user initiated call. Webhook also includes the info to establish a connection via WebRTC. * This webhook is sent to signal the business to establish the call WebRTC connection by utilizing the /calls action=connect * This webhook contains the new SDP information to help with establishing WebRTC connection When user starts a call, the business gets a `CONNECT` webhook: ```json { "object": "whatsapp_business_account", "entry": [ { "id": "366634483210360", // WhatsApp Business Account ID associated with the business phone number "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { // ID and display number for the business phone number placing the call (caller) "phone_number_id": "436666719526789", "display_phone_number": "13175551399", }, "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", // The WhatsApp call ID "to": "16315553601", // The WhatsApp user's phone number (callee) "from": "13175551399", "event": "connect", "timestamp": "1671644824", "session": { "sdp_type": "offer", "sdp": "<>" } } ] }, "field": "calls" } ] } ] } ``` {% endstep %} {% step %} ### (Recommended): Pre-accept call To receive a call, business can establish an SDP answer. * Pre-accepting is recommended to optimize the setup process and allow media connection before it starts. * Media only starts flowing once a call is accepted. * Business have from 30 to 60 seconds to pre-accept a call, or accept with an API answer. Otherwise, the call will be terminated as “Not answered”. The purpose is to pre-establish a WebRTC connection to prevent audio clipping. **Endpoint:** Please use this [endpoint](/docs/messaging-api/api-reference/calling.md#post-calling-calls). ```json {' "messaging_product": "whatsapp", "call_id": "wacid.XXX", "action": "pre_accept", "session": { "sdp_type": "answer", "sdp": "...RFC 4566 SDP..." } } ``` Response: ```json { "success" : true } ``` {% endstep %} {% step %} ### Accept the call Businesses can accept a call using the following [endpoint](/docs/messaging-api/api-reference/calling.md#post-calling-calls): **Request body:** ```json { "messaging_product": "whatsapp", "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "action": "accept", "session" : { "sdp_type" : "answer", "sdp" : "<>" } } ``` This initiates media flow over the established WebRTC session. **Response:** ```json { "messaging_product": "whatsapp", "success" : true } ``` **Error:** ```json { "error": { "message": "", "type": "", "code": , } } ``` {% endstep %} {% step %} ### Reject or Hang Up You can also: * **Reject** the call (before answering): ```json { "action": "reject" } ``` * **Terminate** the call (after connecting): ```json { "action": "terminate" } ``` {% endstep %} {% step %} ### Call Terminated Webhook This webhook is received when the call ends for any reason. It includes metadata like duration, status (`COMPLETED` or `FAILED`), and `biz_opaque_callback_data` if provided: ```json { "object": "whatsapp_business_account", "entry": [ { "id": "", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "16505553602", "phone_number_id": "", }, "calls": [ { "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh", "to": "16315553601", "from": "16315553602", "event": "terminate" "direction": "BUSINESS_INITIATED", "biz_opaque_callback_data": "random_string", "timestamp": "1671644824", "status" : [FAILED | COMPLETED], "start_time" : "1671644824", "end_time" : "1671644944", "duration" : 120 } ], "errors": [ { "code": INT_CODE, "message": "ERROR_TITLE", "href": "ERROR_HREF", "error_data": { "details": "ERROR_DETAILS" } } ] }, "field": "calls" } ] } ] } ``` {% endstep %} {% endstepper %} ## Call Buttons ### **Interactive Voice Call Button** Sent via interactive message or a template, you can call this API to send a message to consumers to raise awareness of the calling support using an inline button embedded within a text message or template: [#message-with-call-button](#message-with-call-button "mention") [#template-with-call-button](#template-with-call-button "mention") #### Message with call button {% stepper %} {% step %} You can use the following endpoint and body to send a message with call button: **Endpoint:** Please use this [endpoint](/docs/messaging-api/api-reference/messages.md#post-messages). **Request body:** ```json { "messaging_product": "whatsapp", "recipient_type": "individual", "to": "{{recipient-phone-number}}", "type": "interactive", "interactive": { "type": "voice_call", "body": { "text": "You can call us on WhatsApp now for faster service!" }, "action": { "name": "voice_call", "parameters": { "display_text": "Call on WhatsApp", "ttl_minutes": 100 // Expected value is an Integer value between 1 and 43200 (30 days) } } } } ``` {% endstep %} {% step %} The client will visualize the following:

Send interactive message with WhatsApp Call Button

{% endstep %} {% step %} When clicked, the API initiates a WhatsApp call to the sending business number. This behavior is the same as a consumer clicking the phone/call icon in the chat title bar. {% endstep %} {% endstepper %} #### Template with Call button {% stepper %} {% step %} To create the template you can use the following example cURL: 
curl --location 'https://waba-v2.360dialog.io/v1/configs/templates' \
--header 'Content-Type: application/json' \
--header 'D360-API-KEY: {YOUR-D360-API-KEY}' \
--data '{
    "name": "calling_template",
    "category": "MARKETING",
    "language": "en_US",
    "components": [
        {
            "type": "BODY",
            "text": "You can call us on WhatsApp now for faster service!"
        },
        {
            "type": "BUTTONS",
            "buttons": [
                {
                    "type": "VOICE_CALL",
                    "text": "Call Now"
                },
                {
                    "type": "URL",
                    "text": "Contact Support",
                    "url": "https://www.360dialog.com/contact "
                }
            ]
        }
    ]
}'
{% endstep %} {% step %} To send the template, use: ```json curl --location 'https://waba-v2.360dialog.io/messages' --header 'Content-Type: application/json' --header 'D360-API-KEY: {YOUR-D360-API-KEY}' --data '{ "to": {{recipient-phone-number}}, "messaging_product": "whatsapp", "type": "template", "recipient_type": "individual", "template": { "name": "calling_template", "language": { "code": "en_US" }, "components": [ { "type": "button", "sub_type": "voice_call", "parameters": [ { "type": "ttl_minutes", "ttl_minutes": 100 } ] } ] } }' ``` {% endstep %} {% step %} The user will be able to see the following screen:

Send a template with WhatsApp Call Button

{% endstep %} {% step %} When clicked, the API initiates a WhatsApp call to the sending business number. This behavior is the same as a consumer clicking the phone/call icon in the chat title bar. {% endstep %} {% endstepper %} {% hint style="info" %} There is no support for the button to WhatsApp call a different phone number. {% endhint %} *** ## Troubleshooting Please, check the following table with errors and solutions. If you can't find your case, you can contact our Support team:[Get support](/docs/support/get-support.md). | Error Code | Description | Possible solutions | Http Status Code | | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | |

138000
Calling not enabled

| Calling APIs are not enabled for this phone number |

WhatsApp CloudAPI Calling APIs are currently only available to select WhatsApp Business platform partners.
Reach out to the Whatsapp Business team to find out more.

| 401 Unauthorized | |

138002
Concurrent Calls limit

| Limit reached for maximum concurrent calls for the given number | Try again later or reduce the frequency or amount of API calls the app is making. |

429
Too many requests

| | 138003 Duplicate call | A call is already ongoing with the receiver | Try again later when the current call ends. |

400
Bad Request

| | 138004 Connection error | Error while connecting the call | Try again later or investigate the connection params provided to the API | 500 | |

138005
Call rate limit exceeded

| Limit reached for maximum calls that can be initiated by the business phone number | Try again later or reduce the frequency or amount of API calls the app is making. |

429
Too many requests

| | 131009 | Interactive Message type, 'voice\_call' not supported. Supported types \['button', 'list’] | Ensure the sender in one of the supported countries. |

400
Bad Request

| | 131044 | An error webhook is sent on user initiated calls when there is no valid payment method attached | This is similar to the "Business eligibility payment issue" error in messaging. |

400
Bad Request

| |

138006
No approved call permission found

| No approved call permission from the recipient | Ensure a call permission has been accepted by the consumer | 401 Unauthorized | |

138007
Connect Timeout error

| Call was unable to connect due to a timeout |

Business did not apply the offer/answer SDP from Cloud API in time.
Connect API was not invoked with the answer SDP in time

| 500 | |

138009
Call Permission Request Limit Hit

| Limit reached for call permission request sends for the given business and consumer pair | When a business sends more than the limit of call permission requests per time period, Call Permission Requests are rate limited. A connected call with a consumer will reset the limits. | 400 | |

138010
Business Initiated Calls Per Approved Permission Limit Hit

| Limit reached for business initiated calls per approved permission request, for the given business and consumer pair | When business attempts more that the limit of calls per approved call permission request, we will rate limit the business initiated calls. | 400 | |

138011
Unable to send Call permission request

| Unable to send a call permission request message | Attempt was made to send a call permission request message without an open customer service window |

400
Bad Request

| |

100
Invalid Parameter

| The GraphAPI call you are making has an invalid parameter. |

Exact error details will be listed in the error\_data section of the response payload.

If its SDP Validation related error then the exact issue will be included in the details.

|

400
Bad Request

| |

138012
Business Initiated Calls Limit Hit

| Limit reached for maximum business initiated calls allowed in 24 hours. Currently 5 connected business initiated calls are allowed within 24 hours. |

Exact error details will be listed in the error\_data section of the response payload.

Details will include a timestamp when the next call is allowed.

| 400 | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.360dialog.com/docs/messaging/calling/inbound-calls/how-to-handle-inbound-calls.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.