# WhatsApp Flows - Forms

{{<tags >}}

WhatsApp Flows (Forms) allow you to integrate structured forms within a WhatsApp conversation, making data collection faster and more precise, which reduces errors. This approach minimizes typing mistakes common in traditional chat-based interactions, enhancing the user experience and preventing long, overwhelming flows in the **Flow Builder**.

You can collect various data types and organize questions into sections for a smoother experience. Responses are stored in variables, enabling integration with other flow blocks, such as **Electronic Signature**, **Open Question**, **Finish Chat**, or any other block that supports variable insertion.

In this guide, you'll learn how to create a **WhatsApp Form** and integrate it into a **WhatsApp Flow**.

## Prerequisites

To flawlessly perform the steps of this guide, ensure the following prerequisites are met:

1. **Truora Account**: If you don't already have one, learn how to {{< newtab href="/customer-engagement/account/" >}}Set up a Truora account{{< /newtab >}}.
2. **Activated WhatsApp line**: Follow this {{< newtab href="/guides/waba_acquisition/" >}}guide{{< /newtab >}} to acquire and activate WhatsApp lines in **Truora**.
3. **Know how to create a WhatsApp Flow**: Learn how to {{< newtab href="/guides/flows" >}}Create a WhatsApp Flow{{< /newtab >}} in **Truora**.
4. **Familiarize with Variables**: Having a basic understanding of Flows Variables. If you haven't already, check out our {{< newtab href="/guides/variables/" >}}Using Variables{{< /newtab >}} guide.

## Create a new form

1. Log in to [Truora dashboard](https://connect.truora.com/), and click **Open** under the **Customer Engagement** section.

2. Select the **WhatsApp Flows (Forms)** tab. 

    - If it is your first form, click on **+ Create form**.
    - Otherwise, click **+ New form** in the forms list screen to create a new one.

3. Select your **WABA** and click **Start**. Only the lines associated with this WABA will be able to use the form.

{{<img src="/images/illustrations/wa_forms/01_create_wa_form.gif" class="border border-slate-300 rounded-md" alt="Create form" width="100%">}}

4. Enter a **name** for your **Form** in the top navigation bar.

5. Add a **Title** and a **Description** for the first section.

6. Click **Save** in the navbar to create the form.

{{<img src="/images/illustrations/wa_forms/02_title_and_save_wa_form.gif" class="border border-slate-300 rounded-md" alt="form saved" width="100%">}}

### Pre-filling Data with Form Inputs

You can significantly reduce user friction in WhatsApp by pre-filling form fields with data already collected in your chat flow (such as a name, ID number, or preferences).

To use this feature, you must first define your variables within the Form editor.

For step-by-step instructions on how to define keys, set data types (Text, Number, Boolean), and handle character limits, please refer to the {{< newtab href="/guides/forms/#form-inputs-preloading-data" >}}Form Inputs Configuration Guide {{< /newtab >}}.

### Edit, Add, Duplicate and Delete Questions

#### Edit existing question

A default question is created when you create a form. Modify its text, and customize its settings using these options at the bottom of the question card:

  - **Required Toggle** - Defines whether the question is mandatory.
  - **Input Type Dropdown** – Selects the input type for the response. 
  
  {{<img src="/images/illustrations/wa_forms/03_first_wa_form_question.gif" class="border border-slate-300 rounded-md" alt="input types" width="100%">}}

The following is a breakdown of the available input types:

  {{<table "table w-auto small m-auto text-center table-striped table-bordered">}}
| Question type     | Description                                               |
|-------------------|-----------------------------------------------------------|
| Short answer      | Allows responses up to 250 characters and supports advanced validation patterns (Alphanumeric, Numbers, Letters, URL, or Custom Regex) to ensure data matches your required format. |
| Long text         | Limits responses to 1000 characters.                      |
| Numeric           | Accepts only numbers between f-2147483647 and 2147483647. |
| Multiple choice   | Displays checkboxes for multiple selections.              |
| Unique selection  | Displays radio buttons for a single selection.            |
| List              | Provides a dropdown menu for selection.                   |
| Date              | Uses a date picker.                                       |
| Email             | Requires a valid email format.                            |
| Phone             | Requires a valid phone number.                            |
| Password | Creates a secure input field where characters are masked by default. Includes a "show/hide" eye icon for users to verify their entry while typing. |
  {{</table>}}

#### Dynamic lists

For input types that have options like Multiple choice, Unique selection, and List, you can configure dynamic lists. To enable dynamic lists, first activate the "Dynamic options" switch in the question settings. This will display the integration configuration options. Dynamic lists allow you to populate the options automatically from an external data source through an integration.

To set up a dynamic list, you must first create an integration. Learn how to create and configure integrations in the [Custom integrations Guide](/guides/api_external_connection_wa_flows/).

When configuring a dynamic list, you'll need to:
1. Select the integration you want to use
2. Choose the specific action from that integration
3. Select the credential that will be used to authenticate the requests

**Important**: The integration action must have an output with a JSON array with objects containing `id` and `title` properties. For example:
```json
[
  {"id": "1", "title": "Option 1"},
  {"id": "2", "title": "Option 2"},
  {"id": "3", "title": "Option 3"}
]
```

The dynamic list component only accepts this specific format. Any other format will not be processed by the component.

##### Using Variables in Dynamic Lists

If your form uses **Dynamic Lists** to fetch data from an external API, you can use Form Input variables as parameters. For example, you can pass a `@document_id` captured in WhatsApp to an integration that fetches a user’s specific addresses.

- Under `Config Input Values`, type `@` to see your list of defined variables.

- Select the variable you wish to send to your integration.

{{<img src="/images/illustrations/forms/dynamic_list_variables.png" class="border border-slate-400 rounded-md" alt="dynamic list variables" width="60%">}}

#### Adding a new question

Click **+ New question** in the question card tools, select a question type, and a new question card will be added.

{{<img src="/images/illustrations/wa_forms/04_add_new_question.gif" class="border border-slate-300 rounded-md" alt="Add new question" width="60%">}}


#### Duplicate a question

To create an identical question, click the **Duplicate** button. A new question card will be generated with the same content.

{{<img src="/images/illustrations/wa_forms/05_duplicate_question.gif" class="border border-slate-300 rounded-md" alt="Duplicate question" width="60%">}}

#### Delete a question

Click the **Delete** icon to remove a question.

{{<img src="/images/illustrations/wa_forms/06_delete_question.gif" class="border border-slate-300 rounded-md" alt="Delete question" width="60%">}}

### Form sections

Sections help you organize questions into separate pages, making forms easier to navigate and preventing long, overwhelming screens. Each section can hold up to 50 questions.

  - To add a new section, click the **New section** icon in the question card tools. 
    - A section thumbnail will appear at the top, displaying "**Section N of Total sections**" with an "**X**" to delete it.
  
  {{<img src="/images/illustrations/wa_forms/07_add_section.gif" class="border border-slate-300 rounded-md" alt="add section" width="60%">}}

  - If you want to delete a **section with questions**, a confirmation modal will appear, allowing you to select either to **delete questions within this section** or **move them to the previous section**.
  
  {{<img src="/images/illustrations/wa_forms/08_delete_section.gif" class="border border-slate-300 rounded-md" alt="delete section modal" width="60%">}}

### Preview a form

Click the **Preview** button in the navbar to see how users will experience the form. The preview mode lets you navigate through sections and view the form's layout.

In the top menu of the preview bar, you can:

  1. Switch between form sections.
  2. Click the **Settings** icon to:<br><br> 
    **•** Select **Android** or **iOS** preview.<br>
    **•** Toggle between **light** and **dark** mode.

{{<img src="/images/illustrations/wa_forms/09_preview_wa_form.gif" class="border border-slate-300 rounded-md" alt="WA form preview" width="100%">}}

### Save and publish

Click **Publish** in the navbar to make your form available for use in **WhatsApp Flows**.

{{<img src="/images/illustrations/wa_forms/10_publish_wa_form.gif" class="border border-slate-300 rounded-md" alt="WA form publishing" width="100%">}}

### Copy a form

To duplicate a published form:

  1. Go to **WA Flows (forms)** tab.
  2. Find the form you want to copy and click on it.
  3. Click on **Create Copy**. A new, editable copy of the form will open.
  4. Make the necessary changes, then **Save** and **Publish** the new form.

{{<img src="/images/illustrations/wa_forms/11_copy_wa_form.gif" class="border border-slate-300 rounded-md" alt="WA form copy" width="100%">}}

<br><br>

---

## Integrating a Form into a WhatsApp Flow

Follow these steps to integrate a form into a **WhatsApp Flow** to collect user data.

### Adding a Form to the Flow

1. In the **Flow Builder**, locate the **Forms** block under **Advanced Blocks** and drag it into your flow.
2. Click the block to open its **Properties**:
 - **Title**: Name the block for easy identification.
 - **Select Form**: From the dropdown list, select the form that should be displayed during the flow execution.
 - **+Create form**: If you haven't created a form yet, click this option to open the form creation window.
 - **Message**: Write the message that will be sent to the user to start the form.
 - **Button Text**: Define the button label users will click to open the form.

{{<img src="/images/illustrations/wa_forms/12_add_form_block.gif" class="border border-slate-300 rounded-md" alt="Add Form block" width="100%">}}

### Pre-filling Data with Form Inputs

Once your variables are defined, you can "link" them to the output of previous blocks in the **Flow Builder**.

1. **Select the Form Block**: Click on the Forms block in your flow.

2. **Configure Inputs**: Look for the **Inputs** section in the configuration panel. All form input variables defined in your form will appear here, allowing you to choose which ones to pre-fill.

3. **Reference Previous Outputs**: Click the input field and type `@` to see a list of available data from previous steps (e.g., `{{document_validation.id_number}}`).

4. **Save Changes**: Click **Add inputs** to finalize the mapping.

{{<img src="/images/illustrations/wa_forms/15_referenciate_form_inputs.gif" class="border border-slate-400 rounded-md" alt="Mapping flow variables to form inputs" width="100%">}}

#### Important Constraints

When pre-filling selection-based questions (Unique Selection or Lists), keep the following in mind:

- **30-Character Limit**: Each answer choice has a maximum limit of 30 characters. This limit applies to the final value after the variable is replaced.

- **Truncation Warning**: If the combined text and variable value exceed 30 characters, WhatsApp can truncate the text. Ensure your data is concise to prevent users from seeing cut-off information.

### Using Form variables

Below the form selector, you'll find a list of variables corresponding to each form question:

  - Click the **copy icon** next to a variable to use it in other blocks.
  - Alternatively, type "@" in any destination block to open the variable selector and reference form responses.

{{<img src="/images/illustrations/wa_forms/13_wa_form_variables.gif" class="border border-slate-300 rounded-md" alt="Add Form block" width="80%">}}

In this guide's example, form variables were used in the **Finish Chat** block to confirm the user's subscription with the details they provided.

{{<img src="/images/illustrations/wa_forms/14_wa_form_variables_message.png" class="border border-slate-400 rounded-md" alt="forms empty state" width="50%">}}

### Process with form execution
When a user executes the flow, the form will be displayed for the end user to fill it out. If the form has multiple sections, each section will appear on a separate page for easier navigation.

 - **Form input validation** - Each input includes validation to prevent incorrect data type entry. If the input is invalid, a message will be displayed, and the user will not be able to proceed to the next section or complete the form.
 - **Process execution** - Once the form is completed, the process will move to the next step of your flow, and the variables will be processed based on the configuration of the subsequent block: For this guide's example, variables were included in the message sent to the user, to confirm the user's subscription with the data they entered.


<div class="flex justify-between">
   <div class="flex flex-col items-center">
    <p class="text-center font-bold text-sm">Form Input Validation</p>
    {{<img src="/images/illustrations/wa_forms/15_validate_form_input.gif" class="border border-slate-300 rounded-md" alt="Validate Form input" width="80%">}}
   </div>
   <div class="flex flex-col items-center">
    <p class="text-center font-bold text-sm">Process Execution</p> 
  {{<img src="/images/illustrations/wa_forms/16_wa_form_flow_execution.gif" class="border border-slate-300 rounded-md" alt="WA Form Flow execution " width="80%">}}
   </div>
</div>