Skip to main content

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 or AUTHENTICATION.
  • 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"
}
AttributeTypeDescription
toRequiredThe WhatsApp mobile number of the message recipient. It must be formatted with the international country code. For example: 447576209857
fromRequiredYour WhatsApp Business number.
typeRequiredPossible values can be template.
templateNameRequiredThe name of your approved template in Meta Business Manager.
languageRequiredSee list of supported languages.
categoryRequiredThis can be either MARKETING, UTILITY or AUTHENTICATION. WhatsApp charges different rates for different categories of templates. See their rate cards for more information.
clientRefOptionalThis 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.

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
}
]
}
]
}