Business-Initiated WhatsApp Calls

This guide explains how a business can initiate a WhatsApp voice call to a user, following consent and compliance requirements.

Overview

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

How to Initiate a Call

Request User Call Permission

An end-user may approve, decline, or not respond to a call permission request.

The user may also change their response (i.e. decline a granted permission request or grant a declined permission request) at any time before the call permission request expires.

Webhook: User Response to Call Permission

Business will receive a webhook when the user accepts or rejects your permission request:

event: call_permission_status
status: GRANTED, REJECTED, REVOKED

Receiving a Call Permission Approval Response

Receiving a Call Permission Rejection Response

Enable Callback Permission Status in call settings

When callback_permission_status is enabled, the user automatically provides call permission to your business when they place a call to you.

The call permission request expires when any of the following occurs:

When the consumer interacts with a subsequent new call permission request to the business
7 days after the permission was accepted or declined by the consumer
7 days after the permission was delivered if the consumer does not respond to the request

The permission must be requested and granted before initiating a call. You can request permission in two ways — by sending an Interactive Message with a Call Permission Request, or by sending a template message with a call permission button:

Initiate the Call

Once permission is granted, you can initiate the call.

Endpoint:

POST https://alpha-beta-onboarding.hub-production.360dialog.io/calling/calls/{phone_number_id} --header 'D360-API-KEY: ••••••'

{
  "messaging_product": "whatsapp",
  "to": {recipient-phone-number},
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 4566 SDP"
  }
}

If there are no errors, you will receive a successful response:

{
  "messaging_product": "whatsapp",
  "calls" : [
     "id" : "wacid.HBgLMTIxODU1NTI4MjgVAgARGCAyODRQIAFRoA", // The WhatsApp call ID
   ]
}

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

Appropriate Status Webhook

{
  "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"
}

Business Initiated Calls using SIP

Prerequisites

You have the required call permission approval from the WhatsApp user
- Learn how to obtain user calling permissions

Calling flow

Send an initial SIP INVITE to our servers

Our SIP domain is wa.meta.vc

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.

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)

Send the SIP INVITE to the WhatsApp user number you want to call

For more details, access Meta Official Documentation.

Limits & Rules

Call permission lasts 7 days or until manually revoked
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.

PreviousUser-Initiated WhatsApp Calls NextCommerce & Payments

Last updated 7 hours ago

Was this helpful?