# Send WhatsApp Call Button Messages and Deep Links
## Overview
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 interactive message with a WhatsApp call button
Use this endpoint to send a free-form interactive message with a WhatsApp call button during a [customer service window](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows) or an [open conversation window](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing#opening-conversations).
When a WhatsApp user clicks the call button, the click initiates a WhatsApp call to the business number that sent the message.
WhatsApp sends a standard [message status webhook](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status) in response to this message send.
#### Request syntax
```html
POST <PHONE_NUMBER_ID>/messages
```
| Placeholder | Description | Sample value |
| --- | --- | --- |
| `<PHONE_NUMBER_ID>`<br><br>_Integer_ | **Required**<br><br>The business phone number from which you are sending messages.<br><br>[Learn more about formatting phone numbers in Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api) | `+12784358810` |
#### Request body
```json
{
"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"
}
}
}
}
```
#### Body parameters
[Learn more about sending interactive free form messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api)
| Parameter | Description | Sample value |
| --- | --- | --- |
| `to`<br><br>_Integer_ | **Required** (unless `recipient` is provided)<br><br>The phone number of the WhatsApp user you are messaging.<br><br>[Learn more about formatting phone numbers in Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-account-phone-number-api) | `"17863476655"` |
| `recipient`<br><br>_String_ | **Optional**<br><br>The WhatsApp user's business-scoped user ID (BSUID) or parent BSUID. Use this instead of, or in addition to, `to`. If you include both, `to` takes precedence.<br><br>[Learn more about business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business-scoped-user-id) | `"US.13491208655302741918"` |
| `type`<br><br>_String_ | **Required**<br><br>The type of interactive message you are sending.<br><br>In this case, you are sending a `voice_call`.<br><br>[Learn more about interactive messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api) | `"voice_call"` |
| `action`<br><br>_String_ | **Required**<br><br>The action of your interactive message.<br><br>Must be `voice_call`. | `"voice_call"` |
| `parameters`<br><br>_JSON Object_ | **Optional**<br><br>Optional parameters for the WhatsApp calling button sent to the user.<br><br>Contains three values: `display_text`, `ttl_minutes`, and `payload`.<br><br>`display_text` — (_String_) **Optional**<br><br>The display text on the WhatsApp calling button sent to the user.<br><br>Default is `Call Now`.<br><br>Max length: 20 characters.<br><br>`ttl_minutes` — (_Integer_) **Optional**<br><br>Time to live for the call-to-action (CTA) button in minutes.<br><br>Must be between 1 and 43200 (30 days).<br><br>Default value is 10080 (7 days).<br><br>`payload` — (_String_) **Optional**<br><br>An arbitrary string, useful for tracking.<br><br>Any app subscribed to the `calls` webhook field on the WhatsApp Business account can get this string. The string is included in the `connect` and `terminate` webhook payloads under the `cta_payload` field.<br><br>Cloud API does not process the `cta_payload` field; it returns the value in webhook payloads.<br><br>Maximum 512 characters.<br><br>Payload is only available to WhatsApp clients starting on version 2.25.27. | ```html
"parameters": {
"display_text": "Call on WhatsApp",
"ttl_minutes": 100,
"payload": "payload data"
}
``` |
**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](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business-scoped-user-id).
#### Success response
[Learn more about messaging success responses](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api)
#### Error response
Possible errors:
If you send this message to users on older app versions, Cloud API returns an error webhook with error code `131026`.
[View general Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
## Create and send WhatsApp call button template message
Use these endpoints to create and send a WhatsApp call button template message.
Once your call button template message is created, you can send a message to a WhatsApp user, inviting them to call your business.
[Learn more about creating and managing message templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview)
### Create call button message template
Use this endpoint to create a call button message template.
#### Request syntax
```html
POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>/message_templates
```
| Parameter | Description | Sample value |
| --- | --- | --- |
| `<WHATSAPP_BUSINESS_ACCOUNT_ID>`<br><br>_String_ | **Required**<br><br>Your WhatsApp Business account ID.<br><br>[Learn how to find your WABA ID](https://developers.facebook.com/documentation/business-messaging/whatsapp/whatsapp-business-accounts) | `"waba-90172398162498126"` |
#### Request body
```html
{
"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.luckyshrub.com/support"
}
]
}
]
}
```
#### Body parameters
You can create and manage template messages through both Cloud API and the Meta Business Suite interface.
When creating your call button template, ensure you configure `type` as `voice_call`.
[Learn more about creating and managing message templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview)
| Parameter | Description | Sample value |
| --- | --- | --- |
| `type`<br><br>_String_ | **Required**<br><br>The type of template message you are creating.<br><br>In this case, you are creating a `voice_call`. | `"voice_call"` |
| `text`<br><br>_String_ | **Optional**<br><br>The display text on the WhatsApp calling button sent to the user.<br><br>Default is `Call Now`.<br><br>Max length: 20 characters. | `"Call Now"` |
| `ttl_minutes`<br><br>_Integer_ | **Optional**<br><br>Time to live for the CTA button in minutes.<br><br>Must be between 1440 (1 day) and 43200 (30 days).<br><br>You can override this value when sending the message. | `1440` |
#### Success response
```html
{
"id": "<ID>",
"status": "<STATUS>",
"category": "<CATEGORY>"
}
```
[_Learn more about messaging success responses_](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api)
#### Error response
Possible errors:
* Invalid `whatsapp-business-account-id`
* Permissions/Authorization errors
* Template structure/component validation alerts
[View general Cloud API error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
### Send call button message template
Use this endpoint to **send** a call button message template.
The following is a simplified sample of the send template message request. You can also [learn more about how to send message templates](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/overview).
#### Request syntax
```html
POST /<PHONE_NUMBER_ID>/messages
```
| Parameter | Description | Sample value |
| --- | --- | --- |
| `<PHONE_NUMBER_ID>`<br><br>_String_ | **Required**<br><br>The business phone number from which you are sending messages.<br><br>[Learn more about formatting phone numbers in Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/whatsapp-business-account-phone-number-api) | `+18762639988` |
#### Request body
```json
{
"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"
}
]
}
]
}
}
```
#### Request parameters
| Parameter | Description | Sample value |
| --- | --- | --- |
| `recipient`<br><br>_String_ | **Optional**<br><br>The WhatsApp user's business-scoped user ID (BSUID) or parent BSUID. Use this instead of, or in addition to, `to`. If you include both, `to` takes precedence.<br><br>[Learn more about business-scoped user IDs](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business-scoped-user-id) | `"US.13491208655302741918"` |
| `ttl_minutes`<br><br>_Integer_ | **Optional**<br><br>Time to live for the CTA button in minutes.<br><br>Must be between 1 and 43200 (30 days).<br><br>Default value is 10080 (7 days). | `10800` |
| `payload`<br><br>_String_ | **Optional**<br><br>An arbitrary string, useful for tracking.<br><br>Any app subscribed to the `calls` webhook field on the WhatsApp Business account can get this string. The string is included in the `connect` and `terminate` webhook payloads under the `cta_payload` field.<br><br>Cloud API does not process this field; it returns the value in webhook payloads.<br><br>Maximum 512 characters.<br><br>Payload is only available to WhatsApp clients starting on version 2.25.27. | `payload data` |
**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](https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids#business-scoped-user-id).
#### Success response
[Learn more about messaging success responses](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-phone-number/message-api)
## Calling deep links
Calling deep links are hyperlinks that route WhatsApp users to call your business.
The process to create a calling deep link is similar to a [chat deep link](https://faq.whatsapp.com/5913398998672934/?locale=en_US), except the format for the call deep link is `wa.me/call/<BUSINESS_PHONE_NUMBER>`
Deep links are not supported on WhatsApp desktop clients.
### Embed calling deep links
You can use calling deep links to advertise WhatsApp calling for your business.
Use these links anywhere calling is useful, such as your website, primary application, or a QR code to be shared.
### Send calling deep links
You can also send messages to WhatsApp users with a calling deep link.
Since deep links can be made per business phone number, you can use calling deep links to prompt WhatsApp users to contact a different phone number with voice enabled.
The `wa.me/call/<BUSINESS_PHONE_NUMBER>` format is easy to copy, paste, and send, and does not require you to make a template in Meta Business Suite.
### Send payload data in call deep link
You can also send a payload with the deep link. You can use the `biz_payload` query string when sending the call deep link to any user (`wa.me/call/<BUSINESS_PHONE_NUMBER>?biz_payload=payload`).
When a user calls using the provided deep link with the `biz_payload`, any app subscribed to the `calls` webhook field on the WhatsApp Business account can get this string. The string is included in the `connect` and `terminate` webhook payloads under the `deeplink_payload` field.
Payload in call deep link is only available to WhatsApp clients starting on version 2.25.27.