> ## Documentation Index
> Fetch the complete documentation index at: https://docs.theomnibot.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Questionnaires: Collect and Validate User Responses

> Build multi-question sequences inside a Flow to collect, validate, and score user responses, then review results in the Applicants dashboard.

Questionnaires let you create a sequence of questions that collect information from users inside a Flow. You can validate response formats, assign scores to answers, save data to Contact Fields, and review results in the Applicants section. Use this feature for order forms, surveys, quizzes, consultation requests, or delivery information collection.

## Access and Manage Questionnaires

<Steps>
  <Step title="Open Tools">
    Select **Tools** from the left navigation menu.
  </Step>

  <Step title="Select Questionnaires">
    Click the **Questionnaires** card to open the management page.
  </Step>

  <Step title="Create a questionnaire">
    Click **Add**, enter a name for the questionnaire, and start adding questions.
  </Step>
</Steps>

The management page displays each questionnaire's name, its number of Applicants, and an **Actions** menu. Use **Search name…** to find a questionnaire quickly. The Actions menu provides these options:

| Action         | Description                                        |
| -------------- | -------------------------------------------------- |
| **Applicants** | View participants and their individual responses.  |
| **Rename**     | Change the questionnaire name.                     |
| **Duplicate**  | Create a copy you can edit as a new questionnaire. |
| **Delete**     | Permanently remove the questionnaire.              |

## Create and Configure Questions

The **Questions** page contains General settings and individual question blocks. You can add, duplicate, reorder, deactivate, or delete individual questions at any time.

### General Settings

| Setting                                               | Function                                                                                                                                                 |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Trigger the flow by completing the questionnaire**  | Select a Flow to run automatically after the user finishes the questionnaire.                                                                            |
| **Give points for each question answered**            | Enables scoring and displays a Points field under each question or answer option. ChatbotX saves the total score to the `{{last_points}}` System Field.  |
| **Customize retry messages in case of reply failure** | Validates responses and lets you write a custom message sent when the data is invalid. Applies to Text, Number, Email, Phone, and Quick Reply responses. |
| **Save data to custom fields**                        | Saves each response to a Custom Field or System Field of your choice.                                                                                    |

### Per-Question Settings

Each question block includes the following settings:

| Setting                                       | Description                                                                   |
| --------------------------------------------- | ----------------------------------------------------------------------------- |
| **Question**                                  | The message the Bot sends to the user.                                        |
| **Question Image**                            | An optional image sent alongside the question. Upload a file or insert a URL. |
| **Active**                                    | Toggle to enable or disable the question without deleting it.                 |
| **Response Type**                             | The type of answer the user must provide (see below).                         |
| **Points**                                    | The score assigned to the answer when scoring is enabled.                     |
| **Retry message if the reply is invalid**     | The message sent when the response does not match the expected type.          |
| **Save response to a custom or system field** | The field where ChatbotX stores the user's answer.                            |

Use the icons beside each question to delete, duplicate, or reorder it. Click **Add New** to add another question, then click **Save** to save the questionnaire.

### Handling Invalid Responses

When a user's response does not match the selected Response Type, the Bot sends the retry message and asks the user to try again. After three consecutive failed attempts, ChatbotX exits the questionnaire and continues to the next block in the Flow.

<Warning>
  After three invalid responses, ChatbotX exits the questionnaire entirely. Make sure your retry messages are clear and help the user understand exactly what format is expected.
</Warning>

## Response Types

Questionnaires support five Response Types:

| Type                | Behavior                                             |
| ------------------- | ---------------------------------------------------- |
| **Text**            | Accepts any text response.                           |
| **Number**          | Accepts numeric data only.                           |
| **Email**           | Validates the email address format before accepting. |
| **Phone**           | Validates the phone number format before accepting.  |
| **Multiple choice** | Displays answer options as Quick Reply buttons.      |

With **Multiple choice** you can create multiple answer options under **Options**, assign a separate score to each option, reorder options using the arrows, delete unneeded options, and add new ones with **Add**.

## Review Results in Applicants

When a user completes a questionnaire, ChatbotX saves the result in **Applicants**. The overview shows:

* **Applicants** — total number of participants.
* **Completed** — number of fully completed questionnaires.
* **Completion rate** — the percentage of participants who finished.

The Applicants table lets you search by name and review the **Name**, **Points**, **Status**, and **Date** columns, with sorting available on supported columns. Click a user's name to see their total score, individual responses, and the points awarded for each answer. Click **Inbox** to open the applicant's conversation when you need to follow up.

## Use Questionnaires in a Flow

### Add a Questionnaires Action

<Steps>
  <Step title="Open Send Message">
    Create or open a **Send Message** block in Flow Builder.
  </Step>

  <Step title="Open Actions">
    Click **Create**, select **Actions**, then select **Questionnaires**.
  </Step>

  <Step title="Select a Mode">
    Open **Edit** and select the Mode that matches the purpose of the block.

    | Mode                    | Function                                                                                    |
    | ----------------------- | ------------------------------------------------------------------------------------------- |
    | **Start questionnaire** | Starts the selected questionnaire and asks questions in sequence.                           |
    | **End questionnaire**   | Ends the current questionnaire and saves the result in Applicants.                          |
    | **Delete applicant**    | Removes the user from Applicants so they can complete the questionnaire again from scratch. |
  </Step>
</Steps>

### Delivery Information Flow Example

Create a Send Message that asks whether the user wants to provide delivery information. Connect the **Enter information** button to a block containing the **Start questionnaire** Action. When the user clicks, the Bot asks for their phone number, address, payment method, and email in sequence.

## How Questionnaire Progress Is Preserved

ChatbotX tracks each user's progress through a questionnaire so sessions can resume correctly:

* If a user answers the first question and the Flow returns to the **Start questionnaire** block, the Bot continues from the next unanswered question.
* A questionnaire is considered complete after the user answers every active question.
* The **End questionnaire** Mode also ends the questionnaire and saves the result in Applicants.
* A user already listed in Applicants cannot complete the same questionnaire again without being removed first.
* Run **Delete applicant** to clear the previous result and allow the user to start over.
* If a response matches a Keyword trigger during an active questionnaire, ChatbotX prioritizes and fires that Keyword.
* After three invalid responses, ChatbotX exits the questionnaire and moves to the next block in the Flow.

<Tip>
  Select the correct Contact Field for each question before saving. Reusing stored values like phone numbers, email addresses, and delivery addresses across multiple Flows saves you significant setup time.
</Tip>