Templates (HSM)

Archived on 31 August 2020

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 conversation via the WhatsApp channel.

In order to initiate a conversation as a business 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 from within your Clickatell portal as described below.

Other benefits of using templates include that 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 opted in and given your app permission to send them messages; all templates must be approved by WhatsApp before it can be sent to customers

Template types

Clickatell test templates

Clickatell provides a few test template messages for all approved and verified businesses to use. This also allows the business the ability to test and implement this functionality while the business-specific templates are being registered.

Business templates 

Once the business is verified by WhatsApp, you can proceed with the registration and approval of the template messages that your business requires. When registering a template message, you will have to provide the information as stipulated below under Applying for message templates.

Standard text templates

You can create rich text-based template messages to send to your customers. Formatting options like bold, italic, pre-formatted, or strike-through are supported.

Media templates

You can expand your standard text templates to also include media formats like image, document and video in the header of the message. This will allow you to send your customers rich notifications like a boarding card (PDF), movie ticket (QR code image), etc.

Re-engagement messages

Messages sent from business to consumer for the first time or more than 24 hours after the consumer last messaged the business are known as “re-engagement messages”. All such messages are required to be a template message. Regular text messages or media messages (i.e. any non-template messages) attempted in this a scenario will fail to be delivered to the consumer and an error will be returned by the Clickatell API. Businesses are urged to register a valid template message for this scenario or re-consider their engagement process with the consumer to ensure a good experience.

Applying for message templates

You can register new templates or review your existing approved templates from within the portal.

Navigate to WhatsApp → WhatsApp Templates from the left panel.

You will see two tabs:

My Test Templates: approved templates created by Clickatell that are added to your account by default – use them to get started quickly or when testing your API integration.

Business templates: view existing templates and create and submit new templates for approval

Note: This is only available once your WhatsApp Business profile has been approved and verified by WhatsApp. 

Click the ‘Apply for a message template’ button in the top right.

Complete the required details and click ‘Apply’. 

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

Once approved, you can send the message template using Clickatell’s One API to send a template to one or more customers. You cannot send template messages directly from the portal.

Using media in your templates

Step 1: Select media type

When creating the template, select ‘Media’ under ‘Template header’. Select the type of media you want to add to your template (image, video or document) and click ‘Apply’.

Step 2: Upload media
Once your template has been approved, you can 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.

Note: The uploading of the media file is required before you will be able to send the template. Although the template is not limited to a single media file, it is registered for a specific media type only.

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 your media file has been uploaded successfully, you can send your 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 referencing the media file (as returned in step 2).

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 should be all in lower case, with no spaces. You may use an underscore to indicate a space.
• 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}}
• Template Tag – 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 Examples

• Afrikaans
• English
• English (UK)
• English (US)
• Portugese (BR)
• Portugese (POR)
• Spanish (ARG)
• Spanish (SPA)
• Spanish (MEX)

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’.”