Table of Contents

WhatsApp's Message Templates (HSM)

Xandro Lopez Updated by Xandro Lopez

What is an HSM template?

A Highly-Structured Message (HSM) is a Message Template that is required for proactive/outbound messaging in Whatsapp.

WhatsApp must approve your HSMs before you can start sending them to users.

They are necessary because of the limitations defined by WhatsApp, according to how it accepts the brands to use their API channel.

These messages can be sent to initiate a conversation with your clients or to re-activate them once the 24-hour WhatsApp support window is closed.

Guidelines to Request a HSM Template

Since HSM templates can be either Approved ✅ or Rejected ❌ by WhatsApp, it is important to keep some things in mind.

The first is that all HSMs are approved case-by-case, so a template that was approved for one company may be rejected for yours.

It might also take a few attempts to get your HSM approved.

Whatsapp's Guidelines

In order to have a higher chance ✅ to get your HMS templates approved, make sure that:

  • your use cases for messaging comply with WhatsApp's Business Policy and WhatsApp Commerce Policy.
  • make sure your HSMs fit the use case you have submitted.
  • make sure you select the template category that best suits your use case.

WhatsApp will very likely reject ❌ your template if it contains:

  • Brands asking for reviews or surveys.
  • Brands advertising products, services or events the customer may like (whether or not it is based on purchasing or browsing behaviour).

Keep in mind that message templates are intended to provide a better user experience rather than marketing campaigns.

Please click here to check Facebook's official Message Template Guideline documentation to comply with Whatsapp's requirements to approve Templates.

How to request a template

Message Templates Section

To manage or request HSM Templates, you must access the Message Templates section, available in the Whatsapp Business or Whatsapp Pro channels.

To access it, click on Channels > WhatsApp Business/WhatsApp Pro > Message Templates

Go to the Message template section and click the button in the top right corner which says "Request Message Template"

This will open a small window that will ask for all the template details.

Below you'll find an explanation of each field you need to fill out.

Template name

When creating a message template, it is mandatory to give it a name.

It is advised to use a name that reflects the template’s content.

This name must have no more than 512 characters and may only contain lowercase letters, numbers, and underscores.

No other characters or white space are allowed. 

Example

order_confirmation123 ✅

Order_Confirmation123 ❌

order confirmation 123 ❌

Category

When submitting a message template, it is required to choose a category.

This makes it easier for WhatsApp to review and approve a template by providing context for how the message template will be used.

The category values are described below:

Template category

Use case explanation

Example

Account Update

Notify the user about a change in their account settings

  • Membership expiry
  • Settings have changed
  • Password has changed
  • Preferences have changed

Payment Update

Notify the user about a payment update for an existing transaction

  • Send a receipt
  • Status of a payment transaction has changed

Personal Finance Update

Confirm a users financial activity

  • Payment reminders
  • Fund transfer confirmation or update
  • Payment receipt confirmation

Shipping Update

Notify the user of a change in shipping status for a purchased product

  • Shipping confirmation
  • Status change
  • Product delivery

Reservation Update

Notify the user of any changes/updates in their reservation

  • Booking confirmation
  • Booking cancellation
  • Itinerary changes

Issue Resolution

Notify the user of a customer service issue resolution update

  • Issue is resolved
  • Request for additional information
  • Issue status update

Appointment Update

Notify the user of a change in an appointment

  • Appointment cancelation
  • Appointment time change

Transportation Update

Notify the user of a change in their transportation reservation

  • Change in a flight
  • Trip cancelled

Ticket Update

Updates or reminders for an event that the user has already purchased tickets for

  • Event changes
  • Event cancellation

Alert Update

Notify the user with relevant information

  • Check in/Check out times
  • Open/Close hours

Language

When creating a new message template, you must choose a language code. The language codes are described here.

A message template can be created in as many languages as desired. However, when translating the template into multiple languages, please be sure to use the exact same message template name.

Parameters

When we want to use variables collected from the users, we can use this placeholder to submit them in Templates.

Once it was approved, when sending the template, whatever you send it by chat section or by campaigns, we can add the variables to the template:

Parameters are available to add in the template's Header section, Body section and in the Buttons' Call-to-action section (only available for Website).

Please bear in mind the following limitations:

Limitations

Example

The Header field can only have 1 variable.

{{1}} from Landbot. ✅

{{1}} from Landbot. {{2}} ❌

It is not possible to send variables in the Footer

Alexander Gao from Customer success. ✅

{{1}} from {{2}}. ❌

For the Buttons Call-to-action, it is not possible to send variables in the phone number option.

Tha parameters can only be added to the Website Call-to-action.

The numbers have to be added in ascendent order, and starting from 1.

Hi {{1}}, I'm {{2}}. Welcome to {{3}}. How are you? Visit our website: {{4}}. ✅

Hi {{0}}, I'm {{1}}. Welcome to {{2}}. How are you? Visit our website: {{3}}. ❌

Hi {{1}}, I'm {{3}}. Welcome to {{4}}. How are you? Visit our website: {{5}}. ❌

It is possible to repeat the same variable in different sections of the template, as long as you follow the ascendent order in each section.

The header is optional.

The header can only be one of the following options: 

  • text (title)
  • image
  • document

a) Text (Title)

A text header has a limit of 60 characters, including parameters.

Ex:

Hello {{1}}, this is an update for your account. 

This header contains 44 characters not including parameters.

This means that both parameters combined can only be 16 characters long when sending this template.

If you try to add more characters, the message will fail.

Ex:

  • Hello Johnathan, this is an update on your account 8472693. ✅
  • Hello Johnathan Smith, this is an update on your account 0018472693. ❌

b) Image

It is possible to create a message template with an image header, you do not specify the actual image that will be used.

The image only needs to be specified when sending the template.

The image must have a size of less than 25MB.

c) Document

When creating a message template with a document in the header, you do not specify the actual document that will be used.

You only specify that a document will be used in the message template’s header.

The document only needs to be specified when sending the template.

The document must also have less than 25MB.

Body

The body is mandatory.

The body of a message template should only contain text, parameters, emojis, and formatting (bold, italic, strikethrough, and monospace).

There is no limit to the number of parameters allowed in the body but when sending the message template, the total number of characters can't exceed 1024.

If using parameters in the body, they may contain many characters as long as the total body length does not exceed the aforementioned 1024 characters.

The footer is optional.

When creating a message template, you may include a footer at the end of the message.

A footer may only contain text. No parameters, emojis, or formatting are allowed.

A footer has a limit of 60 characters.

Buttons

The Buttons are optional.

There are two different kinds of buttons that may be added to a message template:

  • call to action, or
  • quick reply.

If you wish to send a call to action, you may not send a quick reply in the same template and vice versa.

a) Call-to-action

  • A Call-to-action button can allow the customer to call a specific phone number or go to a specific URL.
  • If using a phone number call-to-action, the button text (max. 20 characters), and phone number are required fields for template creation.
  • If using a URL call to action, the button text (max. 20 characters) and URL are required fields for template creation.
    However, when using a URL, it is possible to add a parameter at the end to customize the URL. To add a parameter to the URL, simply add {{1}} to the end.
  • Once set, the call-to-actions can not be changed.
  • Additionally, a single message template can have a maximum of 1 phone and 1 URL call-to-action button each.

Here’s an example of each type:

URL - call-to-action:

URL - with parameter call to action:

Phone - call to action

  • Button text: Call for more info
  • Phone Number: +1 123-987-6543

b) Quick reply (buttons)

A quick reply button can allow the customer to easily respond to a message template with up to 3 predefined answers.

For quick reply buttons, all that is required is the button text (max. 20 characters).

This quick reply can then be used to trigger one or another flow in the bot.

Template's Approval Status

Once you have requested your template it will show up in the list along with its current status.

You'll only be able to contact users with the Templates that have already been Approved.

Adding a translation

The translation here means to add another template with the same name and under the same category.

Preview

From the preview section, you can check how the template will look before you send it

WhatsApp Template Message Tiers and Limits

Messaging limits determine how many unique users your business can send messages to on a daily basis.

This includes new conversations as well as existing conversations with users.

The messaging limit DOES NOT limit the number of messages your business can send, just the number of users you are trying to message.

It also DOES NOT apply to messages sent in response to a user-initiated message within a 24-hour period.

  • Tier 1: Allows your business to send messages to 1K unique customers in a rolling 24-hour period.
  • Tier 2: Allows your business to send messages to 10K unique customers in a rolling 24-hour period.
  • Tier 3: Allows your business to send messages to 100K unique customers in a rolling 24-hour period.
Note: A business starts in Tier 1 when it registers its phone number.

A business’s phone number will be upgraded to the next tier if:

  • Its quality rating is not low, and
  • The cumulative amount of users it sends notifications to adds up to twice its current messaging limit within a 7-day period.

Once the business reaches this threshold, it will be moved to the next tier.

The minimum amount of time that this upgrade can occur is after 48 hours, when the business is sending messages up to their current limit every day.

HSM Log

here you'll find all the information related to the HSM that you have:

You can filter by HSM:

You can filter by dates:

Also, you can export a CSV file with the HSM Log to your personal email:

Error Log

Here you will find all the error logs of your HSM with the date, error ID, User, User name, User phone and the Error message:

FAQ

After sending a message template, I received both a "failed" and a "delivered" notification. Does this mean the message failed to display?

Yes, when sending a message template, if it failed to display on the receiving end, you will receive a "failed" status callback with "structure unavailable" in the error object indicating that the message could not be displayed. Depending on the recipient, you may also receive a "delivered" status callback which simply indicates that the message was delivered to the recipient after which the recipient failed to display the message.

Do message templates support emojis?

Yes, message templates support all WhatsApp messaging characters and formatting including emojis, bolding, italics, etc. For emojis, you will need to use the emoji character (copy/paste) rather than its unicode equivalent.

Is there a limit to the number of parameters in a message template?

There is no limit to the number of parameters allowed in a message template.

Is media supported in message templates?

Using media in message templates is not currently supported, but is in development.

Is there a maximum number of message templates allowed per WhatsApp business account?

The maximum is 250 message templates per WhatsApp business account.

What are the reasons message templates might be rejected?

Reasons a message template might be rejected include:

  • Contains potentially abusive content such as abusive language or spam-like content
  • Does not match the select tag type
  • Formatted incorrectly
What should I know about creating a language pack translation?
The fallback language policy is deprecated beginning with v2.27.8 and the deterministic language policy is now the default policy.

If you create a translation in a new language you need to translate all the elements you use into that language. Otherwise, you might get "structure unavailable" errors since recipient's phone can't find an element it expects for the language it's in. These structure unavailable errors are seen when sending template messages using fallback policy.

If creating language translations is not an option for you at this moment, You can use deterministic policy to avoid these errors.

What's the cache time of a language pack?

It is currently 7 days. If a cache has not been updated for longer than 7 days, it will pull the latest language pack from the server regardless of whether the element already exists in the pack or not.

A link will only be rendered as clickable if the recipient has already saved your business number as contact or you have an Official Business Account.

Why is modifying or deleting message templates not supported?

The device will first load from cache, and if an element exists, it will unpack the message using that message template. So instead of modifying message templates, it's safest to simply add a new one with a different element name. That will guarantee that the language pack gets re-downloaded when it can't find that element. Storage costs of message templates are negligible so there's no absolute need to delete message templates.

See Sending Message Templates — Language for more information.

How did we do?

WhatsApp Campaigns 💌

Send Whatsapp Messages with Landbot API

Contact