Templates (HSM)

What is a WhatsApp template message (HSM)?

A template message (also known as a Highly Structured Message or HSM) is a special message type that must be used for any business-initiated or re-engagement conversations via the WhatsApp channel.

As a business, in order to initiate a conversation with an end-user for the first time or after a period of 24 hours since the last interaction, you have to make use of a pre-approved template. You can create and submit such templates for approval by WhatsApp from within your Clickatell portal as described below. 

Templates also include the following benefits: 

• Businesses can register content for their most commonly used messages and simply send the relevant variable parameters instead of recreating the entire message during the API call each time it is used.
• For the consumers who receive a notification message from your verified business for the first time and do not have the business saved as a contact in their phone book, the WhatsApp application will recognize the registered template and display the message without any warnings. This will reduce the likelihood of your messages being marked as spam by the consumer.

Note: Templates can only be sent to users who have given your app permission to send them messages. Read more about the Opt-In rules in the WhatsApp Business Policy. 

Template types

1. Clickatell test templates

Clickatell provides a few test templates for all approved and verified businesses to use. This enables the business to test this functionality while awaiting approval for their WhatsApp Business account. 

The Test Templates are found in the Clickatell portal by navigating to My Workspace → WhatsApp and is only visible if there are no approved WhatsApp accounts yet.

Note: Test templates are only available on your account for 90 days, or for up to 3 days after your own WhatsApp Business account has been approved and activated. 

2. Business templates 

Once your WhatsApp business account has been verified by WhatsApp, you can register the specific template messages your business requires. 

Standard text templates

Create rich text-based template messages to send to your customers. Formatting options like bold, italic, pre-formatted, and strike-through are supported.

Media templates

Expand your standard text templates to include media formats like image, document and video in the header of the message. This allows you to send your customers rich notifications like a boarding card (PDF) or movie ticket (QR code image).

For supported content types, see here.

Interactive templates

Standard text and media templates can be further enhanced to include predefined buttons for interactive engagement with your customers. Two types of buttons are offered:

• Call to action: allows your customers to call a phone number or visit a website 
• Quick reply: allows your customer to return a simple text message

3. Re-engagement messages

Messages sent from a business to a consumer for the first time or more than 24 hours after the consumer last messaged the business, are known as “re-engagement messages” and must be in the form of a template message. Any non-template messages attempted in this scenario will not be delivered to the end-user and an error will be returned by the Clickatell API. 

Applying for message templates

Once you have an approved, active WhatsApp Business account, you can register new templates from within the portal by navigating to My Workspace → WhatsApp. 

Click ‘+ Add Template’. 

Complete the required details and click ‘Submit’. 

The template will appear in your table of message templates with the status ‘Pending’. Once your template is approved by WhatsApp and ready for use, the status will change to ‘Active’.

Once approved, you can specify the template ID and the relevant parameters in your API call when sending messages or transactional notifications to one or more customers using Clickatell’s One API. You cannot send template messages directly from the portal.

Using media in your templates

Step 1: Select media type

When creating a new template, select the ‘Media’ radio button under ‘Header’ and select the type of media you want to add to your template. Enter the rest of the required information and click ‘Submit’.

Step 2: Upload media

Once your template has been approved, upload the media file that needs to form part of your template onto the Clickatell server by using the endpoints as described in the ‘Media Upload’ and ‘Get Uploaded Media Metadata’ sections of the One API Reference docs. Although the template is not limited to a single media file, it is registered for a specific media type only.

Note: The uploading of the media file is required before you will be able to send the template. 

The successful upload of your media will return a fileID which is the unique reference to the media file you’ve uploaded.

Step 3: Send message via One API

Once you have successfully uploaded your media file, you can send the message template via One API by using the endpoint as described in the One API Reference docs. As part of the One API call, you need to include the template name and the fileID as returned in Step 2.

Using interactive buttons in your templates

When creating a new template, you can choose between two types of interactive buttons to include in your template. Only one type of button can be included per template.

1. Call to action button

Allows your customer to call a phone number or visit a website.

• You can add a maximum of two buttons per template 
• A template can only contain one phone number and one website button
• Button text can be a maximum of 20 characters long

From the drop-down select the type of action button you want to add and specify the text that should appear on the button.

“Visit Website” action:

• The website URL is expected in the format of “http(s)://www.google.com”  
• URL can be up to 2000 characters long
• When clicking this button, the user is directed to the specified website on their device
   
   

“Call Phone Number” action:

2. Quick reply button

• Add a maximum of three buttons per template 
• Button text can be a maximum of 20 characters long
• The text on every button used in a template must be unique
• When clicking this button, the user sends the response to the business as part of the conversation

Best practices

When creating a new message template, a business must follow the below best practices:

• Template name – A unique name to identify the template use case for the business. It must be in lower case, with no spaces. You may use an underscore to indicate a space.
• Template category – Type of information contained in the template (e.g. account update, issue resolution, auto reply). Select the value from a predefined set of categories during registration.
• Template parameters – A template message must contain at least one parameter, and all message formatting options (e.g. bold, italics) applies. Parameters cannot have new line/tab characters or more than four consecutive spaces. All parameters will be defined within curly open/close braces and listed in chronological order starting at {{1}} (use the ‘+Variable’ button as a shortcut to easily add these) 

Template Examples

• Bengali
• English
• English (UK)
• English (US)
• French
• German
• Gujarati
• Hindi
• Indonesian
• Kannada
• Marathi
• Portugese (BR)
• Portugese (POR)
• Punjabi
• Spanish
• Spanish (ARG)
• Spanish (MEX)
• Spanish (Traditional)
• Tamil
• Telugu

Rejection reasons

If your template(s) are rejected, it may be because of one of the following reasons:

• Template(s) may be considered to be promotional
  • Advertising, marketing or promotional messages offering coupon codes and/or free gifts and upselling are not permitted in templates
    • E.g. “Here is your boarding pass, with seat assignment and gate information. If you would like to save 10% on your in-flight dinner, order your meal through our app.”
  • Cold call messages
    • E.g. “Is now a good time to talk?”, “Thank you for your interest, can we speak now?”, “I tried contacting you but you weren’t available. When are you free?”
  • Sending a survey or poll to collect data
    • E.g. “Hi, we’re interested in knowing how you feel about certain food groups. Do you mind participating in a survey?”
  • Inclusion of certain words or phrases that make the message template promotional (even though the content of your template may be acceptable)
    • Tip: Think about how your template sounds when you read it aloud.
• Template(s) has floating parameters
  • I.e. just parameters and no text 
    • E.g. “Hello {{1}}”, “{{1}} – {{2}}”
  • It is important to surround the parameters with contextual text so it’s clear what will be inserted for the parameters.
• Template(s) contain incorrect formatting
  • E.g. templates containing spelling mistakes
• Template(s) contain potentially abusive or threatening content
  • E.g. templates that threaten customers with a legal course of action or that threaten to add customers to a WhatsApp group with their friends and family to shame them if they don’t pay back their loans 

Additional guidelines to help accelerate the Message Template approval process

• Make your message template name clear, e.g. instead of using a name like “template_014” rather use “order_update”.
• Remember that someone outside of your business will be reviewing your templates. Providing more clarity gives reviewers context around how the template will be used.
• If you need to write a message template to re-open the 24-hour window, we would suggest starting with some mention of the previous conversation thread, e.g. “I’m sorry that I wasn’t able to respond to your concerns yesterday but I’m happy to assist you now. If you’d like to continue this discussion, please reply with ‘yes’.” or “I was able to do some follow-up based on our previous conversation, and I’ve found the answer to your question about our refund policy. If you’d like to continue our conversation, please say ‘yes’.”