Outbound Calls

In this documentation, you will learn:

• How business-initiated calls work through the Cloud API

• Which call status events are received via webhook (ringing, accepted, rejected, terminated)

• The limits and rules for Call Permission Requests (CPRs)

About Outbound Calls

Business-initiated calls allow a business to reach users by triggering a voice call through the Cloud API — but only after the user grants permission:

• Calls are initiated by the business with a WebRTC offer

• The user receives a ringing call in their WhatsApp app

• The user must have granted call permission to the business

To illustrate this better, please, see the flow below to understand the how it works:

Calling flow

1

Before initiating a call, you will need to send a SIP INVITE to Meta servers

Meta's SIP domain is wa.meta.vc

Example:

To initiate a call to WhatsApp user with phone number 11234567890, the SIP request URI should be sip:[email protected];transport=tls .

• This request will fail with an “SIP 407 Proxy Authentication required” message.

2

Then, you send a 2nd SIP INVITE with Authorization header as per RFC 3261

The Authorization field’s username attribute must match the from header’s user name which is the business phone number:

• The password is generated by Meta and you can retrieve it using get Call Settings endpoint

• The username portion of the from header must be the fully normalized business phone number

• The domain name of the from header must match the SIP server you configured on the business phone number

• The SDP Offer you include supports ICE, DTLS-SRTP and OPUS (essentially WebRTC media)

3

At last, you will need to send the SIP INVITE to the WhatsApp user number you want to call

For more details, access Meta Official Documentation.

Webhook: Call Status Events

After successful initiation of a new call, you will receive Call Connect Webhook response that contains SDP Answer from Cloud API. Your business will then apply the SDP Answer from this webhook to your WebRTC stack in order to initiate the media connection.

Call Connect Webhook

{
    "entry": [
        {
            "changes": [
                {
                    "field": "calls",
                    "value": {
                        "calls": [
                            {
                                "biz_opaque_callback_data": "TRx334DUDFTI4Mj", // Arbitrary string passed by business for tracking purposes
                                "session": {
                                    "sdp_type": "answer",
                                    "sdp": "<RFC 8866 SDP>"
                                },
                                "from": "13175551399", // The business phone number placing the call (caller)
                                "connection": {
                                    "webrtc": {
                                        "sdp": "<RFC 8866 SDP>"
                                    }
                                },
                                "id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA", // The WhatsApp call ID
                                "to": "12185552828", // The WhatsApp user's phone number (callee)
                                "event": "connect",
                                "timestamp": "1749196895",
                                "direction": "BUSINESS_INITIATED"
                            }
                        ],
                        "metadata": { // ID and display number for the business phone number placing the call (caller)
                            "phone_number_id": "436666719526789",
                            "display_phone_number": "13175551399"
                        },
                        "messaging_product": "whatsapp"
                    }
                }
            ],
            "id": "366634483210360" // WhatsApp Business Account ID associated with the business phone number
        }
    ],
    "object": "whatsapp_business_account"
},

After initiating the call, you may receive these statuses:

• RINGING: Call is ringing on the user's device

• ACCEPTED: User accepted the call

• REJECTED: User rejected the call

• TERMINATE: Call ended for any reason

The appropriate Status Webhook will be:

{
  "entry": [
    {
      "changes": [
        {
          "field": "calls",
          "value": {
            "statuses": [
              {
                "id": "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA", // The WhatsApp call ID
                "type": "call",
                "status": "[RINGING|ACCEPTED|REJECTED]", // The current call status
                "timestamp": "1749197000",
                "recipient_id": "12185552828" // The WhatsApp user's phone number (callee)
              }
            ],
            "metadata": { // ID and display number for the business phone number placing the call (caller)
              "phone_number_id": "436666719526789",
              "display_phone_number": "13175551399"
            },
            "messaging_product": "whatsapp"
          }
        }
      ],
      "id": "366634483210360" // WhatsApp Business Account ID associated with the business phone number
    }
  ],
  "object": "whatsapp_business_account"
}

Limits & Rules

For every CPR you should observe the following rules:

• A call permission lasts 7 days or until manually revoked

• The business may initiate up to 5 calls per 24h per user

• 2 consecutive unanswered calls result in system message to reconsider an approved permission

• Permission is revoked automatically after 4 unanswered calls

• Maximum 2 permission requests within 7 days.

  • These limits reset when any connected call (business-initiated/user-initiated) is made between the business and WhatsApp user.

  • These limits apply toward permissions requests sent either as free form or template messages.