Message Template API

Allows you to send WhatsApp 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.

Requests

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 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 heyx.io platform using Message Template API, please ensure you did the following:

  • Have an approved message template

  • Synced the message templates to heyx.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.

POST /v1/message/sendContent/{contactcId}

Sample POST Template with Body Text Request

curl -X POST \ 
        'https://app.heyx.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": []
}

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.

POST /v1/message/sendContent/{contactcId}

Sample POST Template with Body Parameters Request

curl -X POST \ 
        'https://app.heyx.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": []
}

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. 

POST /v1/message/sendContent/{contactcId}

Sample POST Template with Header Request

curl -X POST \ 
        'https://app.heyx.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": "heyx 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.heyx.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": []
}

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.

POST /v1/message/sendContent/{contactcId}

Sample POST Template with CTA Buttons Request

curl -X POST \ 
        'https://app.heyx.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.heyx.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": []

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.

POST /v1/message/sendContent/{contactcId}

Sample POST Template with Quick Replies Request

curl -X POST \ 
        'https://app.heyx.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": "heyx 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": []
}

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. 

POST /v1/message/sendContent/{contactcId}

Sample POST Template with Footer Request

curl -X POST \ 
        'https://app.heyx.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": "heyx 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.heyx.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": []
}

Error Codes

Unauthorized (HTTP Status → 401)

  {
        "status": "error",
        "message": "API Token is invalid.",
        "data": []
  }

Too Many Requests (HTTP Status → 429)

  {
      "status": "error",
      "message": "Too many requests",
      "data": []
  }

Method Not Allowed (HTTP Status → 405)

  {
      "status": "error",
      "message": "405 Method Not Allowed.",
      "data": []
  }

General (HTTP Status → 403)

  {
      "status": "error",
      "message": "Message String",
      "data": []
  }

Unmatched File Type (HTTP Status → 403)

  {
      "status": "error",
      "message": "Sorry, Url provided is not an image/audio/video file",
      "data": []
  }

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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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 heyx.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

PreviousMessages API

Last updated