Skip to contentSkip to navigationSkip to topbar
On this page

WhatsApp Business Calling



WhatsApp Business Calling with Twilio Programmable Voice

whatsapp-business-calling-with-twilio-programmable-voice page anchor
(new)

Beta

WhatsApp Business Calling is in Private Beta. The information in this document could change. We might add or update features before the product becomes Generally Available. Beta products don't have a Service Level Agreement (SLA). Learn more about beta product support(link takes you to an external page).

WhatsApp Business Calling adds Voice-over-IP (VoIP) calling to communications between customers and businesses using the WhatsApp consumer application. Customers can use the WhatsApp consumer app to communicate with businesses via a single thread for both messaging and voice. Businesses can use the Twilio Programmable Voice and Programmable Messaging APIs to enable data-driven, contextual communication with those customers.

(warning)

Warning

WhatsApp Business Calling is not supported in the following sanctioned countries: Cuba, Iran, North Korea, Syria, and three regions in Ukraine: Crimea, Donetsk, and Luhansk.


Twilio configuration and enablement

twilio-configuration-and-enablement page anchor

Registration of your WhatsApp sender for use with Twilio Programmable Voice can be done using the Twilio WhatsApp Business Platform, currently found under our Twilio Programmable Messaging platform and APIs. WhatsApp Messaging is required to use WhatsApp Business Calling. Getting started with WhatsApp is a great place to start.

Onboard your WhatsApp Business Account and senders

onboard-your-whatsapp-business-account-and-senders page anchor

To use WhatsApp Business Calling with Twilio Programmable Voice, you will first need a WhatsApp-activated phone number, also referred to as a WhatsApp sender, that can send and receive WhatsApp messages. Check out Getting started with WhatsApp to learn how to register your first WhatsApp sender.

Once you have an approved WhatsApp sender, continue below to get started with WhatsApp Business Calling.

Configure your sender for WhatsApp Business Calling

configure-your-sender-for-whatsapp-business-calling page anchor

You can configure your onboarded WhatsApp sender for Programmable Voice by selecting a TwiML Voice Application SID(link takes you to an external page). You can configure a TwiML Voice Application via your Twilio Console or API.

Create a Programmable Voice application

create-a-programmable-voice-application page anchor

To handle the inbound call, you will need a Twilio Programmable Voice application. This could be as simple as an application to play an MP3 recording, as complex as a contact center built using Twilio Flex, or anything in between.

Refer to the Twilio Programmable Voice documentation for more information. A good place to start would be the tutorial on handling inbound calls. If you have an existing Programmable Voice solution configured on a Twilio phone number, that may be an option to use here.

Once you have a Voice application to handle your calls, you will need to configure it as a TwiML application that you can use to configure your WhatsApp number to handle inbound voice calls from WhatsApp end users. You can find your TwiML applications in your Twilio Console under Voice > Manage > TwiML Apps.

  • If you don't have a TwiML Application SID already, you can create one: How do I create a TwiML App(link takes you to an external page)
  • The only configuration you need is the Request URL where you will send the webhooks for your inbound WhatsApp voice calls to your application.
    • You should only configure the Voice Configuration section; don't configure the Messaging Configuration section, as it's not used here.
Create TwiML App.

When created, you can get the Application SID to use for your WhatsApp Business Calling configuration:

TwiML App SID.

Activate your sender for WhatsApp Business Calling using Twilio Console

activate-your-sender-for-whatsapp-business-calling-using-twilio-console page anchor

Once you have a TwiML application to use, you can set it under the WhatsApp sender, in the Voice Endpoint Configuration section:

Sender Voice Config.

Configuring the Voice Configuration of your sender with a TwiML application activates WhatsApp Business Calling on that sender. You can deactivate WhatsApp Business Calling by removing the TwiML application from the configuration.

Activate your sender for WhatsApp Business Calling via Twilio API

activate-your-sender-for-whatsapp-business-calling-via-twilio-api page anchor

You can also set the Voice Configuration of your sender to your TwiML Application SID(link takes you to an external page) using the Messaging API and the WhatsApp Senders resource.

Set the voice_application_sid parameter on your onboarded sender to the TwiML Application SID of your Voice application.

Setting a sender's Voice Application SID:

1
curl -X POST https://messaging.twilio.com/v2/Channels/Senders/XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
2
-H "Content-Type: application/json; charset=utf-8" \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"configuration": {
6
"voice_application_sid": "APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
7
}
8
}'

Output:

1
{
2
"configuration": {
3
"verification_code": null,
4
"verification_method": "sms",
5
"voice_application_sid": "APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
6
"waba_id": null
7
},
8
"offline_reasons": null,
9
"profile": null,
10
"properties": null,
11
"sender_id": null,
12
"sid": "XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
13
"status": "ONLINE:UPDATING",
14
"url": "https://messaging.twilio.com/v2/Channels/Senders/XExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
15
"webhook": null
16
}

Note: Configuring the Voice Configuration of your sender with a TwiML application activates WhatsApp Business Calling on that sender. You can deactivate WhatsApp Business Calling by setting the voice_application_sid parameter to null.


User-initiated (inbound) calling—WhatsApp to Twilio call flow

user-initiated-inbound-callingwhatsapp-to-twilio-call-flow page anchor

WhatsApp consumers can initiate a call to a business using either the business's calling icon (if activated), or using a voice call-to-action button sent by the business via a template, described below. Calls that are sent to your WhatsApp sender will generate a webhook to your Twilio Voice application, which will handle the call in the same manner as inbound calls to a Twilio phone number.

Inbound Call Flow.

Note Calls from WhatsApp endpoints can't be connected to Public Switched Telephone Network (PSTN) endpoints. Such calls will be rejected.

WhatsApp messaging templates

whatsapp-messaging-templates page anchor

You will need to use WhatsApp message templates to send a new voice call button that customers can use to initiate a call into your Voice application; button type is VOICE_CALL.

What is supported for end users:

  • Creation of a content template to send a voice call button to initiate a voice call over WhatsApp
    • Template can be sent in a messaging session
    • Template can be sent out of session as an approved template
  • Voice call buttons can be added in the actions object in twilio/card, whatsapp/card, and twilio/call-to-action. To learn more about how to create each type, refer to the following pages:
WA Template Message.

Create your voice call content template via API

create-your-voice-call-content-template-via-api page anchor

Note: You can also create this template in your Twilio console's Content Template Builder, using content type Card and button type Voice Call.

VOICE_CALL button object

voice_call-button-object page anchor
ParameterTypeRequiredVariable supportDescription
titleStringYesNoThe button text of the voice call button
typeENUMYesNoSet to VOICE_CALL for a voice call button

Create a voice call template

create-a-voice-call-template page anchor

Creation of the voice call template is done using the Twilio API or Console Template Builder, and generates a Content SID, which is a unique identifier for the template. The Content SID can be found in the output from the request.

Voice call on a twilio/card
voice-call-on-a-twiliocard page anchor
1
curl -X POST https://content.twilio.com/v1/Content \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"friendly_name": "voice_call_test",
6
"language": "en",
7
"variables": {"1": "name"},
8
"types": {
9
"twilio/card": {
10
"title": "Hello {{1}} let’s continue on a call.",
11
"actions": [
12
{
13
"title": "Call now",
14
"type": "VOICE_CALL"
15
}
16
]
17
}
18
}
19
}'

Output:

1
{
2
"account_sid": "ACXXXXXX",
3
"date_created": "2024-05-03T17:59:30Z",
4
"date_updated": "2024-05-03T17:59:30Z",
5
"friendly_name": "voice_call_test",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/ApprovalRequests"
10
},
11
"sid": "HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
12
"types": {
13
"twilio/card": {
14
"actions": [{
15
"title": "Call now",
16
"type": "VOICE_CALL"}],
17
"body": null,
18
"media": null,
19
"subtitle": null,
20
"title": "Hello {{1}} let’s continue on a call."
21
}
22
},
23
"url": "https://content.twilio.com/v1/Content/HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
24
"variables": {
25
"1": "name"
26
}
27
}

Submit your voice template for WhatsApp approval

submit-your-voice-template-for-whatsapp-approval page anchor

If you plan to communicate in a session with a user using a WhatsApp template, you must first submit the template to Meta for approval. Insert the Content SID into the locations highlighted below. Meta also requires you to identify whether this is a marketing or utility template. Misclassification may result in template rejection.

Template approval request
template-approval-request page anchor
1
curl -X POST 'https://content.twilio.com/v1/Content/HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/ApprovalRequests/whatsapp' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"name": "voice_call_test",
6
"category": "UTILITY"
7
}'

Send a message using your message template

send-a-message-using-your-message-template page anchor

Once the template is created, the business can send a voice call button as a message using the template.

To learn about how to send a message using a message template, refer to the following:

1
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
2
--data-urlencode "ContentSid=Hxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
3
--data-urlencode "From=whatsapp:+558551234567" \
4
--data-urlencode "To=whatsapp:+555551234567" \
5
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN
WA Send Template.

Current restrictions to user-initiated calling

current-restrictions-to-user-initiated-calling page anchor

From WhatsApp (Meta)

from-whatsapp-meta page anchor
  • The maximum number of concurrent calls to/from a WhatsApp sender is 1,000.
  • Calls to WhatsApp destinations cannot be connected to Public Switched Telephone Network (PSTN) endpoints.
WA Business Manager.

Business-initiated (outbound) calling—Twilio to WhatsApp call flow

business-initiated-outbound-callingtwilio-to-whatsapp-call-flow page anchor

Your Twilio Voice application can also send calls from your WhatsApp Business Account to WhatsApp users on their WhatsApp messenger application.

Outbound Call Flow.
(information)

Info

Calls to WhatsApp endpoints can't be connected to Public Switched Telephone Network (PSTN) endpoints. These calls will be rejected.

Create a calling permission request template

create-a-calling-permission-request-template page anchor

You first need to create a twilio/call-to-action template for the calling permission request using the Twilio API. This generates a Content SID, which is a unique identifier for the template. The Content SID can be found in the output from the request:

1
curl -X POST 'https://content.twilio.com/v1/Content' \
2
-H 'Content-Type: application/json' \
3
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
4
-d '{
5
"friendly_name": "voice_call_request",
6
"language": "en",
7
"types": {
8
"twilio/call-to-action": {
9
"body":"test",
10
"actions": [
11
{
12
"type": "VOICE_CALL_REQUEST",
13
"title": "Call Request"
14
}
15
]
16
}
17
}
18
}'

Output:

1
{
2
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
"date_created": "2024-11-07T21:28:38Z",
4
"date_updated": "2024-11-07T21:28:38Z",
5
"friendly_name": "voice_call_request",
6
"language": "en",
7
"links": {
8
"approval_create": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests/whatsapp",
9
"approval_fetch": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/ApprovalRequests"
10
},
11
"sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
12
"types": {
13
"twilio/call-to-action": {
14
"actions": [
15
{
16
"title": "Call Request",
17
"type": "VOICE_CALL_REQUEST"
18
}
19
],
20
"body": "test"
21
}
22
},
23
"url": "https://content.twilio.com/v1/Content/HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
24
"variables": {}
25
}

Note: The VOICE_CALL_REQUEST action must be the only call-to-action button in the template. It cannot be combined with other action types such as URL, PHONE, or VOICE_CALL.

  • The body parameter in twilio/call-to-action is a required property, so it must have a value. However, this will be ignored when Twilio sends the actual request to WhatsApp.
  • The title parameter in VOICE_CALL_REQUEST action type is also a required property, but will be ignored, similar to the body parameter.

Unlike other WhatsApp templates, the VOICE_CALL_REQUEST template does not need to be submitted for WhatsApp approval before using it. This is because the call permission can be sent in active conversations/sessions.

Note: You can also create this template in your console's Content Template Builder, using content type "Call to action" and action type "Voice Call Request".

Sending the call permission request message from the template

sending-the-call-permission-request-message-from-the-template page anchor

Once the template is created, the business can send a voice call request as a message using the template.

To learn about how to send a message using a message template, refer to the following:

1
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Messages.json" \
2
--data-urlencode "ContentSid=HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
3
--data-urlencode "From=whatsapp:+558551234567" \
4
--data-urlencode "To=whatsapp:+555551234567" \
5
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN \
  • ContentSid is the template SID in the output of the create request.
  • From is a WhatsApp sender of the business. This will be the caller in the outbound call.
  • To is the WhatsApp consumer number. This will be the callee in the outbound call.

Receive the call permission request result in a webhook

receive-the-call-permission-request-result-in-a-webhook page anchor

When the user responds to a call permission request, a webhook will be returned to the Messaging Webhook URL configured for the applicable WhatsApp sender number.

1
POST /www/twiml/whatsapp-text.xml HTTP/1.1.
2
Host: xxxx.ngrok.io.
3
User-Agent: TwilioProxy/1.1.
4
Content-Length: 468.
5
Accept: */*.
6
Content-Type: application/x-www-form-urlencoded.
7
I-Twilio-Idempotency-Token: b00cd941-9b6e-49c3-84fb-e2af2cf92cc7.
8
X-Forwarded-For: xxx.xxx.xxx.xxx.
9
X-Forwarded-Host: xxxx.ngrok.io.
10
X-Forwarded-Proto: https.
11
X-Home-Region: stage-us1.
12
X-Twilio-Signature: IJE/ao63CwJRr07hdmuL/F/jIgw=.
13
Accept-Encoding: gzip.
14
.
15
SmsMessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&NumMedia=0&ProfileName=XXXX+Caller+BR-2&MessageType=interactive&SmsSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&WaId=5524987654321&SmsStatus=received&Body=VOICE_CALL_REQUEST&ButtonText=VOICE_CALL_REQUEST&To=whatsapp%3A%2B554123456789&ButtonPayload=REJECTED&ReferralNumMedia=0&MessageSid=SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&AccountSid=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&From=whatsapp%3A%2B5524987654321&ApiVersion=2010-04-01
  • The webhook Body parameter will be set to VOICE_CALL_REQUEST.
  • The request response value will be in the ButtonPayload parameter; possible values are ACCEPTED or REJECTED.

Place a call to a WhatsApp consumer

place-a-call-to-a-whatsapp-consumer page anchor

Once you have established permission to place a business-initiated call to a WhatsApp consumer, you can place the call using Twilio Programmable Voice, via API or TwiML.

Place a call using Twilio Programmable Voice API

place-a-call-using-twilio-programmable-voice-api page anchor

You can initiate a call to WhatsApp destinations using the Twilio Voice API Call resource, similar to any other channel; the syntax to use for WhatsApp caller ID and destinations is whatsapp:{number}.

Note: All API-generated calls to WhatsApp destinations must use a From value that is set to a WhatsApp sender that is registered and activated for Voice calling on the Twilio account the call is being placed from. The format must be whatsapp:{sender}, as shown in the example below.

1
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
2
--data-urlencode "From=whatsapp:+558551234567" \
3
--data-urlencode "To=whatsapp:+555551234567" \
4
--data-urlencode "Url=http://demo.twilio.com/docs/voice.xml" \
5
-u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Place a call using Twilio Programmable Voice TwiML

place-a-call-using-twilio-programmable-voice-twiml page anchor

You can initiate a call to WhatsApp numbers using the TwiML Voice <Dial> verb, similar to any other channel; there is a new <WhatsApp> noun to use, and the syntax to use for WhatsApp caller ID and destinations is whatsapp:{number}.

Note: All TwiML-generated calls to WhatsApp destinations must use a callerId attribute that is set to a WhatsApp sender that is registered and enabled for Voice calling on the Twilio account the call is being placed from. The format must be whatsapp:{sender}, as shown in the example below.

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Dial callerId="whatsapp:+558551234567">
4
<WhatsApp>+555551234567</WhatsApp>
5
</Dial>
6
</Response>

Current restrictions to business-initiated calling

current-restrictions-to-business-initiated-calling page anchor
  • The call permission request can be sent at most once in 24 hours, and no more than two requests in seven days.
  • Users may approve, decline, not respond, or change their response before the request expires.
  • Once permission is granted, the business can place five calls per 24 hours, for a maximum of seven days before having to request permission again.
  • The call permission expires in these cases:
    • Seven days after it is approved, rejected, or not responded to.
    • A new call permission is requested and approved.
    • After two consecutive missed calls, the user will be prompted again to possibly change permission.
    • After four consecutive missed calls, permission will be automatically revoked.
  • The maximum number of concurrent calls to/from a WhatsApp sender is 1,000.
  • Calls to WhatsApp destinations cannot be connected to Public Switched Telephone Network (PSTN) endpoints.
  • The VOICE_CALL_REQUEST template does not require submission for WhatsApp approval.
    • In cases where you want to use text as part of the template, you must submit it for WhatsApp approval.
    • If you do not submit for approval, you cannot add any additional message text, and the template can be used only to send call permissions in existing sessions.

Connect WhatsApp Business Calling to Twilio Flex

connect-whatsapp-business-calling-to-twilio-flex page anchor

To integrate WhatsApp Business Voice Calls with Twilio Flex, you'll need a TwiML application (as described above).

This will determine whether incoming calls are routed directly to Flex or through a Studio Flow (IVR) for additional processing.

Send calls straight to Flex

send-calls-straight-to-flex page anchor
  1. Navigate to TwiML Bins(link takes you to an external page).
  2. Click on the + sign to create a new TwiML Bin. Use the following TwiML Bin:
1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
<Enqueue action="" method="POST" workflowSid="[TASKROUTER_WORKFLOW_SID]">call</Enqueue>
4
</Response>

Replace [TASKROUTER_WORKFLOW_SID] with the expected Workflow SID.

  1. Save and copy the TwiML Bin URL.

Now that you have a TwiML Bin, you can create a TwiML application, as described above:

  1. Navigate to TwiML Apps(link takes you to an external page).
  2. Create a new TwiML application by clicking on Create a New TwiML App.
  3. Give it a friendly name such as "WhatsApp Calling App".
  4. In the Voice Configuration section, enter the URL of your TwiML Bin.
  5. Click Create and then click again on the recently created TwiML application.
  6. This TwiML application will be used to configure the Voice Configuration on your WhatsApp sender. If you are using the API to configure the sender, you'll want to copy the Application SID (APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). If you configure using the Console, you will want to remember the friendly name you gave the application.

Send calls to Flex using Studio

send-calls-to-flex-using-studio page anchor
  1. Navigate to TwiML Apps(link takes you to an external page).
  2. Create a new TwiML application by clicking on Create a New TwiML App.
  3. Give it a friendly name such as "WhatsApp Calling App".
  4. In the Voice Configuration section, enter the URL of your Studio Flow:
https://webhooks.twilio.com/v1/Accounts/ACCOUNT_SID/Flows/STUDIO_FLOW_SID

Replace ACCOUNT_SID and STUDIO_FLOW_SID with your Account SID and the Studio Flow SID.

  1. Click Create and then click again on the recently created TwiML application.
  2. This TwiML application will be used to configure the Voice Configuration on your WhatsApp sender. If you are using the API to configure the sender, you'll want to copy the Application SID (APxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). If you configure using the Console, you will want to remember the friendly name you gave the application.