Templates API - V1
Looking to manage templates (create, update, delete)? See the Template Management 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,UTILITYorAUTHENTICATION. - 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)
- a carousel of cards, each with its own media header, body text, and buttons (see Carousel Templates)
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
}
]
}
]
}
Authentication Templates
Authentication templates are specifically designed for sending one-time passwords (OTPs), verification codes, and other authentication-related messages.
- AUTHENTICATION templates must include a one-time password or verification code
Basic Authentication Template Example with COPY CODE button
Here's how to send an authentication template with an OTP code:
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "otp_verification",
"category": "AUTHENTICATION",
"language": "en",
"clientRef": "auth_123",
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "123456",
"index": 0
}
]
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "URL",
"text": "123456",
"index": 0
}
]
}
]
}
Authentication with OTP Code and contact number
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "otp_with_contact_number",
"category": "AUTHENTICATION",
"language": "en",
"clientRef": "auth_456",
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "789012",
"index": 0
},
{
"type": "text",
"text": "277299999999",
"index": 1
}
]
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"text": "789012",
"index": 0
}
]
}
]
}
Authentication with multiple parameters i.e OTP code, amount & contact number
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "otp_with_details",
"category": "AUTHENTICATION",
"language": "en",
"clientRef": "auth_789",
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "123456",
"index": 0
},
{
"type": "text",
"text": "$50.00", // must include the currency symbol
"index": 1
},
{
"type": "text",
"text": "1234567890",
"index": 2
}
]
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"text": "123456",
"index": 0
}
]
}
]
}
Carousel Templates
Carousel templates allow you to send a horizontally scrollable set of cards in a single WhatsApp message. Each card can have its own image or video header, body text with personalised parameters, and buttons. This is useful for showcasing multiple products, services, or options in a single message.
Your carousel template must be pre-approved by WhatsApp before you can use it. Each card in the carousel must have the same structure (e.g. all cards must have image headers, or all must have video headers).
Carousel example
Here's how to send a carousel template with two cards, each containing a media header, personalised body text, and a URL button.
POST https://api.cuedesk.com/v1/messages/whatsapp
Authorization: Bearer <token>
Content-Type: application/json
{
"to": "447576209857",
"from": "<your_whatsapp_number>",
"type": "template",
"templateName": "<carousel_template_name>",
"category": "MARKETING",
"language": "en",
"clientRef": "carousel_123",
"components": [
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "Jamie", // Template-level body parameter (e.g. recipient name)
"index": 0
}
]
},
{
"type": "CARDS",
"cards": [
{
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "image",
"link": "https://example.com/product1.jpg"
}
]
},
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "Running Shoes",
"index": 0
},
{
"type": "text",
"text": "$99.00",
"index": 1
}
]
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "URL",
"text": "running-shoes-123", // URL suffix appended to the button URL
"index": 0
}
]
}
]
},
{
"components": [
{
"type": "HEADER",
"parameters": [
{
"type": "image",
"link": "https://example.com/product2.jpg"
}
]
},
{
"type": "BODY",
"parameters": [
{
"type": "text",
"text": "Casual Sneakers",
"index": 0
},
{
"type": "text",
"text": "$79.00",
"index": 1
}
]
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "URL",
"text": "casual-sneakers-456",
"index": 0
}
]
}
]
}
]
}
]
}
Carousel component structure
Each carousel template message includes a CARDS component in the components array. The CARDS component contains a cards array where each card has its own nested components.
| Attribute | Type | Description |
type | Required | Must be CARDS. |
cards | Required | Array of card objects. Each card represents one slide in the carousel. |
cards[].components | Required | Array of component objects for this card. Each card can have a HEADER, BODY, and BUTTONS component. |
Each card's components follow the same structure as the top-level Header, Body, and Buttons components described above. The key difference is that these are scoped to a single card within the carousel.
You can also include a top-level BODY component alongside the CARDS component for template-level personalisation (e.g. a greeting that appears above the carousel). Note that top-level BUTTONS are not supported on carousel templates -- buttons are defined per card only.