WhatsApp HSM templates
Contents
General info about HSM templates
What is an HSM template?
An HSM template (Highly Structured Message) is a pre-defined standard message for sending to customers via WhatsApp. A template can consist of text, media files, buttons, and variables. WhatsApp templates have strictly limited categories and require WhatsApp approval.
HSM template advantages:
- Safe bulk and individual outbound messages: you can be confident that your WhatsApp number will not be blocked for suspicious activity.
- Speed. High speed of HSM templates delivery.
- Personalization. Templates can contain variables that you specify individually for each customer.
- Buttons, images, videos, and files in a template.
- Ease of use: there is no need to write a message from scratch every time; agents can easily select the required template in their Workspace.
24-hour time window
WhatsApp restricts the ability to initiate contact with customers. You can only write to a customer first using an HSM template. Template-based messages can be sent both individually and in bulk to a list of phone numbers.
The initial template message to a customer is charged according to company rates. Its cost depends on the category of the template and the country of the recipient. Subsequent messages to a customer of the same category will be free within 24 hours after the customer's last response. Each customer response extends the window by another 24 hours. Once more than 24 hours have passed since the customer's last response, only paid templates can be sent, free-form messaging is blocked.
Creating an HSM template
Creating and managing HSM templates is available to users with the Owner and Administrator roles.
You must have at least 1 WhatsApp channel to create an HSM template. Note that the feature is not available for WhatsApp Cloud API channels.
- In the Template collections section, select the collection to create an HSM template.
- Click the Create button and select Create WhatsApp HSM template.
- Enter the Template name. The template name should reflect its meaning and be understandable to the moderator. This will allow the template to successfully obtain the approval. The field is required.
A template name can include only Latin letters, numbers, and underscores (_). Uppercase letters, spaces, and Cyrillic characters are not allowed. The maximum number of characters is 60.
Correct name example: laundry_detergent.
Incorrect name examples: Sales 20, 20% discount, 84 746 466, Template № 4.
- From the drop-down list, select the collection (only one) in which you want to create a template. The current collection is selected by default.
You can add up to 1000 templates to a collection.
- Select the WhatsApp channel to use the template. If only one WhatsApp channel is created in your account, its name will be automatically filled in the field. You cannot add an HSM template without at least one WhatsApp channel created.
- Select the channel category. The options are: Marketing and Utility. The cost of sending a message depends on the template category.
Utility — notifications about bank transactions, information about account changes, order status, or loyalty program.
Sample template text: Attention! The transfer of {{variable1}} from the account {{variable2}} has been completed.
Marketing — company news, offers with promotions and discounts, information about events and webinars.
Sample template text: Attention! Prices for all products in the {{variable1}} category have been reduced by {{variable2}}. Come shopping!
- To move from general settings to template content settings, click Next.
- Select the language in which you want to write the template text from the drop-down list. The field is required.
- Add a Header for the template. It can contain important information for the customer — they will notice it first.
3 types of headers are available:
Text. Text header has bold font; there is increased spacing between the header and body text. The maximum length is 60 characters. You can add 1 variable to the header text to personalize it for each customer.
Enter a variable in the {{name}} format. The variable name must be unique and contain only English letters and numbers. The variable name must not exceed 25 characters and must not contain spaces, special characters, or line breaks. The number of characters in the variable is included in the total character count of the message text.
Media file. Video (.mp4, .3gpp.), image ( .jpeg, .jpg, .png), or document (.pdf). The maximum file size is 5 MB.
No header.
If you select a header with an attachment, a sample file is required for template approval. You cannot change the selected header type after your template is approved.
In the preview window on the right, check how the entered text will approximately display to a customer.
- In the Message body field, enter the template text the recipient will see. The field is required. The maximum number of characters is 1024, including emojis and variable characters. The text must not contain four or more consecutive spaces and cannot consist solely of variables. The text can contain line breaks.
If required, add variables to make your message individual for each customer.
The maximum number of variables in a template is 10. Enter variables in the {{text}} format. The variable name must be unique and contain only English letters and numbers. The variable name must not exceed 25 characters and must not contain spaces, special characters, or line breaks. The number of characters in the variable is included in the total character count of the message text. One template cannot contain two variables with the same name.
The template text displays in the preview window on the right. It is recommended to compose the text in such a way that the message topic is clear to the moderator. This will help the template successfully obtain the approval.
- If necessary, add a footer to the template, for example your company slogan. The maximum number of characters is 60.
- Add buttons to make your message interactive.
You can add the following types of buttons to the template text:
Quick reply
Call
URL
One message can contain either reply buttons (up to 3 buttons in one template) or call-to-action buttons (1 URL button and 1 call button). You cannot change the button name once you submit the template for approval.
QUICK REPLY button
Use this option to add buttons with any values. These buttons will display in the message sent based on the template.
Once a customer selects one of the buttons, you receive an inbound message from them with the text. This message will be available in the message report as an inbound message.
You can add a maximum of three quick reply buttons. Once the customer presses one of the buttons, other buttons become disabled. You can create buttons that say Yes or No, contain different quality survey options (for example, Great, Good, Bad), offer the customer to select one of the available options to buy (for example, S, M, L), etc. You cannot change the number of buttons and button names after the template is approved.
In the Button text field, enter the button name (as it will appear to customers). The maximum number of characters in the button text is 25.
In the Payload field, enter the button value, which will display in the message report as an inbound message from the customer. The maximum number of characters is 250.
CALL button
Use this option to add a button that will use standard software for calls on a customer’s device to call the number you specify. The customer can use this button multiple times. The call button can be added simultaneously with a URL button, but not with quick reply buttons.
In the Button text field, enter the text to display. The maximum number of characters in the button text is 25.
Enter the phone number to which calls will be made. The phone number should start with + and include the country code.
URL button
Use this option to add a clickable link to your template. You can add a URL button together with a Call button, but not with quick reply buttons.
The URL can be both static and dynamic.
A static URL is the same in every message based on this template.
A dynamic URL must have two parts. The first one is a fixed (invariable) part (for example, a website https://example.com/marketing/); you must enter it in this step. The second, final part of the URL can change for each broadcast created based on the current template (for example, https://example.com/marketing/action234 или https://example.com/marketing/gift-1000).
Enter the button text. The maximum number of characters is 25.
Enter the static and, if selected, dynamic (variable) link values.
A template can only contain one URL button.
Submitting the template for approval
- After filling in all the mandatory fields, click the Create button and select Create and send for review. At this stage, you can also save a template as a draft to submit it for review later.
- If your template contains variables, the Enter variable text samples window opens, where you should add variable examples according to WhatsApp rules. For example, if the template announces the release of a new product version, the variable values should be contextually appropriate. If there are no variables, this additional step is not required.
You can change variable values after successful template verification.
- Add the required examples and make sure the final message looks correctly in the preview window on the right.
- Click Send.
Once submitted for review, the template will change the status to In review. Template review can take from a few minutes to 1-2 days. After moderation, the template status changes to Approved or Rejected. Approved templates are available for agents in their Workspace.
Template rejection reasons
A template is highly likely to be rejected by the moderator if:
the template text is abusive or threatening;
the template text contains spelling or grammatical errors;
the template text contains shortened links;
the selected template language does not match the language of the template text;
the selected category does not correspond to the title and content of the template text.
the template contains no content;
the template message is too promotional (the template is too salesy and violates the Trade Policy or WhatsApp Business Policy);
the message may mislead the recipient (the moderator suspended scam or fraud).
Your HSM templates
- To view the list of HSM templates, go to the WhatsApp HSM tab in the required collection.
- In the template list, review key information about each record: template name, its status, and creation date/time. Use filters to display templates in the statuses you need.
Possible statuses:
Draft. The template is edited in your personal Voximplant Kit account; not submitted for review.
In review. The template is at the registration stage on the provider or operator side.
Approved. The template has been successfully registered with the provider or operator.
Rejected. The template has been rejected by the provider or operator at the registration stage. Send a request to technical support.
Paused. The use of the template has been suspended on the WhatsApp side due to negative customer feedback. The template will be temporarily unavailable for sending broadcasts within 3-6 hours from the time of suspension. Once suspended, the template may switch to the Approved or Disabled status.
Disabled. The template has been disabled by the provider or operator due to negative customer feedback. Send a request to technical support.
- Click the template name – an information window will open in the upper right corner of the screen. There, you can also see how approximately the template will appear to customers.
Actions with templates
In the HSM template list, there is an Actions menu next to each name, which allows you to manage your templates.
Available actions:
Edit. Allows you to edit the template. This action is only available for templates in the Draft status.
Duplicate and edit. Creates an editable copy of the template. Available only for templates in the Draft status.
Delete. Deletes the template. This action is only available for templates in the Draft status. If the template is in use or has been submitted for registration, you cannot delete it.
Move. Moves the template to another collection. A template can only be moved to one collection at a time. Available for all templates. If there are no other collections, you can create a new collection and move the template into it.
Using HSM templates in the Workspace
Once you have successfully registered your HSM template, you can send it to a customer.
- Go to your Workspace and click the Create chat icon. The action is also available while processing a call.
To create a WhatsApp chat, you must have at least one WhatsApp channel and one registered HSM template. The template must be inside a collection assigned to your group.
- Click Create WhatsApp chat.
The Send WhatsApp template window opens.
- Enter the phone number of the customer you want to start a conversation with. If you send a template message during a call, the phone number may be entered into the field automatically based on the customer card information, but you can edit it.
- Select the WhatsApp channel from the dropdown list. The list only includes channels with registered templates.
WhatsApp Cloud API channels are not available for selection.
- Choose a template to send to the customer. The list only shows templates created in the channel you selected above.
In one message, you can only send one template.
After selecting a template, you can preview and partially edit it (variables, attachments, links).
- If you use variables in the header or message body, enter values for each of them.
The maximum number of characters in a variable is 512, and the minimum is 1. Variable text must not contain 4 or more consecutive spaces and line breaks. If the number of characters in the message text (including variables and emojis) exceeds the limit, the message will not be sent.
If a Media header is used in the template, the system automatically attaches the file, image, or video added during template registration. If necessary, change the attachment by selecting one of the options: Upload from PC or Paste URL.
A new file must be of the same type as the one added at template registration.
- If you use a link button in the template, specify its dynamic part, if applicable.
- Click Send.
A new chat with the sent template is created on the My tasks tab. Sending free-form messages is blocked until you receive a first response from the customer.
If for any reason your template message was not sent to the customer, an error with the reason displays. Possible errors:
The recipient is not registered on WhatsApp.
The message content does not match the template.
The message is not sent within the 24-hour conversation.
The daily message limit for the channel has been exceeded.
The message length exceeds the allowed limit.
Incorrect subscriber phone number format.
If more than 24 hours have passed since the last response from the customer, you can send another HSM template in the open chat.
If you have mistakenly sent a template and need to send another one in an open chat within the 24-hour window, click the Use template icon and select an HSM template from the dropdown list. Only templates from the channel you used to send the first template message are available for selection.
Within 24 hours, you can send a maximum of two marketing template messages to one recipient if they have not responded yet.
After selecting a template, a window similar to the one you filled out when sending the first template message opens. You cannot edit the phone number and WhatsApp channel.
- After filling out all the necessary fields, click the Send button.
As soon as the customer responds to the template message, you will be able to send free-form messages for 24 hours. Each new response from the customer extends the 24-hour window by another 24 hours. When more than 24 hours have passed since the last response from the customer, your ability to send messages is blocked. To unlock it, you must send a template again.
If the customer resumes the conversation after 24 hours, you can continue free-form communication regardless of whether a repeated template message was sent.
Displaying templates in the conversation history
The sent template message, customer response, and all the communication within one conversation display in the Message history.