Skip to main content

​
Call Button Messages and Deep Links

Updated: Nov 14, 2025

​
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, etc)

​
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 or an open conversation window. When a WhatsApp user clicks the call button, it initiates a WhatsApp call to the business number that sent the message. A standard message status webhook will be sent in response to this message send. Image

​
Request Syntax

POST <PHONE_NUMBER_ID>/messages
PlaceholderDescriptionSample Value
<PHONE_NUMBER_ID>
Integer		Required
The business phone number which you are sending messages from.
Learn more about formatting phone numbers in Cloud API		+12784358810

​
Request Body

\{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "14085551234",
  "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
ParameterDescriptionSample Value
to
Integer		Required
The phone number of the WhatsApp user you are messaging.
Learn more about formatting phone numbers in Cloud API		“17863476655”
type
String		Required
The type of interactive message you are sending.
In this case, you are sending a voice_call.
Learn more about interactive messages		“voice_call”
action
String		Required
The action of your interactive message.
Must be voice_call.		"voice_call"
parameters
JSON Object		Optional
Optional parameters for the WhatsApp calling button sent to the user.
Contains three values: display_text, ttl_minutes and payload
display_text — ( String) Optional
The display text on the WhatsApp calling button sent to the user.
Default is “Call Now”
Max length: 20 characters
ttl_minutes — ( Integer) Optional
Time to live for the CTA button in minutes.
Must be between 1 and 43200 (30 days)
Default value is 10080 (7 days)
payload — ( String) Optional
An arbitrary string, useful for tracking.
Any app subscribed to the calls webhook field on the WhatsApp Business Account can get this string, as it is included in the connect and terminate webhook payloads under the cta_payload field.
Cloud API does not process this field, it just returns it as part of the webhooks.
Maximum 512 characters.
Payload is only available to WhatsApp client starting on version 2.25.27.		<br />"parameters": {<br />"display_text": "Call on WhatsApp",<br />"ttl_minutes": 100,<br />"payload": "payload data"<br />}<br />

​
Success response

Learn more about messaging success responses

​
Error response

Possible errors that can occur: Sending this message to users on older app versions will result in error webhook with error code 131026 View general Cloud API Error Codes here

​
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, your business can send a message to a WhatsApp user, inviting them to call your business. Learn more about creating and managing message templates

​
Create call button message template

Use this endpoint to create a call button message template.

​
Request syntax

POST/&lt;WHATSAPP_BUSINESS_ACCOUNT_ID&gt;/message_templates
ParameterDescriptionSample Value
&lt;WHATSAPP_BUSINESS_ACCOUNT_ID&gt;
String		Required
Your WhatsApp Business Account ID.
Learn how to find your WABA ID		“waba-90172398162498126”

​
Request body

\{
  "name": "&lt;NAME&gt;",
  "category": "&lt;CATEGORY&gt;",
  "language": "&lt;LANGUAGE&gt;",
  "components": [\
    {\
      "type": "BODY",\
      "text": "You can call us on WhatsApp now for faster service!"\
    },\
    {\
      "type": "BUTTONS",\
      "buttons": [\
        {\
          "type": "voice_call",\
          "text": "Call Now"\
        },\
        {\
          "type": "URL",\
          "text": "Contact Support",\
          "url": "https://www.luckyshrub.com/support"\
        }\
      ]\
    }\
  ]
}

​
Body parameters

Creating and managing template messages can be done both through Cloud API and the WhatsApp Business Manager interface. When creating your call button template, ensure you configure type as voice_call. Learn more about creating and managing message templates
ParameterDescriptionSample Value
type
String		Required
The type of template message you are creating.
In this case, you are creating a voice_call.		“voice_call”

​
Success response

\{
  "id": "&lt;ID&gt;",
  "status": "&lt;STATUS&gt;",
  "category": "&lt;CATEGORY&gt;"
}
Learn more about messaging success responses

​
Error response

Possible errors that can occur: Invalid whatsapp-business-account-id Permissions/Authorization errors Template structure/component validation alerts View general Cloud API Error Codes here

​
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, however you can learn more about how to send message templates here.

​
Request syntax

POST/&lt;PHONE_NUMBER_ID&gt;/messages
ParameterDescriptionSample Value
&lt;PHONE_NUMBER_ID&gt;
String		Required
The business phone number which you are sending a message from.
Learn more about formatting phone numbers in Cloud API		+18762639988

​
Request body

\{
  "to": "14085551234",
  "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

ParameterDescriptionSample Value
ttl_minutes
Integer		Optional
Time to live for the CTA button in minutes.
Must be between 1 and 43200 (30 days)
Default value is 10080 (7 days)		10800
payload
String		Optional
An arbitrary string, useful for tracking.
Any app subscribed to the calls webhook field on the WhatsApp Business Account can get this string, as it is included in the connect and terminate webhook payloads under the cta_payload field.
Cloud API does not process this field, it just returns it as part of the webhooks.
Maximum 512 characters.
Payload is only available to WhatsApp client starting on version 2.25.27.		payload data

​
Success response

Image Learn more about messaging success responses Calling deep links are hyperlinks that route WhatsApp users to call your business. The process to create a calling deep link is the similar to a chat deep link, except the format for call deeplink is wa.me/call/&lt;BUSINESS_PHONE_NUMBER&gt; Note that deep links are not supported on WhatsApp desktop clients. You can use calling deep links to advertise WhatsApp calling for your business Use these links anywhere where calling can be useful, like your website, primary application, or even as a QR code to be shared. Image 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/&lt;BUSINESS_PHONE_NUMBER&gt; format is easy to copy, paste, and send, and does not require you to make a template in Business Manager. Image You also have the option to send a payload with the deeplink. You can use the biz_payload query string when sending the call deeplink to any user (wa.me/call/&lt;BUSINESS_PHONE_NUMBER&gt;?biz_payload=payload). When a user calls using the provided deeplink with the biz_payload any app subscribed to the calls webhook field on the WhatsApp Business Account can get this string, as it is included in the connect and terminate webhook payloads under the deeplink_payload field. Payload in call deeplink is only available to WhatsApp client starting on version 2.25.27. Did you find this page helpful? Thumbs up icon Thumbs down icon ON THIS PAGE Overview Send interactive message with a WhatsApp Call Button Request Syntax Request Body Body Parameters Success response Error response Create and send WhatsApp call button template message Create call button message template Request syntax Request body Body parameters Success response Error response Send call button message template Request syntax Request body Request parameters Success response Calling deep links Embed calling deep links Send calling deep links Send payload data in call deeplink