Official API (CALLING)

Context

WhatsApp Business Calling adds the VoIP communication channel in addition to text messaging between consumers and businesses. Consumers use the WhatsApp application as in Consumer-to-Consumer Calls, while the business interacts with the WhatsApp API through the Graph API for signaling and initial call connection.

Value proposition

WhatsApp Business Calling enables businesses to initiate and receive calls with WhatsApp users using Voice over Internet Protocol (VoIP), with global reach.

Note: * Feature planned or in development. Reach out to your Meta or partner for more details.

Architecture

Possible signaling and media configurations

Notes:

1. You can also use SDES instead of ICE+DTLS with Graph API + Webhook signaling.
2. Additional audio codecs supported: PCMA, PCMU.

Get started

Prerequisites

1. Your business number must be in use with Cloud API (not the WhatsApp Business app).
2. Subscribe your app to the calls webhook field (unless you plan to use SIP).
3. The same app must be subscribed to the WhatsApp Business account of your business phone number.
4. The app must have messaging permissions (whatsapp_business_messaging) for the business number.
5. The business must have a daily messaging limit of at least 2,000 unique recipients.
6. Enable Calling features on your business phone number.

Configure calling features

The API offers features that affect when and how calling features appear to users on your WhatsApp profile:

• Inbound call control: allows you to prevent users from placing calls from your business profile.
• Business call hours: lets you avoid missed calls and direct users to message when your call center is closed.
• Callback requests: offer users the option to request a callback when you don’t pick up a call or if your call center is closed.

Make and receive calls

Cloud API Calling offers two call initiation paths:

• User-initiated calls: calls made from a WhatsApp user to your business.
• Business-initiated calls: calls made from your business to a WhatsApp user.

Testing and sandbox accounts

Warning: Sandbox accounts are only available to Tech Partners.

Overview

A WhatsApp sandbox account is a mock WhatsApp Business account that you can use to test your Calling API integration. Use a calling sandbox account to test the following features:

• Initiate and receive calls using the Calling API.
• Validate calling webhook events.
• Simulate onboarding flows without creating real business assets.

Sandbox account calling limits

The following table outlines the calling limits for sandbox accounts. These limits are subject to change.

Set up a sandbox account

Step 1. Claim a sandbox account

Follow the instructions in Embedded Signup Overview — Claiming sandbox accounts to claim your sandbox account.

Step 2. Obtain credentials and identifiers for your sandbox account

1. In the App Dashboard, navigate to your app, then select WhatsApp > Embedded Signup Builder in the sidebar.
   • Note: Keep this tab open and available as you will use it multiple times throughout this process.
2. Ensure that the Features dropdown is empty, then click Login with Facebook.
3. A popup with the Embedded Signup experience will show. Under Business portfolio select Sandbox Business.
4. Fill in the rest of the required information, then click Next.
5. On the next screen, in the Create or Select a WhatsApp Business Profile dropdown, select Test Number.
6. Once the login flow is complete, in the Exchange Token section, click Get Token.
   • Note: Retain this token for future sandbox account API use.
7. In the Fetch Shared WhatsApp Business account section, click Fetch WABA details.
8. Under WhatsApp Business account field, copy the Value for the id row.
   • Note: Retain this ID since it is the WhatsApp Business account ID for the sandbox WABA.
9. In the Fetch phone numbers section, click Fetch phone numbers.
10. Under ID, copy the value.
    • Note: Retain this ID since it is the phone number ID for your sandbox account test phone number.

Step 3. Register your test phone number and subscribe to your WABA

Prerequisites

Ensure that you have the following information from the previous steps:

• Your sandbox account token string
• Your sandbox account WABA ID
• Your test phone number ID

To complete these next steps, you will use the Graph API Explorer tool.

• Note: Keep this window open as you will use the configuration you created again in later steps in this guide.

1. Navigate to the Graph API Explorer tool.
2. Ensure you are on the latest version of the API.
3. Click Generate Access Token and follow the prompts.
4. Under Permissions, add the whatsapp_business_management and whatsapp_business_messaging permissions.
5. In the endpoint builder, enter /<YOUR_SANDBOX_WABA_ID>/subscribed_apps, then click Submit.

{
  "success": true
}

6. Next, register your test phone number by entering /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/register in the endpoint builder.
7. In the left sidebar, click JSON, then enter the following JSON body, then click Submit:

{
  "messaging_product": "whatsapp",
  "pin": "123456"
}

8. You should receive a standard success response:

{
  "success": true
}

Step 4. Test your messaging functionality

1. In the Graph API Explorer tool, enter /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/messages in the endpoint builder.
2. In the left sidebar, click JSON, then enter the following JSON body, then click Submit:

{
  "messaging_product": "whatsapp",
  "to": "YOUR_NUMBER", // Replace this value with phone number of your device.
  "recipient": "US.13491208655302741918",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

Note: Usernames and business-scoped user IDs: The recipient field lets you identify the WhatsApp user by their BSUID instead of, or in addition to, their phone number in to. For details, see Business-scoped user IDs.

3. You will receive a response with a "message_status": "accepted" value, and you should receive a text message on your device.

Step 5. Configure webhooks and permissions

• Navigate to the App Dashboard.
• Click the app you are using with WhatsApp.
• Select Use cases (pencil icon) from the sidebar.
• Under Connect with customers through WhatsApp, click Customize.
• In the left sidebar, click Configuration.
• Under Callback URL, add the callback URL for your webhook server.
  • If you do not have a webhook server, you can follow our instructions to create a test webhook server.
• Under Verify token, add an arbitrary verification string.
• Click Verify and save.
• On the next page, in the Select product dropdown, click WhatsApp Business Account.
• Under Webhook fields, in the calls row, click the toggle button to subscribe to the calls webhook field.

Finish: Enable calling features on your test phone number

1. In the Graph API Explorer tool, enter /<YOUR_SANDBOX_TEST_PHONE_NUMBER_ID>/settings in the endpoint builder.
2. In the left sidebar, click JSON, then enter the following JSON body, then click Submit:

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED"
  }
}

3. You should receive a standard success response:

{
  "success": true
}

4. Finally, under Access Token, copy the access token down for future use.
   • Note: Retain this access token as you will use it to make API calls for testing your Calling API integration.

Test business-initiated calling

Before you can test business-initiated calls (BIC), you must provide user calling permissions to your sandbox account.

You can do this on the client device you are using for testing:

1. On your client device, open WhatsApp.
2. Navigate to the message thread you have with your sandbox business phone number.
3. At the top of the screen, tap the sandbox business phone number.
4. Scroll down and tap Business Calling Permission.
5. Tap Allow calls.

You can now use your Calling API integration to call the client device and test your integration.

Learn more about business-initiated calls.

Test user-initiated calling

You can test user-initiated calls (UIC) on the client device you are using for testing:

1. On your client device, open WhatsApp.
2. Navigate to the message thread you have with your sandbox business phone number.
3. Tap the phone icon at the top of the screen to call the sandbox business phone number.
4. Confirm a successful call connection.

Learn more about user-initiated calls.

Availability

User-initiated calling

Available in every location Cloud API is available.

Business-initiated calling

Available in every location Cloud API is available, except the following countries:

• United States
• Canada
• Egypt
• Vietnam
• Nigeria

Note: the business phone number’s country code must be in this supported list. The consumer phone number can be from any country where Cloud API is available.

Changelog

Call settings

Use these APIs to view and manage the call configuration of your business phone numbers. By default, calls are not enabled on a business phone number.

Update settings

Updates the call settings of a phone number: enable or disable the feature, control the icon visibility, define the operating hours and the holiday overrides.

Endpoint: POST /calls/{v}/{did}/settings

Request:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/calls/v21.0/{did}/settings' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "ENABLED",
      "call_icon_visibility": "DEFAULT",
      "call_icons": {
        "restrict_to_user_countries": ["US", "BR"]
      },
      "call_hours": {
        "status": "ENABLED",
        "timezone_id": "America/Manaus",
        "weekly_operating_hours": [
          {
            "day_of_week": "MONDAY",
            "open_time": "0400",
            "close_time": "1020"
          }
        ],
        "holiday_schedule": [
          {
            "date": "2026-01-01",
            "start_time": "0000",
            "end_time": "2359"
          }
        ]
      },
      "callback_permission_status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [
          {
            "hostname": "sip.example.com",
            "port": 5061,
            "request_uri_user_params": {
              "KEY1": "VALUE1"
            }
          }
        ]
      },
      "audio": {
        "additional_codecs": ["PCMA", "PCMU"]
      },
      "voicemail": {
        "status": "ENABLED",
        "triggers": ["REJECT", "TIMEOUT"],
        "audio": {
          "default": {
            "announcement_media_id": 938884519013664,
            "timeout_seconds": 20
          }
        }
      }
    }
  }'

Response (200):

{
  "success": true
}

calling node parameters:

Configuration propagation note: after updating call configuration, WhatsApp users may take up to 7 days to reflect the changes. Most users refresh much sooner. You can force an immediate refresh by entering your business chat and opening the chat info page. Regardless of client behavior, the server always honors the configured settings.

Icon visibility behavior:

• DEFAULT: the call icon is shown at every call entry point (chat menu and business info).

• DISABLE_ALL: the icon is hidden in the chat menu and business info window. All entry points outside the chat are also disabled. You can still send interactive messages or templates with a call button (Call CTA).

• Call hours (call_hours): calls outside the configured schedule (or within holiday/unavailability periods) are blocked. The client error screen shows the option to chat with the business, request a callback (if enabled) and the next available time.

• Callback permissions (callback_permission_status): a business-initiated call requires explicit user permission. The account can be configured to automatically trigger the call permission request UI after an unanswered user-initiated call. The user can change their selection at any time.

• Planned change (ETA June 2025) — proactive permissions: the consumer app will automatically send an approved call permission when a user initiates a call to the business, regardless of the result. The user can change this selection at any time. This change is transparent for the integration.

Errors:

Get settings

Endpoint: GET /calls/{v}/{did}/settings

Optionally, you can include SIP credentials in the response with the include_sip_credentials=true query param:

GET /calls/{v}/{did}/settings?include_sip_credentials=true

Response (200):

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "call_hours": {
      "status": "ENABLED",
      "timezone_id": "America/Manaus",
      "weekly_operating_hours": [
        {
          "day_of_week": "MONDAY",
          "open_time": "0400",
          "close_time": "1020"
        }
      ],
      "holiday_schedule": []
    },
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    },
    "audio": {
      "additional_codecs": ["PCMA", "PCMU"]
    },
    "voicemail": {
      "status": "ENABLED",
      "triggers": ["REJECT", "TIMEOUT"],
      "audio": {
        "default": {
          "announcement_media_id": 938884519013664,
          "timeout_seconds": 20
        }
      }
    }
  }
}

Response with restrictions: if your business has restrictions enforced, the response includes the restrictions object:

{
  "calling": {
    "status": "ENABLED",
    "restrictions": {
      "restrictions_list": [
        {
          "type": "RESTRICTED_BUSINESS_INITIATED_CALLING",
          "reason": "Business initiated calling capability has been temporarily disabled for this phone number due to high negative feedback from users.",
          "expiration": 1754072386
        }
      ]
    }
  }
}

Possible type values are RESTRICTED_BUSINESS_INITIATED_CALLING or RESTRICTED_USER_INITIATED_CALLING. expiration is the Unix timestamp UTC when the restriction expires.

Voicemail

When voicemail is enabled, Cloud API:

1. Waits for the configured delay or a reject signal from you.
2. Automatically answers the call.
3. Plays an audio announcement.
4. Records the caller’s voicemail.
5. Delivers the voicemail as an audio message via webhook.

Note: when voicemail is enabled, turn off call hours (call_hours), because WhatsApp users cannot place calls outside business hours. Calling must be enabled on the phone number for the voicemail setting to take effect.

Upload the announcement media

Voicemail announcement files must be uploaded through the Media Upload API with use_case=call_voicemail_announcement, which skips the standard 30-day TTL:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/{v}/{did}/media' \
  --header 'Authorization: Bearer <token>' \
  -F 'file=@<FILE_PATH>;type=audio/ogg' \
  -F 'messaging_product=whatsapp' \
  -F 'use_case=call_voicemail_announcement' \
  -F 'description="Default announcement (English)"'

Media requirements: duration under 60 seconds, MIME audio/ogg with the OPUS codec. Media uploaded with this use_case can only be used as a voicemail announcement, not as a regular message.

Voicemail webhooks

When a user leaves a voicemail, Cloud API delivers the audio through the messages webhook field as an inbound audio message. The difference from a regular audio message: messages[].id contains the call ID (WACID) that produced the voicemail, not a WAMID. Use that ID to correlate the voicemail with the call lifecycle webhooks.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_PHONE_NUMBER>"
            },
            "contacts": [
              {
                "wa_id": "<USER_PHONE_NUMBER>",
                "profile": { "name": "<USER_PROFILE_NAME>" }
              }
            ],
            "messages": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyASG...",
                "from": "<USER_PHONE_NUMBER>",
                "timestamp": "1728932177",
                "type": "audio",
                "audio": {
                  "id": "1002764438271669",
                  "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                  "mime_type": "audio/ogg; codecs=opus"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Delivery is best-effort: if voicemail collection fails, no voicemail webhook is sent for that call. No additional subscription is required beyond the standard messages field.

Settings update webhooks

Subscribe to the account_settings_update webhook field to get notified on phone number settings updates. Currently only call settings changes are observed: status, call_icon_visibility, callback_permission_status, sip.status and srtp_key_exchange_protocol.

Requirements: subscribe to account_settings_update, the app must be subscribed to the WABA of the number, and have whatsapp_business_management permission.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "timestamp": "1671644824",
            "type": "phone_number_settings",
            "phone_number_settings": {
              "phone_number_id": "phone-number-id",
              "calling": {
                "status": "ENABLED",
                "call_icon_visibility": "DEFAULT",
                "callback_permission_status": "ENABLED"
              }
            }
          },
          "field": "account_settings_update"
        }
      ]
    }
  ]
}

Calling restrictions for user feedback

If your calls receive high negative user feedback (blocks and reports), business-initiated calling, user-initiated calling, or both can be restricted.

Early warning

You are notified when the number is close to being paused, via email and the account_update webhook:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1623862418,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PN",
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "LOW_BUSINESS_INITIATED_CALLING_QUALITY"
            }
          }
        }
      ]
    }
  ]
}

Pause in calling functionality

When negative feedback reaches the threshold, Cloud API automatically restricts the functionality for 7 days. While paused:

• Business-initiated calls: cannot make calls to the user or send permission requests.
• User-initiated calls: cannot receive calls or show the call icon.

Permissions approved or declined by users while paused remain valid.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "PN",
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
              {
                "restriction_type": "RESTRICTED_BUSINESS_INITIATED_CALLING",
                "expiration": 1641848057
              }
            ]
          }
        }
      ]
    }
  ]
}

Calling restrictions for low call pickup rates

When inbound calls are frequently not picked up, you are notified and the call button may be hidden.

Warning: email with options to change how you handle incoming calls.

Restriction: if the situation persists, the call button is hidden from users. To mitigate: identify the cause of unanswered calls and ensure enough resources, or disable buttons / calls via WhatsApp Manager.

Warning webhook:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505552771",
            "event": "ACCOUNT_VIOLATION",
            "violation_info": {
              "violation_type": "USER_INITIATED_CALLS_LOW_PICKUP_RATE",
              "remediation": "Please identify and address the cause of user-initiated calls not being picked up."
            }
          }
        }
      ]
    }
  ]
}

Enforcement webhook:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "0",
      "time": 1641848059,
      "changes": [
        {
          "field": "account_update",
          "value": {
            "phone_number": "16505552771",
            "event": "ACCOUNT_RESTRICTION",
            "restriction_info": [
              {
                "restriction_type": "RESTRICTED_USER_INITIATED_CALLING_CALL_BUTTON_HIDDEN",
                "remediation": "The call button has been hidden due to low pickup rates."
              }
            ]
          }
        }
      ]
    }
  ]
}

Consumer-initiated calls

The Calling API supports receiving calls made by WhatsApp users to your business. Your business dictates when calls can be received by configuring call hours and holiday unavailability.

The user-initiated call flow is:

1. The user calls your business — you receive the Connect webhook with an SDP Offer.
2. Pre-accept (recommended) — establishes the media connection before sending media, avoiding audio clipping.
3. Accept — once the WebRTC connection is established, accept the call. Media flows immediately after the 200 OK.
4. Terminate — either you or the user can hang up. You receive the Terminate webhook.

You have approximately 30 to 60 seconds after the Connect webhook to respond. If you do not respond, the call is terminated on the user side with a “Not Answered” notification and a termination webhook is delivered.

Pre-accept

Answer a user-initiated call by pre-accepting it. It eases call setup and avoids audio clipping: it establishes the WebRTC connection before accepting the call, without sending media.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "pre_accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Accept

Accepts a previously pre-accepted call, providing the agent SDP. The business has a limited time (30–60 seconds) to answer the user’s call; if it does not respond, the call ends with “Unanswered” and a termination webhook is sent.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "biz_opaque_callback_data": "random data"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Reject

Rejects a user-initiated call.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "reject"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Hang up

Ends an active call. It must be invoked even if there is an RTCP BYE packet in the media path, to get more accurate pricing. When the consumer ends the call, this API is not required; a termination webhook will be sent.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
  "action": "terminate"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "success": true
}

Common signaling body fields:

Call webhooks

Call webhooks use a structure similar to messaging. A calls section within the webhook value section contains the call-related fields.

Connect

Sent in near real time when the business receives an inbound call, including the SDP info to establish the WebRTC connection.

{
  "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",
                "connection": {
                  "webrtc": {
                    "sdp": "<<RFC 8866 SDP>>"
                  }
                },
                "session": {
                  "sdp_type": "offer",
                  "sdp": "<<RFC 8866 SDP>>"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

calls object fields:

Terminated

Sent when the call has been terminated for any reason (consumer hangs up or the business invokes terminate).

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "whatsapp-business-account-id",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16505553602",
              "phone_number_id": "phone-number-id"
            },
            "calls": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V-Hc5eCgK5Gh",
                "to": "16315553601",
                "from": "16315553602",
                "event": "terminate",
                "direction": "BUSINESS_INITIATED",
                "biz_opaque_callback_data": "random data",
                "timestamp": "1671644824",
                "status": "COMPLETED",
                "start_time": "1671644824",
                "end_time": "1671644944",
                "duration": 120
              }
            ],
            "errors": [
              {
                "code": 222,
                "message": "ERROR_TITLE",
                "href": "ERROR_HREF",
                "error_data": {
                  "details": "ERROR_DETAILS"
                }
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

Relevant fields:

Call CTA messages

After you adopt Cloud API Calling features, you can raise awareness with your customers in two core ways:

• Send them a message with a WhatsApp call button.
• Embed a calling deep link into your brand surfaces (website, application, and so on).

Send an interactive message with a call button

Sends an interactive message with the WhatsApp call button during a customer service window or an open conversation window. When the user clicks the button, a WhatsApp call to the business number that sent the message is initiated.

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "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,
        "payload": "payload data"
      }
    }
  }
}

Rules:

• interactive.type must be voice_call and interactive.body is required.
• interactive.footer is not allowed.
• to is required (unless recipient); recipient (BSUID or parent BSUID) can be used instead of, or in addition to, to. If both are provided, to takes precedence.
• display_text defaults to Call now; max length 20 characters.
• ttl_minutes (optional): button lifetime, between 1 and 43200 (30 days). Default 10080 (7 days).
• payload (optional): arbitrary string for tracking. Included in the connect and terminate webhooks under the cta_payload field. Max 512 characters. Only available to WhatsApp clients from version 2.25.27.
• Sending this message to users on old versions triggers an error webhook with code 131026.

Create a template with a call button

The templates API supports the voice_call button, which triggers a WhatsApp call on click. It can be used anywhere the phone number button is supported.

Endpoint: POST /message_templates/{v}/{did}

Request:

{
  "name": "<NAME>",
  "category": "<CATEGORY>",
  "language": "<LANGUAGE>",
  "components": [
    {
      "type": "BODY",
      "text": "You can call us on WhatsApp now for faster service!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "voice_call",
          "text": "Call Now",
          "ttl_minutes": 1440
        },
        {
          "type": "URL",
          "text": "Contact Support",
          "url": "https://www.example.com/support"
        }
      ]
    }
  ]
}

voice_call button rules in templates:

• type must be voice_call.
• text (optional): the button label. Default Call Now; max 20 characters.
• ttl_minutes (optional): button lifetime, between 1440 (1 day) and 43200 (30 days). Can be overridden when sending the message.
• Not supported in carousel, authentication, catalog, coupon, limited-time-offer, SPM or MPM templates.

Send a call button template message

Sends the call button template to a user. You can override ttl_minutes and send a tracking payload.

Endpoint: POST /{v}/{did}/messages

Request:

{
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "messaging_product": "whatsapp",
  "type": "template",
  "recipient_type": "individual",
  "template": {
    "name": "wa_voice_call",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "voice_call",
        "parameters": [
          {
            "type": "ttl_minutes",
            "ttl_minutes": 100
          },
          {
            "type": "payload",
            "payload": "payload data"
          }
        ]
      }
    ]
  }
}

button component parameters:

Calling deep links

Calling deep links are hyperlinks that route WhatsApp users to call your business. The process is similar to a chat deep link, except the format is:

wa.me/call/<BUSINESS_PHONE_NUMBER>

Note: deep links are not supported on WhatsApp desktop clients.

• Embed calling deep links: use them to advertise WhatsApp calling anywhere it’s useful, such as your website, primary application, or a QR code.
• Send calling deep links: you can send messages to WhatsApp users with a calling deep link. Since deep links can be made per business phone number, you can use them to prompt users to contact a different number with voice enabled. The wa.me/call/<BUSINESS_PHONE_NUMBER> format is easy to copy, paste, and send, and does not require a template.
• Send payload data in a call deep link: you can send a payload with the biz_payload query string:

wa.me/call/<BUSINESS_PHONE_NUMBER>?biz_payload=payload

When a user calls using the deep link with biz_payload, any app subscribed to the calls field can get this string in the connect and terminate webhooks under the deeplink_payload field. The deep link payload is only available to WhatsApp clients from version 2.25.27.

Call error codes

Most errors have the following shape:

{
  "error": {
    "message": "<Error Message>",
    "type": "<Exception Type>",
    "code": <Exception Code>,
    "fbtrace_id": "<Trace ID>"
  }
}

DTMF support

Cloud API supports DTMF tones to integrate IVR systems. Consumers press buttons in the client app and the tones are injected into the WebRTC RTP stream established as part of the VoIP connection.

• The WebRTC stream complies with RFC 4733 for DTMF digit transport over RTP.
• There is no webhook to transmit DTMF digits.
• The dial pad only supports DTMF use cases; it does not change any other call behavior.
• Tone values are digits 0–9, # and *. Tone duration is 500 ms and the interval between tones is 100 ms.

Clock rate: only the 8000 clock rate is supported in our SDPs. For user-initiated calls, the SDP offer includes only the 8000 clock rate. For business-initiated calls, your SDP offer should use the 8000 clock rate; even if it is absent, the API proceeds with 8000 against payload type 126. DTMF RTP packets use the same timestamp and sequence number base as regular audio packets (no need to worry about differing clock rates). The DTMF packet duration field is calculated using 8000 clock units. The API does not support the 48000 clock rate for DTMF.

Business-initiated calls

Product overview

The Calling API lets your business call WhatsApp users. The user controls when your business can call them by granting call permissions to your business phone number.

The business-initiated call flow is:

1. Obtain permission from the user to call them (permission request message or enabled callback_permission_status).
2. Initiate the call with action: connect, identifying the user by phone number (to), BSUID (recipient), or both.
3. Establish the connection: you receive the Connect webhook with an SDP Answer from Cloud API and apply it to your WebRTC stack to start the media connection. Then you receive status webhooks (RINGING, ACCEPTED, REJECTED). The ACCEPTED status webhook arrives after the call is established; Cloud API sends it for call event auditing.
4. Terminate the call: either you or the user can hang up. When terminated, you receive the Terminate webhook.

To call a user, the business must first obtain the user’s permission. When a user grants call permissions, they can be temporary or permanent. As of November 3, 2025, permanent permissions are available: users can grant a business ongoing permission to call. The user can review and change the calling permission at any time from the business profile.

The business does not control this permission; only the user can grant or revoke it, at any time. WhatsApp stores permanent permission data until the user revokes it.

A business can obtain permission in the following ways:

1. Send a call permission request to the user — free-form or template message; the user chooses between temporary or permanent.
2. Callback permission — the user automatically grants a temporary permission by calling the business. You must enable callback_permission_status on the number.
3. Permission via business profile — the user grants permission through the business profile.

Note: call permission features are available only in regions where business-initiated calling is available.

When granted, a call permission allows calling the user subject to the following restrictions (per business + consumer pair):

Requesting user permission

The permission request is sent as a free-form interactive message or as a template message. The consumer can approve, reject or not respond; they can also change their answer before it expires.

The request expires when any of these happens:

• The consumer interacts with a subsequent permission request.
• 7 days after the consumer accepted or rejected the permission.
• 7 days after delivery if the consumer does not respond.

Send limits:

• Max 1 permission request in 24 hours and 2 requests in 7 days per pair. The limit resets with a connected call between the business and the consumer.
• 2 consecutive unanswered calls trigger a system message to reconsider the approved permission.
• 4 consecutive unanswered calls automatically revoke the approved permission.

Send methods:

1. Free-form message: in response to a user message, subject to the customer service window. Body text is optional; header and footer are not supported.
2. Template message: lets you start a conversation with a call request. The body is required; header and footer are supported.

API: Send a free-form permission request

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "<phone number> or <wa_id>",
  "recipient": "US.13491208655302741918",
  "type": "interactive",
  "interactive": {
    "type": "call_permission_request",
    "action": {
      "name": "call_permission_request"
    },
    "body": {
      "text": "We would like to call you to help support your query on Order No: ON-12345."
    }
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+1-408-555-1234",
      "wa_id": "14085551234",
      "user_id": "<BSUID>",
      "parent_user_id": "<PARENT_BSUID>"
    }
  ],
  "messages": [
    {
      "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    }
  ]
}

Notes:

• Only type and action.name are required. action.name must be call_permission_request.
• to is required (unless recipient); recipient (BSUID or parent BSUID) can be used instead of, or in addition to, to. If both are provided, to takes precedence.
• body is optional and gives the user context.
• The business cannot edit the content of the call permission interactive message; only the body.
• Requires an open customer service window with the user account.
• Sending to users on older app versions triggers an error webhook with code 131026.

API: Create a template with permission request

Endpoint: POST /message_templates/{v}/{did}

Request:

{
  "name": "sample_cpr_template",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "text": "Support of Order No: {{1}}",
      "example": {
        "body_text": [["ON-12345"]]
      }
    },
    {
      "type": "BODY",
      "text": "We would like to call you to help support your query on Order No: {{1}} for the item {{2}}.",
      "example": {
        "body_text": [["ON-12345", "Avocados"]]
      }
    },
    {
      "type": "FOOTER",
      "text": "Talk to you soon!"
    },
    {
      "type": "call_permission_request"
    }
  ]
}

Response (200):

{
  "id": "<ID>",
  "status": "<STATUS>",
  "category": "<CATEGORY>"
}

Notes:

• The body component is required and only supports text.
• Header and footer are optional.
• Supported categories: Marketing and Utility.
• The call_permission_request type identifies the template.
• Media is not supported in this template.

API: Send a permission request template

Endpoint: POST /{v}/{did}/messages

Request:

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "{user number}",
  "type": "template",
  "template": {
    "name": "sample_cpr_template",
    "language": {
      "policy": "deterministic",
      "code": "en_US"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "ON-12345"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "ON-12345"
          },
          {
            "type": "text",
            "text": "Avocados"
          }
        ]
      }
    ]
  }
}

Response (200):

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "+1-408-555-1234",
      "wa_id": "+1-408-555-1234"
    }
  ],
  "messages": [
    {
      "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
    }
  ]
}

API: Get the call permission status

Gets the call permission state for a business phone number with a single WhatsApp user. You can identify the user by phone number (user_wa_id) or by their BSUID (recipient).

Endpoint: GET /calls/{v}/{did}/call_permissions?user_wa_id={user_whatsapp_id}

Or using a BSUID:

Endpoint: GET /calls/{v}/{did}/call_permissions?recipient={BSUID}

Response (200):

{
  "messaging_product": "whatsapp",
  "permission": {
    "status": "temporary",
    "expiration_time": 1745343479
  },
  "actions": [
    {
      "action_name": "send_call_permission_request",
      "can_perform_action": true,
      "limits": [
        {
          "time_period": "PT24H",
          "max_allowed": 1,
          "current_usage": 0
        },
        {
          "time_period": "P7D",
          "max_allowed": 2,
          "current_usage": 1
        }
      ]
    },
    {
      "action_name": "start_call",
      "can_perform_action": false,
      "limits": [
        {
          "time_period": "PT24H",
          "max_allowed": 5,
          "current_usage": 5,
          "limit_expiration_time": 1745622600
        }
      ]
    }
  ]
}

Response fields:

Errors:

Call permission webhooks

Temporary approval

When the consumer approves a temporary permission, the interactive section of the message webhook contains call_permission_reply.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "{phone-number-id}",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "{phone-number}",
              "phone_number_id": "{phone-number-id}"
            },
            "contacts": [
              {
                "profile": { "name": "NAME" },
                "wa_id": "{phone-number}"
              }
            ],
            "messages": [
              {
                "from": "{phone-number}",
                "id": "wamid.sH0kFlaCGg0xcvZbgmg90lHrg2dL",
                "timestamp": "{TIMESTAMP}",
                "context": {
                  "from": "{phone-number}",
                  "id": "wamid.gBGGFlaCmZ9plHrf2Mh-o"
                },
                "interactive": {
                  "type": "call_permission_reply",
                  "call_permission_reply": {
                    "response": "accept",
                    "is_permanent": false,
                    "expiration_timestamp": "{timestamp}",
                    "response_source": "user_action"
                  }
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

Permanent approval

Same as temporary approval, with is_permanent: true and no expiration_timestamp.

Rejection

Same as approval, with response: "reject". response_source can be user_action (the user rejected) or automatic (automatic rejection due to unanswered-call limits).

Permission from the callback flow

When the permission is granted after a lost consumer-initiated call, context.id contains the call ID of the lost call.

call_permission_reply fields:

Start a new call

Initiates a call to a WhatsApp user. There is a rate limit of 10,000 new calls per 24 hours per business phone number.

Endpoint: POST /calls/{v}/{did}/signaling

Request:

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "biz_opaque_callback_data": "0fS5cePMok"
}

Response (200):

{
  "messaging_product": "whatsapp",
  "calls": [
    {
      "id": "wacid.ABGGFjFVU2AfAgo6V"
    }
  ]
}

Body parameters:

Errors:

Call status webhooks

Sent on specific events of a business-initiated call: ringing (the call starts ringing), accepted (the consumer accepts) and rejected (the consumer rejects).

{
  "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"
            },
            "statuses": [
              {
                "id": "wacid.ABGGFjFVU2AfAgo6V",
                "timestamp": "1671644824",
                "type": "call",
                "status": "RINGING",
                "recipient_id": "16315553602",
                "biz_opaque_callback_data": "random data"
              }
            ]
          },
          "field": "calls"
        }
      ]
    }
  ]
}

statuses fields:

Call recording

The Calling API can record the audio of business-initiated calls (BIC) and user-initiated calls (UIC) you make through the WhatsApp Business Cloud API. When you opt a call into recording, both participants hear a short legally required announcement before the recording begins. After the call ends, you receive a webhook with a media ID you can use to download the finished recording.

Recording is opt-in on a per-call basis — you decide at the time you initiate or accept each call whether it should be recorded. It is independent of call transcription: you can enable either one on its own, both together, or neither. Each is configured and priced separately, has its own request object, and delivers its result in its own webhook event.

Enable recording on a business-initiated call

Add a recording object to your business-initiated call request body:

Endpoint: POST /calls/{v}/{did}/signaling

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "recording": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Enable recording on a user-initiated call

Add the same recording object when you accept an incoming call:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "recording": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

To accept an incoming call without recording it, either omit the recording field entirely or send it with "status": "DISABLED".

Announcements and consent

Before any audio is recorded, the Calling API mixes a spoken announcement into both your business and the WhatsApp user audio streams. The announcement is generated from the purpose string you provide and the announcement_language you select, for example:

“The audio of this call will be recorded for the following purpose: .”

The recording starts only after the announcement has finished playing. A participant who does not consent can decline by terminating the call before or during the announcement. The purpose field is mandatory whenever status is ENABLED; calls submitted with recording enabled but without a purpose are rejected with a request error.

recording object reference

Supported announcement languages

Using recording with transcription

Recording and transcription are fully independent. The recording and transcription objects are separate request fields, so you choose each one independently on a per-call basis:

• Send only recording to receive an audio recording and no transcript.
• Send only transcription to receive a transcript and no audio recording.
• Send both objects to receive both an audio recording and a transcript.
• Omit both (or set both to DISABLED) to receive neither.

When you enable both on the same call, participants hear a single combined announcement:

“The audio of this call will be recorded and transcribed for the following purpose: .”

When both objects are present, the announcement_language and purpose from the recording object are used for this combined announcement, and the corresponding values in the transcription object are ignored. You still receive a separate webhook for each enabled feature.

Recording-available webhook

After the call ends and post-processing finishes (typically under one minute), the Calling API sends a call_recording_available event under the existing calls webhook field:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "calls",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>"
            },
            "calls": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyNTMVAgASGCBGO...",
                "from": "<USER_PHONE_NUMBER>",
                "from_user_id": "<BSUID>",
                "from_parent_user_id": "<PARENT_BSUID>",
                "timestamp": "1728932177",
                "event": "call_recording_available",
                "call_recording": {
                  "type": "audio",
                  "audio": {
                    "id": "1002764438271669",
                    "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                    "mime_type": "audio/ogg; codecs=opus",
                    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

call_recording fields:

Download the recording

Recordings use the same download flow as media messages:

1. The url returned in the webhook is valid for 5 minutes. Issue an authenticated GET request with your access token to download the file directly.
2. If the URL has expired, use the Media API to retrieve a fresh media URL with the audio.id.

Retention

Recordings remain available for download for 7 days after the call_recording_available webhook is delivered. After that period, the media ID expires and the underlying file is deleted. Download and persist the recording to your own storage within the retention window if you need to keep it long-term.

Errors

Call transcription

The Calling API can transcribe the audio of business-initiated calls (BIC) and user-initiated calls (UIC) you make through the WhatsApp Business Cloud API. When you opt a call into transcription, both participants hear a short legally required announcement before transcription begins. After the call ends, you receive a webhook with a media ID you can use to download the finished transcript as a JSON document.

Transcription is opt-in on a per-call basis — you decide at the time you initiate or accept each call whether it should be transcribed. It is independent of call recording: you can enable either one on its own, both together, or neither. Each is configured and priced separately, has its own request object, and delivers its result in its own webhook event.

Enable transcription on a business-initiated call

Add a transcription object to your business-initiated call request body:

Endpoint: POST /calls/{v}/{did}/signaling

{
  "messaging_product": "whatsapp",
  "to": "14085551234",
  "recipient": "US.13491208655302741918",
  "action": "connect",
  "session": {
    "sdp_type": "offer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "transcription": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

Enable transcription on a user-initiated call

Add the same transcription object when you accept an incoming call:

{
  "messaging_product": "whatsapp",
  "call_id": "wacid.ABGGFjFVU2AfAgo6V",
  "action": "accept",
  "session": {
    "sdp_type": "answer",
    "sdp": "<<RFC 8866 SDP>>"
  },
  "transcription": {
    "status": "ENABLED",
    "purpose": "quality assurance",
    "announcement_language": "en_US"
  }
}

To accept an incoming call without transcribing it, either omit the transcription field entirely or send it with "status": "DISABLED".

Announcements and consent

Before any audio is transcribed, the Calling API mixes a spoken announcement into both your business and the WhatsApp user audio streams:

“The audio of this call will be transcribed for the following purpose: .”

Transcription starts only after the announcement has finished playing. A participant who does not consent can decline by terminating the call before or during the announcement. The purpose field is mandatory whenever status is ENABLED; calls submitted with transcription enabled but without a purpose are rejected with a request error.

transcription object reference

Supported announcement languages

Note: announcement_language also accepts nl and es_ES. They are valid, but until a localized transcription announcement is available they play the English announcement.

Using transcription with recording

Transcription and recording are fully independent. When you enable both on the same call, participants hear a single combined announcement:

“The audio of this call will be recorded and transcribed for the following purpose: .”

When both objects are present, the announcement_language and purpose from the recording object are used for this combined announcement, and the corresponding values in the transcription object are ignored. You still receive a separate webhook for each enabled feature.

Transcription-available webhook

After the call ends and post-processing finishes (typically under one minute), the Calling API sends a call_transcription_available event under the existing calls webhook field:

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "<WABA_ID>",
      "changes": [
        {
          "field": "calls",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "phone_number_id": "<BUSINESS_PHONE_NUMBER_ID>",
              "display_phone_number": "<BUSINESS_DISPLAY_PHONE_NUMBER>"
            },
            "calls": [
              {
                "id": "wacid.HBgLMTQxMjYxMzYyNTMVAgASGCBGO...",
                "from": "<USER_PHONE_NUMBER>",
                "from_user_id": "<BSUID>",
                "from_parent_user_id": "<PARENT_BSUID>",
                "timestamp": "1728932177",
                "event": "call_transcription_available",
                "call_transcript": {
                  "document": {
                    "id": "1002764438271669",
                    "sha256": "Y9vvGyeo3n76ptkXu3CwDBsnzbRFqpjHskQdMGSVqas=",
                    "mime_type": "application/json",
                    "url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=133..."
                  }
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

call_transcript fields:

Transcript language

You do not specify a transcription language in the request. The Calling API automatically detects the spoken language of the call, transcribes it, and reports the detected language in the transcript.language field (ISO 639 code, e.g. en). This detected language is independent of the announcement_language.

The set of detectable languages evolves constantly and includes (among others): English, Spanish, Portuguese, French, German, Italian, Hindi, Arabic, Chinese, Japanese, Korean, Russian, Turkish, Vietnamese and more than 50 languages. If a call is spoken in an unsupported language, you still receive the call_transcription_available webhook, but the transcript may be empty.

Transcript document format

The downloaded transcript is a JSON document with two top-level objects: metadata and transcript.

{
  "metadata": {
    "processed_at": "2026-06-18T20:16:47Z",
    "audio": {
      "duration": 21.76,
      "sample_rate": 16000,
      "channels": 2,
      "audio_format": "stereo"
    }
  },
  "transcript": {
    "text": "[Business] Hello, how about you? [Customer] Hey, I'm good. How are you?",
    "language": "en",
    "duration": 21.76,
    "confidence": 0.83,
    "segments": [
      {
        "id": 1,
        "speaker": "Business",
        "channel": 0,
        "start": 1.16,
        "end": 2.44,
        "text": "Hello, how about you?",
        "confidence": 0.85,
        "words": [
          {
            "word": "Hello,",
            "start": 1.16,
            "end": 1.64,
            "confidence": 0.89,
            "lang": "en"
          }
        ]
      }
    ]
  }
}

metadata fields:

transcript fields:

segments fields:

Each segment represents a continuous span of speech from one speaker.

Download the transcript

Transcripts use the same download flow as media messages:

1. The url returned in the webhook is valid for 5 minutes. Issue an authenticated GET request with your access token to download the file directly.
2. If the URL has expired, use the Media API to retrieve a fresh media URL with the document.id.

Retention

Transcripts remain available for download for 7 days after the call_transcription_available webhook is delivered. After that period, the media ID expires and the underlying file is deleted. Download and persist the transcript to your own storage within the retention window if you need to keep it long-term.

Errors

Integration best practices

Audio clipping problem and solution

When connecting the consumer’s WhatsApp media segment (WebRTC) with another media segment (e.g. SIP), audio clipping may occur: the consumer loses roughly one second of the business message (e.g. an IVR playing 1-2-3 may be heard only from 2).

Root cause: when a media server connects two segments, it must ensure both are roughly ready at the same time. If the SIP segment sends media before the WebRTC segment is ready, packets are discarded and clipping occurs.

Suggested solution: a WebRTC agent must not send media until the ICE process is almost complete. This is achieved with optimistic acceptance: invoke pre-accept even before sending the SIP INVITE. Per RFC, a UAC must be ready to receive media right after sending the INVITE.

Key points:

• When receiving the connect webhook, initialize the WebRTC agent, prepare the SDP answer and call pre-accept with that SDP answer.
• Wait for the ICE process to complete the valid candidate lists before sending media.
• If the SIP UA rejects the call instead of sending a 200 OK, call the terminate API.
• If the consumer connection is ready before the SIP one, the consumer may hear a few milliseconds of silence, which is better than losing the initial business audio.

Other alternatives: force the SIP UA not to play audio until it receives the WebRTC ACK, until it detects the connected state, buffer SIP media packets and send them once the WebRTC connection is established, or insert silence in the IVR before the actual audio.

Integration patterns

Single app vs. multiple apps

To integrate the Calling API you need to call Graph API endpoints and process Webhooks from Meta, which requires you to have an app. Almost always, you should already have an app used for messaging, and you can reuse it for calling.

In this setup, the Webhook Callback URI is the same for both message and call webhooks, but the payload can be used to distinguish between the two categories. You can forward calling-specific webhooks to a calls-related component from your main webhook logic.

Reusing the same app offers:

• Reduced operational overhead (app review, ongoing maintenance).
• Simplified footprint on Meta.
• Equality between the app used for Embedded Signup and the one used for invoking Graph APIs and receiving webhooks.
• No impact to existing functionality; you only need to ensure the webhook server gracefully handles calls-related webhooks.

Having separate apps is still supported.

Integrating using a third-party calling provider

In this scenario, you use a third-party (3p) calling provider internally, and that provider is not visible to Meta. The pattern is similar to any other SaaS service. This architecture can optionally be extended to integrate with the SIP infrastructure on your side.

Warning: our terms disallow use of PSTN on any leg of the WhatsApp call in the overall call flow. Even if you bridge the WA call into the SIP world, you must ensure it stays exclusively on VoIP and never touches the PSTN. A SIP trunk by itself is not disallowed, because technically it can be used without any PSTN at all.

Guidelines for media path integration

The WhatsApp Business Calling VoIP stack is designed to be compatible with WebRTC, but Meta restricts the supported functionalities.

Mandatory requirements (if unmet, the call fails during signaling or media packet decoding):

• Use only the supported codecs.
• For Opus, set the media clock rate to 48 kHz.
• For Opus, use a ptime of 20 ms.
• Audio must use a single SSRC. The Meta relay server overwrites the SSRC of all business audio packets to a fixed SSRC before they reach the WA client. WA clients handle only one audio source from their peers. Using multiple SSRCs causes undefined behavior: severe media corruption, audio glitches, and likely total media failure.
• Set the DTMF clock rate to 8 kHz.

Recommendations (for high call quality and reliability):

• ICE process: Meta’s VoIP stack is ICE-LITE; it is recommended that the Solution Partner’s stack is ICE-FULL (RFC 5245 §2.7). The partner’s stack should initiate the ICE process by sending STUN connectivity checks, assume the ICE CONTROLLING role (Meta assumes CONTROLLED), use regular nomination instead of aggressive (RFC 5245 §8.1.1.2), wait for ICE to complete before nominating the candidate and starting DTLS, and not switch the candidate mid-call.
• DTLS: use ECDH keys for the DTLS certificates to prevent packet fragmentation. The Solution Partner should act as a DTLS client (RFC 6347 §4.2).
• Media: WhatsApp may not always send the first RTP media packet. Your media server’s egress should not wait for WhatsApp’s media ingress; if it does, there is a risk of deadlock where each side waits for the other.
• Audio clipping: see the audio clipping section above.

Integration examples

Meta documents integration examples with common VoIP platforms. These guides are for information purposes only, with no support or warranties of any kind from Meta or any vendor; there are many ways to integrate, and the guides explain just one way exclusively for illustrative purposes.

Asterisk using SIP

Integration of the Calling API using SIP signaling with Asterisk, an open-source PBX.

• User-initiated calls: the WhatsApp user dials the business number; the call is received by Asterisk and routed through an IVR that asks for an extension registered on the same server; the call is connected to that extension.
• Business-initiated calls: the agent registers with Asterisk using SIP credentials; dials the b2c-sip extension, the IVR asks for the WhatsApp number to call, and the call is connected to the user.
• The WA → Asterisk leg uses SDES for media key exchange and Opus as codec. The Asterisk → SIP UA leg uses SDES and Opus or G.711.

Key troubleshooting — not receiving ACK from Meta or business audio stops around 30s:

If Meta sends a SIP INVITE, your server responds 200 OK, but you never receive the ACK and the SIP server terminates the dialog on ACK timeout (typically 32s), the most likely cause is incorrect Record-Route headers in your 200 OK. The 200 OK must not modify the Record-Route headers included in Meta’s original INVITE (you can add new ones, but not modify the existing). The solution is rewrite_contact=no on the WhatsApp endpoint in pjsip.conf, and ensure your 200 OK has as the last 2 headers:

Record-Route: <sip:wa.meta.vc;transport=tls;lr>
Record-Route: <sip:onevc-sip-proxy.fbinfra.net:8191;transport=tls;lr>

FreeSWITCH using SIP

Integration with FreeSWITCH using SIP signaling. Same flow structure as Asterisk (IVR for extensions and for B2C calls via b2c-sip). The WA → FreeSWITCH leg uses SDES with Opus; the FreeSWITCH → SIP UA leg uses SDES with Opus or G.711.

Key points: FreeSWITCH listens on 5081 for TLS; the wa-biz-api-dialplan.xml dialplan verifies the request comes from wa.meta.vc and uses check_acl with Meta’s allowlisted IPs; a 1-second silence stream is added to establish the media path and avoid audio clipping.

FreeSWITCH using Graph API with Janus

Integration using Cloud API signaling (Graph APIs + Webhooks) with FreeSWITCH and Janus, a general-purpose WebRTC server.

• An integration module sits between WA and Janus and translates Cloud API Signaling messages to Janus SIP plugin messages and vice versa.
• Janus converts WA media (WebRTC, DTLS key exchange) to the media negotiated with FreeSWITCH (SDES).
• Business-initiated calls: the SIP INVITE reaches Janus on extension 1000, is converted to a Graph API request with the INVITE SDP as offer; when the user accepts, the SIP INVITE is accepted passing the SDP answer from the connect webhook.
• User-initiated calls: the webhook receives the incoming call with the SDP offer; the Janus SIP plugin sends an INVITE to FreeSWITCH (destination c2b-sip); on receiving the 200 OK, an accept request is sent to Meta with the answer SDP.

Asterisk using Graph API with RtpEngine

Integration using Cloud API signaling with Asterisk and RtpEngine, a proxy for relaying, manipulating and controlling RTP streams. RtpEngine acts as a media proxy between WA (WebRTC, DTLS) and Asterisk (SDES).

The integration module translates Cloud API Signaling to SIP for Asterisk, uses RtpEngine’s ng control protocol for media bridging, and connects via reserved extension 1000. To initiate a call: Asterisk sends a SIP INVITE to extension 1000 with a custom header carrying the WA number; the INVITE SDP is sent to RtpEngine, which returns a new SDP; that SDP is used in the Graph API request to initiate the call.

Asterisk with built-in WebRTC using Graph API

Similar to Asterisk + RtpEngine, but using Asterisk’s built-in WebRTC support (no RtpEngine required). In the extension 1000 configuration, webrtc=yes is a shortcut for: use_avpf=yes, media_encryption=dtls, dtls_verify=fingerprint, dtls_setup=actpass, ice_support=yes, media_use_received_transport=yes, rtcp_mux=yes.

Pricing model

Warning: All user-initiated calls are free.

Overview

Businesses are charged for calls based on:

• Duration of the call (calculated in six-second pulses).
• Country code of the phone number being called.
• Volume tier (based on minutes called within the calendar month) using the same tiering accrual as messaging.

Note: Our systems count fractional pulses as one pulse. For example, a 56-second call (9.33 pulses) would be counted as 10 pulses.

For calls that cross pricing tiers (for example from the 0 - 50,000 tier to the 50,001 - 250,000 tier), the entire call is priced at the lower rate (that is, the rate of the higher volume tier).

A valid payment method is required to place calls.

Note: Call permission request messages are subject to per-messaging pricing.

Rate cards and volume tiers

These rate cards represent the current rates and volume tiers for the WhatsApp Business Calling API, effective April 1, 2026, based on WhatsApp Business account timezone.

Updates to rate cards

The following tables show future updates to the rates. See our rate cards above for current rates.

Rates effective July 1, 2026 across 16 currencies:

Previous updates

• Effective April 1, 2026 – 8 new billing currencies introduced: AED (United Arab Emirates), ARS (Argentina), CLP (Chile), COP (Colombia), MYR (Malaysia), PEN (Peru), SAR (Saudi Arabia), SGD (Singapore).
• Effective January 1, 2026 – MXN (Mexico) rates introduced.

How calling changes the 24 hour customer service window

Currently, when a WhatsApp user messages you, a 24-hour timer called a customer service window begins, or refreshes.

When you are within the window, your business can send any type of message to the WhatsApp user, which is otherwise not allowed.

With the introduction of the Calling API, the customer service window now also starts or refreshes for calls:

• When a WhatsApp user calls you, regardless of if you accept the call or not.
• When a WhatsApp user accepts your call.

Get cost and call analytics

Get call analytics for your WhatsApp Business account (WABA), providing useful information like cost, counts of completed calls, and average call duration. Learn more about call analytics.

Endpoint: GET /calls/{v}/{did}/analytics

Response (200):

{
  "call_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1676361600,
            "end": 1676448000,
            "cost": 10,
            "count": 10,
            "average_duration": 1
          }
        ]
      }
    ]
  },
  "id": "114525791557199"
}

Filters:

SIP specifications

Session Initiation Protocol (SIP) is a signaling protocol used for initiating, maintaining, modifying, and terminating real-time communication sessions between two or more endpoints. The Calling API supports using SIP as the signaling protocol instead of the Graph API endpoints.

Caution: when SIP is enabled on a business phone number, you cannot use the calling-related Graph API endpoints. By default, calling-related webhooks are not sent, but you can enable webhook delivery for SIP calls with webhook_delivery to receive call lifecycle events.

Prerequisites:

• The app must be enabled for calls (Beta contract signature).
• The app must have messaging permissions on the business phone number. Test by sending and receiving messages with the Graph API messaging endpoints, then use the same app to configure your SIP server for calling. Verify with the Health Status API.
• The app mode must be “Live” (not “In development”).
• A standards-compliant third-party SIP server that supports TLS transport and digest authentication.

Security:

• TLS transport is mandatory for SIP. Meta presents a valid server cert whose subject name covers the SIP domain wa.meta.vc. Your SIP server must do the same: Meta validates your cert and that its subject name covers the SIP domain configured on the business phone number.
• Meta does not support mutual TLS (mTLS): when Meta acts as a TLS client, your TLS server must not request a client certificate. If you do, Meta presents a client cert whose subject references a random dynamic host that will not pass validation.
• Meta adds transport=TLS to the request URI as part of its SIP requests to your server.
• For business-initiated calls, the SIP INVITE from your server will be challenged with digest auth.
• For user-initiated calls, it is strongly recommended to challenge Meta’s SIP INVITE with digest auth.

Configure SIP settings

Endpoint: POST /calls/{v}/{did}/settings

Request:

{
  "calling": {
    "status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "webhook_delivery": "ENABLED",
      "servers": [
        {
          "hostname": "sip.example.com",
          "port": 5061,
          "request_uri_user_params": {
            "tgrp": "meta-wa",
            "trunk-context": "byoc.example.com"
          }
        }
      ]
    }
  }
}

Response (200):

{
  "success": true
}

sip fields:

**Response (200):**

```json
{
  "success": true
}

sip fields:

curl example:

curl --request POST \
  --url 'https://channels.chattigo.com/bsp-cloud-chattigo-isv/calls/v21.0/{did}/settings' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "calling": {
      "status": "ENABLED",
      "sip": {
        "status": "ENABLED",
        "servers": [{
          "hostname": "{SIP_SERVER_URL}"
        }]
      }
    }
  }'

Get SIP settings

The SIP user password is only included if the include_sip_credentials=true query param is specified.

Endpoint: GET /calls/{v}/{did}/settings?include_sip_credentials=true

Response (200):

{
  "calling": {
    "status": "ENABLED",
    "call_icon_visibility": "DEFAULT",
    "callback_permission_status": "ENABLED",
    "sip": {
      "status": "ENABLED",
      "servers": [
        {
          "app_id": "<APP_ID_THAT_CONFIGURED_THIS_SIP_SERVER>",
          "hostname": "sip.example.com",
          "sip_user_password": "{SIP_USER_PASSWORD}"
        }
      ]
    }
  }
}