WhatsApp Message Templates

When initiating a conversation with a customer, WhatsApp requires you to use a pre-approved Message Template (previously referred to as a Highly Structured Message or HSM). In this quickstart, you'll learn how to write and send a Message Template using cURL.

Every Message Template needs to be approved by WhatsApp before it can be used. WhatsApp generally takes a couple of days to approve or reject a template, but this may vary depending on the language.

When submitting the Message Template, keep in mind that it needs to contain the full body of the message (with the option to add unique parameters represented as placeholders) and at least one parameter.

But wait, how can you submit a WhatsApp Message Template? We're glad you asked, you can do it via the WhatsApp Template Manager on the MessageBird Dashboard.

Writing a Message Template

For example, the message:

Name: Account Registration

Hi Anna! 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. For our example, {{1}} is the name or the customer, {{2}} is what the company is sending to the customer, {{3}} is the training ID of that specific client.

Remember that each Message Template needs at least one parameter. The name of the Message Template needs to be formatted in small letters only, and the spaces must 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. If a locale Message Template has been submitted, that specific language will be used.

Sending a Message Template

To input actual variables into a Message Template, you'll need to send parameter values instead of sending the full message.

For the following Message Template example:

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

In order to send a template message, you must perform the following HTTP request to Conversations API. The following example uses the endpoint POST /v1/send, however, you can use any of the endpoints for sending messages, please check the Conversations API reference for details about it.

curl -X "POST" "https://conversations.messagebird.com/v1/send" \
-H "Authorization: AccessKey {your-access-key}" \
-H "Content-Type: application/json" \
--data '{
    "type": "hsm",
    "to": "+31XXXXXXXXX",
    "from": "aa4c8e7cee664341a22ef9bfd9f52477",
    "content": {
        "hsm": {
            "namespace": "5ba2d0b7_f2c6_433b_a66e_57b009ceb6ff",
            "templateName": "order_update",
            "language": {
                "policy": "deterministic",
                "code": "en"
            },
            "params": [
                {
                    "default": "Bob"
                },
                {
                    "default": "tomorrow!"
                }
            ]
        }
    }
}'

If the request is successful, the response will be similar to this:

{
  "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 the request is unsuccessful, head over to the Conversations API Troubleshooting to understand the error; if you're still stuck, feel free to contact us—we're happy to help you out.