Message Template API
Allows you to send WhatApp message templates to Contacts in the platform.
Channel token is required to access this API resource.
Tokens can be generated by using the key icon, next to the desired channel in Settings.
The Message Template API is composed of several types of requests:
Path variable for the message template API request. contactcId is the phone number of the recipient. The sample value for different WhatsApp Partner is listed in the table below.
WhatsApp Provider | Description | Sample Value |
|---|---|---|
Cloud API | without + | 60123456789 |
360 Dialog | without + | 60123456789 |
Vonage | without + | 60123456789 |
MessageBird | without + | 60123456789 |
Twilio | whatsapp:<number with plus> | whatsapp:+60123456789 |
Before sending a Template Message to a contact at respond.io platform using Message Template API, please ensure you did the following:
- Have an approved message template
- Synced the message templates to respond.io platform
- Use the exact template content as configured on WhatsApp Business Manager in the request body to prevent any mismatch between message sent to the contact and message appear in the messages module
This request sends a message template with body text only directly to the Contact as per defined in the Endpoint.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with Body Text Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "bug_fixed",
"languageCode": "en",
"components": [
{
"type": "body",
"text": "Good news! 😀\nWe have fixed the bug that you reported, \nPlease run some tests and let us know how it worked."
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Sample Value |
|---|---|---|---|
type | String | Yes | body |
text | String | Yes | This is a message template |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
}
This request sends a message template with body parameters directly to the Contact as per defined in the Endpoint.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with Body Parameters Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "account100",
"languageCode": "en",
"components": [
{
"type": "body",
"text": "Hi {{1}}, your account has reached {{2}} of your contact limit.\nTo prevent losing conversations, increase your contact limit {{3}}. Feel free to reach out with any questions.",
"parameters": [
{
"type": "text",
"text": "Parameter 1"
},
{
"type": "text",
"text": "Parameter 2"
},
{
"type": "text",
"text": "Parameter 3"
}
]
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | body |
text | String | Yes | This is a message template |
parameters | Array | Yes | Refer to the Parameters Array table below for details |
Parameters Array
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | text |
text | String | Yes | Supports any plain text values, standard fields, custom fields as well as formatting |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
}
This request sends a message template with header directly to the Contact as per defined in the Endpoint.
Please note that this API request is only available for 360 Dialog and Vonage.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with Header Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "account_update_en",
"languageCode": "en",
"components": [
{
"type": "header",
"format": "text",
"text": "Respond team is here for you"
},
{
"type": "body",
"text": "Hi, your account has been updated."
},
{
"type": "footer",
"text": "Have a nice day"
},
{
"type": "buttons",
"buttons": [
{
"type": "url",
"text": "Visit Us",
"url": "https://www.respond.io/"
}
]
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | header |
format | String | Yes | Refer to text OR Image / Document / Video Format table |
Text Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
text | String | Yes | This is a header text |
parameters | Array | No | Note that we only need to include the parameters array if the header text contains parameters. { type: "text", text: "parameter 1 OR @contact.field OR @field.custom_field" } |
Image / Document / Video Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
parameters | Array | Yes | Refer to the Parameter Object below for details on the array |
Parameter Object
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | image OR video OR document |
image OR document OR video | Object | Yes |
Image / Document / Video Object
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
link | String | Yes | |
filename | String | No | sample.jpg |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
}
This request sends a message template with CTA buttons directly to the Contact as per defined in the Endpoint.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with CTA Buttons Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "delivery_order",
"languageCode": "en",
"components": [
{
"type": "header",
"format": "image",
"parameters": [
{
"type": "image",
"image": {
"link": "https://picsum.photos/200/300"
}
}
]
},
{
"type": "body",
"text": "Hi {{1}} your order {{2}} is on the way! To track your delivery, simply click on the delivery partner'\''s link or updates.",
"parameters": [
{
"type": "text",
"text": "abc"
},
{
"type": "text",
"text": "abc"
}
]
},
{
"type": "footer",
"text": "For more inquiries, simply reply to this message."
},
{
"type": "buttons",
"buttons": [
{
"type": "url",
"text": "Track Your Parcel",
"url": "https://www.respond.io/"
},
{
"type": "phone_number",
"text": "Customer Care",
"phone_number": "+60123456789"
}
]
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | buttons |
button | Array | Yes | Refer to the Button Object table below for details on the array |
Button Object
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | url |
text | String | Yes | Button Text |
url | String | Yes | |
phone_number | String | Yes | If button type is "phone_number", then we need to include this e.g. +60123456789 |
parameters | Array | Yes | If button type is "url" and contains parameters, then we need to include the parameter text e.g. { type: "text", text: "button_parameter_text" } |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
This request sends a message template with quick replies directly to the Contact as per defined in the Endpoint.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with Quick Replies Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "account_update_en",
"languageCode": "en",
"components": [
{
"type": "header",
"format": "text",
"text": "Respond team is here for you"
},
{
"type": "body",
"text": "Hi, your account has been updated."
},
{
"type": "footer",
"text": "Have a nice day"
},
{
"type": "buttons",
"buttons": [
{
"type": "quick_reply",
"text": "Yes"
},
{
"type": "quick_reply",
"text": "No"
},
{
"type": "quick_reply",
"text": "Will confirm later"
}
]
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | buttons |
button | Array | Yes | Refer to the Button Object table below for details on the array |
Button Object
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | quick_reply |
text | String | Yes | Quick Reply Option 1 |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
}
This request sends a message template with footer directly to the Contact as per defined in the Endpoint.
Please note that this API request is only available for 360 Dialog and Vonage.
POST /v1/message/sendContent/{contactcId}
Sample POST Template with Footer Request
curl -X POST \
'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
-H 'Authorization: Bearer {channel_token}' \
-H 'Content-Type: application/json' \
-d '{
"body": [
{
"type": "whatsapp_template",
"template": {
"name": "account_update_en",
"languageCode": "en",
"components": [
{
"type": "header",
"format": "text",
"text": "Respond team is here for you"
},
{
"type": "body",
"text": "Hi, your account has been updated."
},
{
"type": "footer",
"text": "Have a nice day"
},
{
"type": "buttons",
"buttons": [
{
"type": "url",
"text": "Visit Us",
"url": "https://www.respond.io/"
}
]
}
]
}
}
]
}'
Component Format
Fields | Type | Mandatory | Example Value |
|---|---|---|---|
type | String | Yes | footer |
text | String | Yes | This is a footer text |
Response - Success (HTTP status → 201)
{
"status": "success",
"message": "Message Sent",
"data": {
"id": {{id}}
},
"trace": []
}
{
"status": "error",
"message": "API Token is invalid.",
"data": []
}
{
"status": "error",
"message": "Too many requests",
"data": []
}
{
"status": "error",
"message": "405 Method Not Allowed.",
"data": []
}
{
"status": "error",
"message": "Message String",
"data": []
}
{
"status": "error",
"message": "Sorry, Url provided is not an image/audio/video file",
"data": []
}
WhatsApp template with body text only
What happens if I send template text that does not match exactly with the one configured on WhatsApp Business Manager?
The contact will receive the template as configured on the WhatsApp Business Manager. However, on the Messages module of respond.io, it will appear as sent from the Messaging API. To prevent this mismatch, we advise you to use the exact template text in the request body
What happens if I do not include formatted text in the API request but my template has formatting included?
Similar to the case above, the contact will receive the template as configured on the WhatsApp Business Manager. However, on the Messages module of respond.io, it will appear as sent from the Messaging API. To prevent this mismatch, we advise you to use the exact template text in the request body
Since the contact will always receive the message configured on WhatsApp Business Manager, can I omit the text when sending the request?
If you omit the text, the contact will still receive the intended template message however it will not appear on the respond.io Messages module. To prevent this mismatch, we advise you to use the exact template text in the request body
WhatsApp template with body parameters
What happens if I do not include the parameters / have incorrect number of parameters in the request?
The template message will not be sent to the contact and an error code will be returned from the API as well as displayed on the Messages module
What happens if I use a deleted custom field as a parameter value?
The template message will be still be sent but the parameter value will be treated as a literal string instead
Can I format the parameter values?
Yes you may format the parameter values. Supported formatting are bold (e.g. Parameter 1), italics (Parameter 1), monospace (
Parameter 1) and strikethrough (Parameter 1).Can I omit the body text and only include the correct number of parameters?
The contact will receive the template as configured on the WhatsApp Business Manager with the parameter values sent. However, on the Messages module of respond.io, it will appear as sent from the Messaging API. To prevent this mismatch, we advise you to use the exact template text in the request body
WhatsApp Template with Header
What happens if I do not include the parameters / have incorrect number of parameters in the request?
The template message will not be sent to the contact and an error code will be returned from the API as well as displayed on the Messages module
If the header has no parameters, can I omit it from the request?
If you omit the header component from the request, the contact will still receive the header as part of the message however the header text will not be reflected on respond.io Messages module. In light of this, it is best to always include the header text on the API as well so as to sync up the behavior between respond.io Messages module and contact WhatsApp
What happens if I do not include filename values for image / video / document type headers?
For image and video files, the message will still be sent and will be reflected accordingly on both the contact phone and on respond.io Messages module. For document type header, if filename is omitted, the Messages module will display the document correctly but the contact message will have the file attachment displayed as null.pdf. In light of this, to keep the behavior consistent, please have the filename included as best practice
What format should image / video / document URL be?
Image / Video / Document URL should be a valid URL with http / https format and should be resolvable. Prior to including the image URL, try opening the image URL on a browser window and ensure that the image is loaded to ensure that it is working properly
WhatsApp template with CTA buttons
What happens if I do not include the parameters / have incorrect number of parameters in the request?
The template message will not be sent to the contact and an error code will be returned from the API as well as displayed on the Messages module
What happens if I do not include / partially include button options if the buttons do not include parameters?
The message sent to the contact will still contain all the buttons as configured in WhatsApp Business Manager. However, the Messages module on respond.io will not reflect this and may cause a mismatch. In light of this, it is best to have the button component included in the request body
WhatsApp template with quick replies
What happens if I do not include / partially include quick reply options?
The message sent to the contact will still contain all the quick reply as configured in WhatsApp Business Manager. However, the Messages module on respond.io will not reflect this and may cause a mismatch. In light of this, it is best to have the quick reply text included in the request body
What happens if the quick replies option does not match?
The message sent to the contact will still contain all the quick reply as configured in WhatsApp Business Manager. However, the Messages module on respond.io will not reflect this and may cause a mismatch. In light of this, it is best to have the quick reply text match the values configured on WhatsApp Business Manager
WhatsApp template with footer
Can I omit the footer component from the request since it is static?
If you omit the footer component from the request, the contact will still receive the footer as part of the message however the footer text will not be reflected on respond.io Messages module. In light of this, it is best to always include the footer text on the API as well so as to sync up the behavior between respond.io Messages module and contact WhatsApp
What happens if I send footer text that does not match exactly with the one configured on WhatsApp Business Manager?
The contact will receive the template as configured on the WhatsApp Business Manager. However, on the Messages module of respond.io, it will appear as sent from the Messaging API. To prevent this mismatch, we advise you to use the exact template text in the request body
Last modified 1mo ago