Skip to content

Support for More Than 3 Quick Reply Buttons in HSM Templates #526

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Fawas003 merged 9 commits into from
Dec 10, 2025
Merged

Support for More Than 3 Quick Reply Buttons in HSM Templates #526

Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
68f7fe2
refactor: hsm doc
priyanshu6238 Dec 8, 2025
a8c4cef
fix: correct button limit in HSM template instructions
priyanshu6238 Dec 8, 2025
63efb74
fix: date
priyanshu6238 Dec 9, 2025
f511f83
add: image
priyanshu6238 Dec 9, 2025
119342e
Add: header
priyanshu6238 Dec 9, 2025
c4c66b2
Fix: typo in Quick Reply button description
priyanshu6238 Dec 9, 2025
3f5f23b
fix: screenshot
priyanshu6238 Dec 9, 2025
ce0e674
fix: alignment
priyanshu6238 Dec 10, 2025
0e24b00
fix: image
priyanshu6238 Dec 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
127 changes: 66 additions & 61 deletions docs/4. Product Features/06. HSM Templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,15 @@

# HSM Templates
<h3>
<table>
<tr>
<td><b>10 minutes read</b></td>
<td style={{ paddingLeft: '40px' }}><b>Level: Beginner</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: October 2025</b></td>
<td style={{ paddingLeft: '40px' }}><b>Last Updated: December 2025</b></td>
</tr>
</table>
</h3>


**HSM (Highly Structured Message) templates are pre-approved message formats required for sending outbound messages to contacts outside the 24-hour WhatsApp session window.
**HSM (Highly Structured Message) templates are pre-approved message formats required for sending outbound messages to contacts outside the 24-hour WhatsApp session window.
These templates help ensure compliance with WhatsApp’s policies and are commonly used to send notifications, alerts, or support messages.
Templates can include placeholders for personalized content and are essential for initiating conversations once the 24- hour session window has expired.**

Expand All @@ -24,7 +23,6 @@ Session Window - A session window refers to the 24-hour period following a user'

- For initiating conversation with the contacts after the 24-hour session window is closed, such as sending reminders or important follow-ups.


- For broadcasting standardized updates, like activity schedules, weather alerts, crop advisories, appointment confirmations, service announcements,programs and events

---
Expand All @@ -49,65 +47,69 @@ Session Window - A session window refers to the 24-hour period following a user'
<br />
<br />

4. Fill in the following details in the form.
4. Fill in the following details in the form.

a.`Is Active`- the check box is by default checked. Keep it checked.

b. `Language` - Select the preferred language from the dropdown to ensure the template gets approved in that specific language.
a.`Is Active`- the check box is by default checked. Keep it checked.

<img width="517" height="216" alt="image" src="https://github.com/user-attachments/assets/fc0e56bd-a743-4b04-91e4-378e351fb2b9" />
b. `Language` - Select the preferred language from the dropdown to ensure the template gets approved in that specific language.

c. `Translate existing HSM` - Select this if the HSM template you are trying to apply has a language variant of an existing HSM template in a different language. If not then no need to enable it.

d. `Element Name` - Provide a title for WABA namespace for the HSM template. Incase the translate existing HSM is selected, this field becomes a drop down. From the list select the element name of the HSM template for which the language variant is being applied.

e. `Title` - Enter the name you want for your HSM Template as it would appear in Glific (It should be what use case does this template serves eg. OTP, Optin,
Activity Preference).

<img width="410" height="337" alt="image" src="https://github.com/user-attachments/assets/9e45eae4-6a92-4058-8083-9963e380afe9" />
_(Ensure Title and Template Name are not identical to avoid mapping issues.)_
<img width="517" height="216" alt="image" src="https://github.com/user-attachments/assets/fc0e56bd-a743-4b04-91e4-378e351fb2b9" />

c. `Translate existing HSM` - Select this if the HSM template you are trying to apply has a language variant of an existing HSM template in a different language. If not then no need to enable it.

f. `Message` - Type the message you want to send to users in this HSM template.
d. `Element Name` - Provide a title for WABA namespace for the HSM template. Incase the translate existing HSM is selected, this field becomes a drop down. From the list select the element name of the HSM template for which the language variant is being applied.

g. `Add Variable` - Click on add variable if you'd like to insert a variable values (ex- preferred names, locations, any other value being captured in flow or contact variables). This provides further fields below to enter a sample value for the variables.
e. `Title` - Enter the name you want for your HSM Template as it would appear in Glific (It should be what use case does this template serves eg. OTP, Optin,
Activity Preference).

<img width="401" height="360" alt="image" src="https://github.com/user-attachments/assets/aa9960c3-1d6c-4e75-9c60-71598eccf293" />
<img width="410" height="337" alt="image" src="https://github.com/user-attachments/assets/9e45eae4-6a92-4058-8083-9963e380afe9" />

_(Ensure Title and Template Name are not identical to avoid mapping issues.)_


h. `Footer` - Add the message which you want to act like a subtext.
f. `Message` - Type the message you want to send to users in this HSM template.

i. `Add Buttons` - You can use `Add Buttons` checkbox to use buttons in HSM templates.

- Quick Replies is selected by default which allows to add 3 buttons to the message
g. `Add Variable` - Click on add variable if you'd like to insert a variable values (ex- preferred names, locations, any other value being captured in flow or contact variables). This provides further fields below to enter a sample value for the variables.

<img width="511" height="375" alt="image" src="https://github.com/user-attachments/assets/37d8050b-2a3d-420c-8c90-f9910eca6994" />
<img width="401" height="360" alt="image" src="https://github.com/user-attachments/assets/aa9960c3-1d6c-4e75-9c60-71598eccf293" />

- Call to action buttons: Add a Call to Action (CTA) button in an HSM (template) message when the recipient is expected to take a specific action directly from the message.
h. `Footer` - Add the message which you want to act like a subtext.

<img width="506" height="387" alt="image" src="https://github.com/user-attachments/assets/460cf615-e772-41ce-a837-babddce2e5e7" />
i. `Add Buttons` - You can use `Add Buttons` checkbox to use buttons in HSM templates.

- Call to Action is selected by default. Click the dropdown and select the Quick Replies option.

<img width="389" height="212" alt="Screenshot 2025-12-09 at 1 40 59 PM" src="https://github.com/user-attachments/assets/ba9a52ae-b85a-4aa9-bbf5-de326270766d" />

- You can add up to 10 buttons in the Quick Reply option.
<img width="398" height="746" alt="Screenshot 2025-12-09 at 1 43 19 PM" src="https://github.com/user-attachments/assets/8a60319d-1d42-46df-94e0-46b13c3773e4" />

- There are two main options:

- **Phone number** and **URL**.

- **Note:-** Phone numbers without country code (for example Exotel numbers) will be added in HSM as an `Call to actions` option. As a workaround, you can add these numbers in the body of the message.

- If selected **URL**, must choose between **Static** and **Dynamic** links.
- Call to action buttons: Add a Call to Action (CTA) button in an HSM (template) message when the recipient is expected to take a specific action directly from the message.

<img width="366" height="326" alt="Screenshot 2025-12-09 at 1 52 47 PM" src="https://github.com/user-attachments/assets/bdc55bb6-64f6-4d04-9430-3d19ee4acce5" />

Here's a simple explanation with examples:

- There are two main options:

Comment on lines +88 to +94
Copy link
Contributor

@coderabbitai coderabbitai bot Dec 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Correct unordered list indentation.

The nested list items under section "i" use inconsistent indentation that violates markdown standards (MD007). The dashes at lines 88, 93, etc. should align without the 3-space offset, or use a consistent indentation pattern throughout.

     i. `Add Buttons` - You can use `Add Buttons` checkbox to use buttons in HSM templates.
 
-    - Call to Action is selected by default. Click the dropdown and select the Quick Replies option.
+    - Call to Action is selected by default. Click the dropdown and select the Quick Replies option.

Ensure all nested bullet points (lines 88, 93, and others in this block) follow consistent indentation: either left-aligned or properly nested with 2-space indentation.

Committable suggestion skipped: line range outside the PR's diff.

🧰 Tools
🪛 markdownlint-cli2 (0.18.1)

88-88: Unordered list indentation
Expected: 0; Actual: 3

(MD007, ul-indent)

🤖 Prompt for AI Agents 
In docs/4. Product Features/06.  HSM Templates.md around lines 88 to 94, the
nested unordered list indentation is inconsistent (MD007); fix by aligning the
top-level dashes at the same column and normalizing nested bullets to a
consistent 2-space indentation level (or left-align all bullets) throughout this
block so each nested item is indented exactly two spaces from its parent and all
list markers line up uniformly.

- **Phone number** and **URL**.

- **Note:-** Phone numbers without country code (for example Exotel numbers) will be added in HSM as an `Call to actions` option. As a workaround, you can add these numbers in the body of the message.

- If selected **URL**, must choose between **Static** and **Dynamic** links.

Here's a simple explanation with examples:

**Static URL**

- A Static URL is a fixed link. It will be the same for everyone who receives the message.

- Use it when the link doesn't change.


**Example:**

- Sending a message about online training. The requirement is that all users visit the same registration page.
Button Title: Register Now
Button Title: Register Now

- Button Value: `https://xyz.org/register`

Expand All @@ -119,7 +121,6 @@ Button Title: Register Now

- Use it when the link includes unique details per user.


**Example:**

- Send a personalized health report to each user.
Expand All @@ -130,35 +131,33 @@ Button Title: Register Now

- When sent, `{{1}}` will be replaced by the user's specific ID, like 12345 or abc678.


<img width="503" alt="Screenshot 2024-07-01 at 5 13 14 PM" src="https://github.com/glific/docs/assets/141305477/09ec727f-46bf-4242-a95a-caebb6763491"/>


j. `Category` - Select the most relevant category from the dropdown. Ex. Utility or Marketing.
j. `Category` - Select the most relevant category from the dropdown. Ex. Utility or Marketing.

- Utility: Used for transactional messages to keep your customers in the loop with essential order updates, shipping status, about their accounts, orders, appointment reminders, and important alerts.

- Marketing: Elevate your brand by sending promotional content, announcing new products, and offering special deals to captivate your audience. For instance, promotional messages, including special offers, product launches, and loyalty programs
- Utility: Used for transactional messages to keep your customers in the loop with essential order updates, shipping status, about their accounts, orders, appointment reminders, and important alerts.


k. `Attachment type` - Select the attachment type to send an attachment in your HSM template message Ex. Image, Audio, Video, etc.

l. `Attachment URL` - Paste the attachment URL ( public URL) from the GCS bucket. Refer [Upload files on GCS](https://glific.github.io/docs/docs/Pre%20Onboarding/GCS%20Setup/Upload%20files%20on%20GCS/#upload-media-files-in-the-gcs-bucket)
Note - Attachment Type & URL are optional. It needs to be filled only if an attachment is required to be sent in the HSM template to the beneficiary.For more info please check [this]( https://developers.facebook.com/docs/whatsapp/updates-to-pricing/new-template-guidelines)
- Marketing: Elevate your brand by sending promotional content, announcing new products, and offering special deals to captivate your audience. For instance, promotional messages, including special offers, product launches, and loyalty programs

Notice a simulator available in the form, as you will fill in the details of the HSM template, it will start previewing the message.
k. `Attachment type` - Select the attachment type to send an attachment in your HSM template message Ex. Image, Audio, Video, etc.

l. `Attachment URL` - Paste the attachment URL ( public URL) from the GCS bucket. Refer [Upload files on GCS](https://glific.github.io/docs/docs/Pre%20Onboarding/GCS%20Setup/Upload%20files%20on%20GCS/#upload-media-files-in-the-gcs-bucket)
Note - Attachment Type & URL are optional. It needs to be filled only if an attachment is required to be sent in the HSM template to the beneficiary.For more info please check [this](https://developers.facebook.com/docs/whatsapp/updates-to-pricing/new-template-guidelines)

Notice a simulator available in the form, as you will fill in the details of the HSM template, it will start previewing the message.
Simulator helps you to get an idea about how the message will look like when the contact receives it.

<img width="365" alt="image" src="https://github.com/glific/docs/assets/122982753/b9aee8df-29bd-41cf-bdcb-1742ffabd6c7"/>
<br />

m. `Tag`s - Add tags if required, not a mandatory step.
m. `Tag`s - Add tags if required, not a mandatory step.

n. Click on `Submit for Approval`,

- Click on the Sync button on the HSM list page, after a couple of minutes to see the change in status of HSM from Pending to either `Approved` or `Rejected`

n. Click on `Submit for Approval`,
- Click on the Sync button on the HSM list page, after a couple of minutes to see the change in status of HSM from Pending to either `Approved` or `Rejected`

<img width="507" height="121" alt="image" src="https://github.com/user-attachments/assets/3430e9d6-b348-49be-abdf-816997754279" />

Generally it takes a maximum of `2 mins to 48 hours` to get approval from WhatsApp.
Once you get your message approved, you can start sending it to your contacts. Verify that the `Status` of your message has turned **Approved** from the `Templates` page

Expand All @@ -171,7 +170,6 @@ Once you get your message approved, you can start sending it to your contacts. V

- A new template must be created to replace the rejected one.


## Can I Edit a Template After Approval?

- No, WhatsApp approval is immutable.
Expand All @@ -196,15 +194,16 @@ You can use approved HSM templates in your flow, to send to multiple users autom

2 . Click on `HSM Template` tab

![image](https://user-images.githubusercontent.com/32592458/218255870-dea659b0-421f-4383-a65f-9dbdd500eb00.png)
<img width="613" height="463" alt="Screenshot 2025-12-10 at 7 07 20 PM" src="https://github.com/user-attachments/assets/252d355c-a3b4-4b54-bf23-c7b60fd63eb6" />

3 . Select the HSM template you want to send from the dropdown list. Refer [HSM Templates](https://glific.github.io/docs/docs/Product%20Features/HSM%20Templates/) to know more about how to create HSM templates.

![image](https://user-images.githubusercontent.com/32592458/218255877-26f48828-88d1-497c-96c3-f4f339d5a529.png)
<img width="620" height="400" alt="Screenshot 2025-12-10 at 7 07 55 PM" src="https://github.com/user-attachments/assets/d67baf37-fe70-4a7b-9d8e-880a17a00d7d" />


4 . Select the `variable` names to replace in the HSM template.

![image](https://user-images.githubusercontent.com/32592458/218255890-c2071b37-0312-457c-ae32-297d88a2a18e.png)
<img width="604" height="465" alt="Screenshot 2025-12-10 at 7 08 27 PM" src="https://github.com/user-attachments/assets/2c611989-9d82-4c7f-af8d-f7420468a2f5" />

5 . Click on `Ok` button.

Expand Down Expand Up @@ -315,6 +314,13 @@ Multiple templates can also be applied by using Bulk Apply HSM templates using G
1. `Quick Reply 1 Title:` Add Text that would appear on first button when button type is `QUICK_REPLY`
1. `Quick Reply 2 Title:` Add Text that would appear on second button when button type is `QUICK_REPLY`
1. `Quick Reply 3 Title:` Add Text that would appear on third button when button type is `QUICK_REPLY`
1. `Quick Reply 4 Title:` Add Text that would appear on fourth button when button type is `QUICK_REPLY`
1. `Quick Reply 5 Title:` Add Text that would appear on fifth button when button type is `QUICK_REPLY`
1. `Quick Reply 6 Title:` Add Text that would appear on sixth button when button type is `QUICK_REPLY`
1. `Quick Reply 7 Title:` Add Text that would appear on seventh button when button type is `QUICK_REPLY`
1. `Quick Reply 8 Title:` Add Text that would appear on eight button when button type is `QUICK_REPLY`
1. `Quick Reply 9 Title:` Add Text that would appear on ninth button when button type is `QUICK_REPLY`
1. `Quick Reply 10 Title:` Add Text that would appear on tenth button when button type is `QUICK_REPLY`

4. Click on `File` -> `Download` -> `Comma Separated Values(.csv)` to download sheet in csv format

Expand Down Expand Up @@ -353,4 +359,3 @@ By default, there is a **limit of 250 HSM templates per phone number**. If incas
**Note** - The HSM templates need to be in one language. Do not mix the languages in one template (Ex. words of both English and Hindi language should not be in one HSM template).

---