WhatsApp Template Messages (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 here. 

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. 

There are multiple pre-approved templates available to you from within the Clickatell Portal. These templates were provided by WhatsApp themselves and are non-editable. To create your own custom templates, you have to verify your business first. 

Also see:

• Adding WhatsApp template messages (HSMs)
• Best practices & example templates
• WhatsApp Business Policy

Applying for message templates

You can apply for message templates from within the Clickatell Portal. See here for steps and information.

Once approved, you can specify the template name and the relevant parameters in your API call when sending messages or transactional notifications to one or more customers using Clickatell’s One API (see below for more information).

You cannot send template messages directly from the portal.

Sending text templates

Step 1: Apply for media template in the Clickatell Portal

Refer to the Clickatell Portal User Guide.

• Select ‘None‘ or ‘Text‘ as header.
• Add variables (e.g., {{1}}, {{2}}) to your template where you want to insert parameters.
• Submit and wait for WhatsApp’s approval.

Step 2: Send template message via One API

Once approved, send the message template to end-users via our One API using the “Sends one or more messages” endpoint as described in the One API Reference document.

• As part of the One API call, you need to include the template name and parameters you want to insert in the message.
• For an example payload, select “WhatsApp: Text Template” from the drop-down:

Using media in your templates

Step 1: Apply for media template in the Clickatell Portal

Refer to the Clickatell Portal User Guide.

• Select ‘Media‘ as header.
• Select ‘Image‘, ‘Video‘ or ‘Document‘ as media type.
• Add variables (e.g., {{1}}, {{2}}) to your template where you want to insert parameters.
• Submit and wait for WhatsApp’s approval.

Step 2: Upload media via One API

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

Once your template has been approved, upload the media file that must form part of your template onto the Clickatell server by using the ‘Upload media file’ and ‘Get media file metadata’ as described in the One API Reference document.

• Although the template is not limited to a single media file, it is registered for a specific media type only.
• See here for supported content types and limitations.
• The successful upload of your media will return a fileID which is the unique reference to the media file you’ve uploaded. You’ll use this fileID in Step 3 below.

Step 3: Send message via One API

Once you have successfully uploaded your media file, you can send the message template to end-users via our One API using the “Sends one or more messages” endpoint as described in the One API Reference document.

• As part of the One API call, you need to include the template name and the fileID (as returned in Step 2), as well as any parameters you want to insert in the message.
• For an example payload, select “WhatsApp: Media Template” from the drop-down:

Note: if you are using Media header in combination with interactive buttons, simply select the correct option from the drop-down for an example payload for the combination.

Using interactive buttons in your templates

Step 1: Apply for template containing interactive buttons in the Clickatell Portal

Refer to the Clickatell Portal User Guide.

• Select ‘None‘, ‘Text‘ or ‘Media‘ as header.
• Add variables (e.g., {{1}}, {{2}}) to your template where you want to insert parameters.
• Select one of the following types of buttons:
  • Call to action button
    • Visit website (static/dynamic URL)
    • Call phone number
  • Quick reply button
• Submit and wait for WhatsApp’s approval.

Step 2:

Once approved, send the message template to end-users via our One API using the “Sends one or more messages” endpoint as described in the One API Reference document.

• As part of the One API call, you need to include the template name and parameters you want to insert in the message.
• For an example payload, select the relevant option from the drop-down (e.g., “WhatsApp: Interactive Text Template with Dynamic URL“) from the drop-down: