Templates API
WhatsApp allows you to send pre-approved message templates to users without them having to interact with your WhatsApp Business number first.
Overview
- Your template must be approved by WhatsApp before you can use it. Our team can help you with this.
- Each template must be categorised as either
MARKETING
,UTILITY
orAUTHENTICATION
. - Templates can include:
- parameters for personalisation (e.g. name, order number or anything else)
- a text, image, video, document or location header
- up to three buttons (Quick Reply, Link or Call)
Basic example
Here's how to send a basic WhatsApp template with no personalisation to someone using the Messages API. See the authentication page for how to obtain a bearer token.
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<template_name>",
"category": "MARKETING",
"language": "en",
"clientRef": "123"
}
Attribute | Type | Description |
to | Required | The WhatsApp mobile number of the message recipient. It must be formatted with the international country code. For example: 447576209857 |
from | Required | Your WhatsApp Business number. |
type | Required | Possible values can be template . |
templateName | Required | The name of your approved template in Meta Business Manager. |
language | Required | See list of supported languages. |
category | Required | This can be either MARKETING , UTILITY or AUTHENTICATION . WhatsApp charges different rates for different categories of templates. See their rate cards for more information. |
clientRef | Optional | This is an optional custom ID that you can set on a message that will be returned with message status updates. |
Components
You can personalise data in your WhatsApp Template by adding component objects to the components
array in the request body. The components must already exist in your pre-approved WhatsApp template but you can override their properties at send time to personalise the message for each recipient.
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<template_name>",
"category": "MARKETING",
"language": "en",
"clientRef": "123",
"components": []
}
The component object types you can use are HEADER
, BODY
and BUTTONS
. You can include up to one of each component per message. If your WhatsApp Template has a component but you don't override the component data at send time then the default component data specified in your component when created will be used.
Below you can find information how about to structure each component object.
Header
If your template has a media header you can provide the media at send time by adding a HEADER
object to the components
array.
You cannot override your template with a different media type. If your template has an image header, you can only provide an image at send time, you cannot send a document or video.
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<template_name>",
"category": "UTILITY",
"language": "en",
"clientRef": "123",
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "image", // Can be text, image or video or document
"link": "media_url", // For image, video or document
"text": "Header text", // For text only
}
]
}
]
}
Body
If you want to insert personalised information into the text of your template you can do this by adding a BODY
object to the components
array in the request body.
Here is an example of what the body text in your template might look like in Meta Business Manager.
Hello {{1}}, your order #{{2}} has been dispatched and will be delivered on {{3}}.
You can then include a BODY
object with the parameters to be inserted into the text as per the example below.
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<template_name>",
"category": "UTILITY",
"language": "en",
"clientRef": "123",
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "Jamie",
"index": 0
},
{
"type": "text",
"text": "2641",
"index": 1
},
{
"type": "text",
"text": "Wed, 26 July",
"index": 2
}
]
}
]
}
Buttons
To override the button data for your template you can add a BUTTONS
object to the components
array in the request body. Here's an example of a request the three types of buttons available.
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<template_name>",
"category": "UTILITY",
"language": "en",
"clientRef": "123",
"components": [
{
"type":"BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Yes",
"index": 0
},
{
"type":"URL",
"text": "ABC123", // Parameter to be added to the URL
"index": 1
},
{
"type":"PHONE_NUMBER",
"text": "Call us",
"phone_number": "123456",
"index": 2
}
]
}
]
}