Skip to content
Merged
Changes from 1 commit
Commits
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
153 changes: 93 additions & 60 deletions docs/4. Product Features/WhatsApp Forms.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<tr>
<td><b>3 minute read</b></td>
<td style={{ paddingLeft: 40 }}><b>Level: Intermediate</b></td>
<td style={{ paddingLeft: 40 }}><b>Last updated: December 2025</b></td>
<td style={{ paddingLeft: 40 }}><b>Last updated: February 2026</b></td>
</tr>
</table>

Expand Down Expand Up @@ -41,39 +41,101 @@ WhatsApp Forms reduce back-and-forth messaging and ensure clean, structured data

Steps:
1. Go to `Quick Tools` → `WhatsApp Forms` in Glific.
2. Click `Create Form`
3. Go to WhatsApp Flows Playground to get a friendly interface to create your form
4. Choose field types and design your form (text input, radio, multi-select, etc.)
5. Click on `copy flow JSON` after completing the form design
6. Paste the Flow JSON into the `form JSON` input field
7. Give your form an appropriate `title`, `description` and `category`
8. Click on `Save`
9. This creates a draft of the form
10. On the `WhatsApp Forms` Listing page, click on the publish icon to publish the form.
2. Click `Create` Form
3. Provide a form `title` and `category`
4. For data storage, add a `google sheet` with write access to the google service account to automatically capture the responses to the form. This step is optional. A google sheet can be added before the form is `submitted to Meta`
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Capitalize “Google” consistently.

Multiple instances use “google” in running text. Please capitalize the proper noun.

Also applies to: 96-96, 128-128

🧰 Tools
🪛 LanguageTool

[uncategorized] ~46-~46: “Google” is a proper noun and needs to be capitalized.
Context: ...google sheet with write access to the google service account to automatically captur...

(A_GOOGLE)


[uncategorized] ~46-~46: “Google” is a proper noun and needs to be capitalized.
Context: ...s to the form. This step is optional. A google sheet can be added before the form is `...

(A_GOOGLE)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 46, The document uses the
lowercase proper noun "google" in phrases like "google sheet" and "google
service account" (e.g., the text "add a `google sheet` with write access to the
google service account"); update these occurrences to use the correct
capitalization "Google" (e.g., "Google Sheet", "Google service account")
consistently throughout the file, including the instances referenced at lines
46, 96, and 128.

6. Click on Save and go to the form builder interface
<img width="568" height="386" alt="Screenshot 2026-02-24 at 3 51 24 PM" src="https://github.com/user-attachments/assets/15e81cc8-0da5-43a0-95fd-298177bb567a" />
Comment on lines 42 to +48
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fix broken step numbering.

There are skipped numbers in multiple step lists (e.g., 4→6, 2→4, 1→3), which makes the instructions hard to follow. Please renumber for continuity.

Also applies to: 61-65, 154-156

🧰 Tools
🪛 LanguageTool

[uncategorized] ~46-~46: “Google” is a proper noun and needs to be capitalized.
Context: ...google sheet with write access to the google service account to automatically captur...

(A_GOOGLE)


[uncategorized] ~46-~46: “Google” is a proper noun and needs to be capitalized.
Context: ...s to the form. This step is optional. A google sheet can be added before the form is `...

(A_GOOGLE)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md around lines 42 - 48, The ordered
step lists in WhatsApp Forms.md have skipped numbers (e.g., 1,2,3,4,6) which
breaks continuity; update each "Steps:" ordered list so numbering is sequential
and continuous (e.g., change the block that currently reads 1,2,3,4,6 to
1,2,3,4,5) and repeat the same fix for the other occurrences referenced (the
lists around lines 61-65 and 154-156); ensure every "Steps:" section and its
items are renumbered to a consecutive sequence without gaps so users can follow
instructions linearly.


<iframe
width="560"
height="315"
src="https://drive.google.com/file/d/1PxitFQIRKBrpvmOzbM4ZSd4WIUFCCoK9/preview"
frameborder="0"
allow="autoplay"
allowfullscreen>
</iframe>
### Navigating the form builder interface.
The form builder interface can be used to create forms

There are 3 major actions:

1. Form Json - this allows you to toggle to the from json view, and edit things in the form json as it gets developed by adding screens and components from
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Complete the unfinished sentence in “Form Json” description.

The sentence ends with “from” and is incomplete, so readers won’t know the source/context.

✍️ Proposed text fix
-1. Form Json - this allows you to toggle to the from json view, and edit things in the form json as it gets developed by adding screens and components from 
+1. Form Json - this allows you to toggle to the form JSON view and edit the JSON generated as you add screens and components from the builder.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 55, The "Form Json"
description sentence is incomplete; update the line starting "1. Form Json -
this allows you to toggle to the from json view, and edit things in the form
json as it gets developed by adding screens and components from" to finish the
thought—e.g., state the source/context such as "from the form builder" or "from
the UI editor" so it reads clearly (e.g., "...by adding screens and components
from the form builder"); ensure the phrase "form json" is corrected to "form
JSON" for consistency if desired.

2. Save Draft - while the changes being made are auto-saved, this button is provided as a back-up.
3. Submit to Meta - this is the final step of form creation. Click on `Submit to meta` once the form is ready to be used by over WhatsApp. Please note: once the form is submitted to meta, it cannot be changed further. To make changes, a new form will need to be created and modified.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fix grammatical and terminology inconsistencies.

Two issues in this line:

  1. "over WhatsApp" should be "on WhatsApp" for proper usage
  2. "submitted to meta" should use capital "M" in "Meta" for consistency with "Submit to Meta" button name used throughout
📝 Proposed fix
-3. Submit to Meta - this is the final step of form creation. Click on `Submit to meta` once the form is ready to be used by over WhatsApp. Please note: once the form is submitted to meta, it cannot be changed further. To make changes, a new form will need to be created and modified.
+3. Submit to Meta - this is the final step of form creation. Click on `Submit to Meta` once the form is ready to be used on WhatsApp. Please note: once the form is submitted to Meta, it cannot be changed further. To make changes, a new form will need to be created and modified.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 57, Update the sentence
that begins "Submit to Meta - this is the final step of form creation..." to
correct two issues: change "over WhatsApp" to "on WhatsApp" and capitalize
"Meta" in "submitted to meta" so it reads consistently with the "Submit to Meta"
button name; ensure the final sentence reads that once the form is "submitted to
Meta" it cannot be changed and a new form must be created to modify it.


Comment on lines +55 to +58
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟠 Major

Align lifecycle terminology (“Submit to Meta” vs “published”).

The doc states forms must be “submitted to Meta” and then later says they must be “published.” These appear to describe the same lifecycle step; inconsistent terminology will confuse users. Please standardize on one term across the guide and FAQs.

Also applies to: 223-226, 239-245

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md around lines 55 - 58, The doc
uses two different lifecycle terms—“Submit to Meta” (button/step label) and
“published” (descriptive state); pick one term and make it consistent across the
guide and FAQs (replace occurrences of “published” with “Submit to Meta” or vice
versa), update the Form Features section lines referencing the final step (e.g.,
the “Submit to Meta” button text) and the FAQ/other sections (previously lines
~223-226 and ~239-245) so they use the chosen term consistently, and keep the
immutability note (“once the form is submitted to meta, it cannot be changed
further”) aligned to the chosen terminology.

<img width="570" height="365" alt="Screenshot 2026-02-24 at 3 54 14 PM" src="https://github.com/user-attachments/assets/08b36aa4-3d3b-46f0-8251-db54da39f050" />

Other details:

1. There is a form builder section with buttons to add content to the form like dropdowns, checkboxes, date fields, titles, captions, images and new screens to build out the form with required fields.
2. The preview section allows you to get glimpse of how the form will turn out on WhatsApp. The preview has tabs to `preview`, see the `field names` and the `revision history` of the form.
4. Please note, the preview mode is not fully representative of how the form will look on WhatsApp of your beneficiaries, as this varies a lot based on the version of WhatsApp and the device type such as android, ios etc.

### Form Builder Action
1. Adding screens: Use `Add new` button to the in line of the Screens header to add new screens. Screen title can be added in the `Screen Name` entry field
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fix awkward phrasing.

"to the in line of" is grammatically incorrect. Should be "next to" or "inline with".

📝 Proposed fix
-1. Adding screens: Use `Add new` button to the in line of the Screens header to add new screens. Screen title can be added in the `Screen Name` entry field
+1. Adding screens: Use the `Add New` button next to the Screens header to add new screens. Screen title can be added in the `Screen Name` entry field.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
1. Adding screens: Use `Add new` button to the in line of the Screens header to add new screens. Screen title can be added in the `Screen Name` entry field
1. Adding screens: Use the `Add New` button next to the Screens header to add new screens. Screen title can be added in the `Screen Name` entry field.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 68, Replace the awkward
phrase "to the in line of the Screens header" with a clear alternative; in the
sentence inside "Adding screens" change it to say either "Use the 'Add new'
button next to the Screens header to add new screens" or "Use the 'Add new'
button inline with the Screens header to add new screens," and keep the
remainder ("Screen title can be added in the `Screen Name` entry field")
unchanged.

2. Building the form: click on `Add Content` to select the type of data collection field you’d like to add under a particular screen.
<img width="696" height="788" alt="Screenshot 2026-02-24 at 5 02 06 PM" src="https://github.com/user-attachments/assets/6064456a-b3b0-480a-9c1c-96d9dbd245c7" />

### Types of content that can be added
1. **Titles and Captions**: Under the `Text` content, heading, subheading, captions, and texts can be added to the form.

<img width="1165" height="813" alt="Screenshot 2026-02-24 at 5 00 45 PM" src="https://github.com/user-attachments/assets/19b33e4a-48b5-4450-af39-976c9104dd44" />
2. **Media**: An image file, of type JPEG, PNG can be added upto 300kb in size.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

media is showing as md form in preview. this may not be an issue once it is published, i am not sure

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

this will change once it is published.

<img width="543" height="367" alt="Screenshot 2026-02-24 at 4 42 06 PM" src="https://github.com/user-attachments/assets/5ef5b08f-6b38-4b6f-842f-bc94845d29f0" />

3. **Text answer**: A short answer, paragraph answer of date field can be captured using this type.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Paragraph and date picker are different options right? this sentence may need to be rephrased
@mahajantejas

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

date picker is part of the short answer type, i have re-phrased it.

<img width="581" height="381" alt="Screenshot 2026-02-24 at 4 42 30 PM" src="https://github.com/user-attachments/assets/c3d56c7c-07fc-4b39-9286-485a892c8704" />

4. **Selection**: Dropdown, Single choice, multiple choice, opt-in can be collected using the selection type of content

<img width="561" height="384" alt="Screenshot 2026-02-24 at 4 42 45 PM" src="https://github.com/user-attachments/assets/589faff4-47b8-4edb-b382-967caecc5815" />

#### What are field names and how to use them?
Field name the the mandatory captions/ titles that appear above the input field in the form. This serves 2 function
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

'the' is repeating @mahajantejas

1. To appear as the caption for the user to see in the WhatsApp Form
2. To appear as the header under which the responses are being captured. The header can be seen by toggling to `Field Names` section next to `Preview` button
<img width="561" height="385" alt="Screenshot 2026-02-24 at 4 43 45 PM" src="https://github.com/user-attachments/assets/6bb2c0d4-e877-42d1-bcaf-13bfdd551e51" />


The header name can be changed by clicking on the edit button
<img width="566" height="386" alt="Screenshot 2026-02-24 at 4 44 32 PM" src="https://github.com/user-attachments/assets/f7068240-3f09-44c0-8df7-89b2cccfffef" />

Field names are useful to refer to any response from the form, and also the field names appear as the headers in the attached google sheet.

#### How to use field names in the flow
1. A form message should be always followed by a `wait for response` node. As shown in the screenshot below.
<img width="323" height="442" alt="Screenshot 2026-02-24 at 4 46 46 PM" src="https://github.com/user-attachments/assets/1d3db195-b770-42d7-9780-0fbf941a0e74" />

2. The send message node 89e6 sends the HSM with form to the user,
3. Wait for response node ad02 with the result name `result_1` captures all the responses to the form questions by the user
4. The send message node 888f, is used to display back to the user one of the responses, by going into the responses and referring to the particular field name in this case - `preferred_mode_of_payment` by printing `@results.result_1.preferred_mode_of_payment`


#### What are Option Ids and how to use them

The options listed under selection type of the content - dropdown or single choice or multiple choice show up in the form json. Each option has a `title` which is text that appears to the user in the whatsapp interface to select. There is also an `id`, this id is what gets returned as the response and remains invisible to the user.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Standardize WhatsApp capitalization.

"whatsapp interface" should be "WhatsApp interface" for consistency with the product name used throughout the document.

📝 Proposed fix
-The options listed under selection type of the content - dropdown or single choice or multiple choice show up in the form json. Each option has a `title` which is text that appears to the user in the whatsapp interface to select. There is also an `id`, this id is what gets returned as the response and remains invisible to the user.
+The options listed under selection type of the content - dropdown or single choice or multiple choice show up in the form json. Each option has a `title` which is text that appears to the user in the WhatsApp interface to select. There is also an `id`, this id is what gets returned as the response and remains invisible to the user.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The options listed under selection type of the content - dropdown or single choice or multiple choice show up in the form json. Each option has a `title` which is text that appears to the user in the whatsapp interface to select. There is also an `id`, this id is what gets returned as the response and remains invisible to the user.
The options listed under selection type of the content - dropdown or single choice or multiple choice show up in the form json. Each option has a `title` which is text that appears to the user in the WhatsApp interface to select. There is also an `id`, this id is what gets returned as the response and remains invisible to the user.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 109, Replace the
lowercase "whatsapp interface" phrase with the correct product capitalization
"WhatsApp interface" in the sentence that reads "Each option has a `title` which
is text that appears to the user in the whatsapp interface to select" so the
sentence uses "WhatsApp interface" consistently; update the same occurrence of
"whatsapp" (if duplicated) within that paragraph to "WhatsApp".


<img width="609" height="406" alt="Screenshot 2026-02-24 at 4 49 39 PM" src="https://github.com/user-attachments/assets/e5bb5a8f-4584-4148-9086-d5e53a2d647b" />

- In the above screenshot, a short section of the form json can be seen corresponding to the question of preferred mode of payment, and the list of options.

- The options show a distinct `title` which corresponds to what can be seen on the form page, and an `id`which is different from the title.

- Renaming the `option id` in the form json is an important step to ensure data captured is clean and as per the requirements of the program.

<img width="1242" height="833" alt="Screenshot 2026-02-24 at 4 51 15 PM" src="https://github.com/user-attachments/assets/650469e6-9068-4434-9ecf-149df19d11ca" />

**Implications of the id **
- This can help with multi-lingual forms by having the titles in local language, while the response getting captured and stored to be in english to help with collecting clean data.
- This can help with usecases where title and responses need to be abstracted away.

### Form creation checklist

Checklist to make sure the form is completed
1. There is a google sheet attached to the form for ease of collecting responses. While the responses to the form are synced to your bigquery by default, having a google sheet attached will help you to see responses quickly and easily.
2. The `field names` under which the responses will be captured is appropriate
3.The `option ids` for the fields with options are re-named in the flow json to reflect appropriate values that need to be collected in responses.
4. The form is `submitted to meta`

### How to Send WhatsApp Forms to users on WhatsApp

WhatsApp forms can be sent as HSM messages.
<iframe
width="560"
height="315"
src="https://drive.google.com/file/d/1YZGHR0ulaDnUcIBXKn3aj4HpMQS9jLww/preview"
frameborder="0"
allow="autoplay"
allowfullscreen>
</iframe>
WhatsApp forms can be sent to users when the forms are attached to HSM messages.

Steps:
1. Ensure that the form is in `published`
1. Ensure that the form is `submitted to meta`
2. Navigate to `Quick Tools` -> `HSM Templates` -> `Create`
3. Follow the steps to create the HSM template, by giving it a `title`, `element name`, `body` of the message,
4. Click on `Add buttons` and select `WhatsApp Forms`
Expand All @@ -84,35 +146,16 @@ Steps:
9. Use this HSM message inside the Glific flow.
10. Like any other HSM or send message node, ensure that this HSM follows a `wait for response` node. This node will help to record the response to the form fields.

<iframe
width="560"
height="315"
src="https://drive.google.com/file/d/1B4EnVGJ9cqinMw73kXudzYcm2bcEAiEJ/preview"
frameborder="0"
allow="autoplay"
allowfullscreen>
</iframe>

### How the WhatsApp Form results can be used in the Glific flow

The responses to the form can be captured, and used in the Glific for taking actions such as write to google sheet or can be used in split by logic to create separate branches in the glific flow based on the responses received to any particular fields on the form.
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

⚠️ Potential issue | 🟡 Minor

Fix awkward phrasing.

"in the Glific" should be "in Glific flows" for clarity.

📝 Proposed fix
-The responses to the form can be captured, and used in the Glific for taking actions such as write to google sheet or can be used  in split by logic to create separate branches in the glific flow based on the responses received to any particular fields on the form. 
+The responses to the form can be captured and used in Glific flows for taking actions such as writing to Google sheets or using split-by logic to create separate branches in the flow based on responses received to any particular fields on the form.
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
The responses to the form can be captured, and used in the Glific for taking actions such as write to google sheet or can be used in split by logic to create separate branches in the glific flow based on the responses received to any particular fields on the form.
The responses to the form can be captured and used in Glific flows for taking actions such as writing to Google sheets or using split-by logic to create separate branches in the flow based on responses received to any particular fields on the form.
🧰 Tools
🪛 LanguageTool

[grammar] ~152-~152: Use a hyphen to join words.
Context: ...to google sheet or can be used in split by logic to create separate branches in ...

(QB_NEW_EN_HYPHEN)


[grammar] ~152-~152: Use a hyphen to join words.
Context: ...google sheet or can be used in split by logic to create separate branches in the...

(QB_NEW_EN_HYPHEN)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/4`. Product Features/WhatsApp Forms.md at line 152, Replace the awkward
phrase "in the Glific" with "in Glific flows" in the sentence describing how
form responses are used; update the sentence in the WhatsApp Forms documentation
(the line that starts "The responses to the form can be captured...") to read
"...can be captured, and used in Glific flows for taking actions such as write
to google sheet or can be used in split by logic..." and adjust surrounding
punctuation/spacing so the sentence remains grammatical.


To use this
1. The variable names for each field in the form come up on the “view” screen of the form
2. These variable names follow the pattern of `screen_number_label`
3. Take a note of all the these form variable names from the form view page
1. The field names for each field in the form come up on the “field names” screen of the form
3. Take a note of all the these form field names
4. In the flow, use `wait for response` node after the `send contact a message` node which is sending the form HSM message
5. Now to reference each variable from the form response, use the following syntax: `@results.form.screen_0_<label>`


<iframe
width="560"
height="315"
src="https://drive.google.com/file/d/1Uedfm3JDLnkhSHjVcUrLZolUixo4RUkX/preview"
frameborder="0"
allow="autoplay"
allowfullscreen>
</iframe>

### How WhatsApp Form Results Come to BigQuery
1. Ensure your Glific account is connected to BigQuery instance
Expand Down Expand Up @@ -191,16 +234,9 @@ In the above SQL snippet change the following
11. Each language variation must be attached to a language-specific HSM. Follow this [documentation on multi-lingual HSMs](https://glific.github.io/docs/docs/Product%20Features/HSM%20Templates/#approve-multi-lingual-hsm-templates) to learn more.
### FAQs

1. Why do I need to use the Meta’s Playground to create the forms?

Glific currently uses the Meta WhatsApp Flows Playground to
- Get a cleaner UI to create the form
- Preview the form structure
- Validate form structure
- Test multi-screen navigation
- Get the final JSON code required for Glific

2. What is the draft state of the form
1. What is the draft state of the form

Draft state of the form is when the form entity is created in Glific and it can be edited to improve the UI, but the form is not yet published with Meta, therefore it cannot be used in HSMs and it is not yet available to use via WhatsApp

Expand All @@ -220,9 +256,6 @@ The responses captured from whatsapp forms are returned along with the index of

Using the form in Business Initiated Message scenarios incurs the cost of category of the HSM message the form is attached to. Using the form under service message type scenarios is free of charge. Service messages means when a user initiates the conversation by entering a keyword or clicking on the WhatsApp keyword-encoded link and starting the conversation with the chatbot of your organization.

7. Why can I not see WhatsApp forms option under Quick Tools?

WhatsApp forms is a trial feature released to beta-tester organizations. If you'd like to try it out, please reach out to [tejas@glific.org](mailto:tejas@glific.org).



Expand Down