Message Template API

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. 
Requests
The Message Template API is composed of several types of requests:
​Sending WhatsApp template with body text only​
​Sending WhatsApp template with body parameters​
​Sending WhatsApp template with header​
​Sending WhatsApp template with CTA buttons​
​Sending WhatsApp template with quick replies​
​Sending WhatsApp template with footer 
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 Partner
Description
Sample Value
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 
Sending WhatsApp Template with Body Text only
This request sends a message template with body text only directly to the Contact as per defined in the Endpoint.
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with Body Text Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
    "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "bug_fixed",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "body",
15
                        "text": "Good news! 😀\nWe have fixed the bug that you reported, \nPlease run some tests and let us know how it worked."
16
                    }
17
                ]
18
            }
19
        }
20
    ]
21
}'
Copied!
Component Format
Fields
Type
Mandatory
Sample Value
type
String
Yes
body
text
String
Yes
This is a message template
​
Response - Success (HTTP status → 201)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
}
Copied!
Sending WhatsApp Template with Body Parameters
This request sends a message template with body parameters directly to the Contact as per defined in the Endpoint.
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with Body Parameters Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
    "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "account100",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "body",
15
                        "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.",
16
                        "parameters": [
17
                            {
18
                                "type": "text",
19
                                "text": "Parameter 1"
20
                            },
21
                            {
22
                                "type": "text",
23
                                "text": "Parameter 2"
24
                            },
25
                            {
26
                                "type": "text",
27
                                "text": "Parameter 3"
28
                            }
29
                        ]
30
                    }
31
                ]
32
            }
33
        }
34
    ]
35
}'
Copied!
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)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
}
Copied!
Sending WhatsApp template with header
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. 
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with Header Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
    "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "account_update_en",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "header",
15
                        "format": "text",
16
                        "text": "Respond team is here for you"
17
                    },
18
                    {
19
                        "type": "body",
20
                        "text": "Hi, your account has been updated."
21
                    },
22
                    {
23
                        "type": "footer",
24
                        "text": "Have a nice day"
25
                    },
26
                    {
27
                        "type": "buttons",
28
                        "buttons": [
29
                            {
30
                                "type": "url",
31
                                "text": "Visit Us",
32
                                "url": "https://www.respond.io/"
33
                            }
34
                        ]
35
                    }
36
                ]
37
            }
38
        }
39
    ]
40
}'
Copied!
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
Refer to the table below for details on the object
Image / Document / Video Object
Fields
Type
Mandatory
Example Value
link
String
Yes
​https://res.cloudinary.com/demo/image/upload/v1312461204/sample.jpg​
filename
String
No
sample.jpg
​
Response - Success (HTTP status → 201)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
}
Copied!
Sending WhatsApp Template with CTA Buttons
This request sends a message template with CTA buttons directly to the Contact as per defined in the Endpoint.
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with CTA Buttons Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
     "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "delivery_order",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "header",
15
                        "format": "image",
16
                        "parameters": [
17
                            {
18
                                "type": "image",
19
                                "image": {
20
                                    "link": "https://picsum.photos/200/300"
21
                                }
22
                            }
23
                        ]
24
                    },
25
                    {
26
                        "type": "body",
27
                        "text": "Hi {{1}} your order {{2}} is on the way! To track your delivery, simply click on the delivery partner'\''s link or updates.",
28
                        "parameters": [
29
                            {
30
                                "type": "text",
31
                                "text": "abc"
32
                            },
33
                            {
34
                                "type": "text",
35
                                "text": "abc"
36
                            }
37
                        ]
38
                    },
39
                    {
40
                        "type": "footer",
41
                        "text": "For more inquiries, simply reply to this message."
42
                    },
43
                    {
44
                        "type": "buttons",
45
                        "buttons": [
46
                            {
47
                                "type": "url",
48
                                "text": "Track Your Parcel",
49
                                "url": "https://www.respond.io/"
50
                            },
51
                            {
52
                                "type": "phone_number",
53
                                "text": "Customer Care",
54
                                "phone_number": "+60123456789"
55
                            }
56
                        ]
57
                    }
58
                ]
59
            }
60
        }
61
    ]
62
}'
Copied!
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
If button type is "url", then we need to include this e.g. https://respond.io​
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)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
​
Copied!
Sending WhatsApp Template with Quick Replies
This request sends a message template with quick replies directly to the Contact as per defined in the Endpoint.
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with Quick Replies Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
     "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "account_update_en",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "header",
15
                        "format": "text",
16
                        "text": "Respond team is here for you"
17
                    },
18
                    {
19
                        "type": "body",
20
                        "text": "Hi, your account has been updated."
21
                    },
22
                    {
23
                        "type": "footer",
24
                        "text": "Have a nice day"
25
                    },
26
                    {
27
                        "type": "buttons",
28
                        "buttons": [
29
                            {
30
                                "type": "quick_reply",
31
                                "text": "Yes"
32
                            },
33
                            {
34
                                "type": "quick_reply",
35
                                "text": "No"
36
                            },
37
                            {
38
                                "type": "quick_reply",
39
                                "text": "Will confirm later"
40
                            }
41
                        ]
42
                    }
43
                ]
44
            }
45
        }
46
    ]
47
}'
Copied!
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)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
}
Copied!
Sending WhatsApp template with Footer
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. 
1
POST /v1/message/sendContent/{contactcId}
Copied!
Sample POST Template with Footer Request
1
curl -X POST \ 
2
        'https://app.respond.io/api/v1/message/sendContent/{{contactcId}}' \
3
        -H 'Authorization: Bearer {channel_token}' \
4
        -H 'Content-Type: application/json' \
5
        -d '{
6
     "body": [
7
        {
8
            "type": "whatsapp_template",
9
            "template": {
10
                "name": "account_update_en",
11
                "languageCode": "en",
12
                "components": [
13
                    {
14
                        "type": "header",
15
                        "format": "text",
16
                        "text": "Respond team is here for you"
17
                    },
18
                    {
19
                        "type": "body",
20
                        "text": "Hi, your account has been updated."
21
                    },
22
                    {
23
                        "type": "footer",
24
                        "text": "Have a nice day"
25
                    },
26
                    {
27
                        "type": "buttons",
28
                        "buttons": [
29
                            {
30
                                "type": "url",
31
                                "text": "Visit Us",
32
                                "url": "https://www.respond.io/"
33
                            }
34
                        ]
35
                    }
36
                ]
37
            }
38
        }
39
    ]
40
}'
Copied!
Component Format
Fields
Type
Mandatory
Example Value
type
String
Yes
footer
text
String
Yes
This is a footer text
Response - Success (HTTP status → 201)
1
{
2
    "status": "success",
3
    "message": "Message Sent",
4
    "data": {
5
        "id": {{id}}
6
    },
7
    "trace": []
8
}
Copied!
Error Codes
Unauthorized (HTTP Status → 401)
1
  {
2
        "status": "error",
3
        "message": "API Token is invalid.",
4
        "data": []
5
  }
Copied!
Too Many Requests (HTTP Status → 429)
1
  {
2
      "status": "error",
3
      "message": "Too many requests",
4
      "data": []
5
  }
Copied!
Method Not Allowed (HTTP Status → 405)
1
  {
2
      "status": "error",
3
      "message": "405 Method Not Allowed.",
4
      "data": []
5
  }
Copied!
General (HTTP Status → 403)
1
  {
2
      "status": "error",
3
      "message": "Message String",
4
      "data": []
5
  }
Copied!
Unmatched File Type (HTTP Status → 403)
1
  {
2
      "status": "error",
3
      "message": "Sorry, Url provided is not an image/audio/video file",
4
      "data": []
5
  }
Copied!
Frequently Asked Questions
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