@@ -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`
+6. Click on Save and go to the form builder interface
+
-
+### 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
+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.
+
+
+
+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 a 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
+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.
+
+
+### 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.
+
+
+2. **Media**: An image file, of type JPEG, PNG can be added upto 300kb in size.
+
+
+3. **Text answer**: A short answer, paragraph answer or date field can be captured using this type.
+
+
+4. **Selection**: Dropdown, Single choice, multiple choice, opt-in can be collected using the selection type of content
+
+
+
+#### What are field names and how to use them?
+Field names are the captions/ titles that appear above the input field in the form. This serves 2 function
+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
+
+
+
+The header name can be changed by clicking on the edit button
+
+
+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.
+
+
+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.
+
+
+
+- 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.
+
+
+
+**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 use cases 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 fields with options are renamed in the form JSON to reflect the values that need to be collected.
+4. The form is `submitted to Meta`.
### How to Send WhatsApp Forms to users on WhatsApp
-WhatsApp forms can be sent as HSM messages.
-
+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`
@@ -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.
-
### 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.
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_