Close mobile menu

WhatsApp Message Templates

When initiating a conversation with a customer, WhatsApp requires you to use a pre-approved message template called a Message Template (previously referred to as a Highly Structured Message or HSM.

Notification icon

Message Template registration can take up to 15 working days.

Every Message Template needs to be approved by WhatsApp before it can be used; when submitting the Message Template, you should keep in mind that it needs to contain the full body of the message, with the option to add unique parameters represented as placeholders.

Please keep in mind at least one parameter is required when submitting an Message Template. 

Writing a Message Template

For example, the message:

Name: Account Registration

Hi Joey! Thanks for starting your personal training plan. We’ll send you a weekly update with your new schedule. You can log-in online using your training ID 123456. Stay fit!

Needs to be submitted as:

Name: account_registration

Hi {{1}}! Thanks for starting your personal training plan. We’ll send you a {{2}} update with your new schedule. You can log-in online using your training ID {{3}}. Stay fit!

The Message Template uses numbered placeholders '{{x}}' for each variable in the message. Each variable can be replaced with text that contains letters, digits, special characters, or spaces. Each Message Template needs at least one parameter. Additionally, the name of the Message Template needs to be formatted in small letters only and spaces need to be replaced with an underscore. 

One of the unique features of WhatsApp is that it offers locale editing. When sending the Message Template, WhatsApp will identify the language of the recipient WhatsApp account, and if a locale Message Template has been submitted, that language will be used. 

Sending a Message Template

In order to input actual variables into a Message Template, you will need to send parameter values instead of sending the full message.

For the following example Message Template:

Hi {{1}}, your order has been shipped and should arrive {{2}}

You will need to send the following example request:

$ curl -X "POST" "https://conversations.messagebird.com/v1/conversations/2e15efafec384e1c82e9842075e87beb/messages" \
-H "Authorization: AccessKey gshuPaZoeEG6ovbc8M79w0QyM" \
-H "Content-Type: application/json" \
--data '{
"type": "hsm",
"content":{
"hsm": {
"namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
"templateName": "order_update",
"language": {
"policy": "deterministic",
"code": "en"
},
"params": [
{"default": "Bob"},
{"default": "tomorrow!"}
]
}
}

If the request was successful, you can expect to see a response similar to:

{
"id": "2ec3d1e8725f41b1933906426738e6a5",
"conversationId": "2e15efafec384e1c82e9842075e87beb",
"channelId": "aa4c8e7cee664341a22ef9bfd9f52477",
"status": "pending",
"type": "hsm",
"direction": "sent",
"content": {
"hsm": {
"namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
"templateName": "order_update",
"language": {
"policy": "deterministic",
"code": "en"
},
"params": [
{
"default": "Bob"
},
{
"default": "tomorrow!"
}
]
}
},
"createdDatetime": "2018-08-29T13:53:44.642664784Z",
"updatedDatetime": "2018-08-29T13:53:44.673850825Z"
}

If you the request was unsuccessful, don't worry, head over to Troubleshooting to resolve the problem. If you're still stuck, please reach out to support@messagebird.com; we're here to help.

Next steps

You may now want to check out these resources:

Questions?

We’re always happy to help with code or other questions you might have! Search our API Reference, check the Developer tutorials or contact support.

Cookie Settings