# Show a form in the chat widget

> Attach a form to a deployment and choose exactly when visitors see it.

You decide when a form appears in a conversation: before the chat starts, after a few messages, when the chat goes quiet, and more. A deployment can show several forms, each with its own trigger.

## Add a form to a deployment

1. Open **Deployments** and select the deployment. Forms work on widget and hosted page deployments.
2. Go to the **Chat widget** tab and find **Forms**.
3. Select **Add form**, then pick the **Form**. Only enabled forms can be picked.
4. Choose **When** it appears and, where it needs one, its value.
5. Set the **Frequency** and the options below.
6. Select **Save changes**.

A deployment can have up to 20 forms. A new one starts with **When** set to **Before chat starts** and **Frequency** set to **Once per visitor**. **Required to chat** and **Can be skipped** start off. **Share answers with the agent**, **Can be reopened** and **Answers can be reviewed** start on.

## When it appears

| When | The form appears |
| --- | --- |
| Before chat starts | Before the visitor's first message |
| After N messages | Once the visitor has sent the **Message count** you set |
| After idle | After the chat has been idle for the **Idle seconds** you set |
| On page area | On pages your site marks with that **Page area** |
| When conversation closes | When the conversation ends and can't take new messages |
| When panel closes | When the visitor closes the chat panel |
| Manual (open via code) | When your own code opens it |

Only one form shows at a time. If two could show at the same moment, the one higher in the list wins.

A form shows as the last item in the conversation. With **Required to chat** on, the message box is locked until the visitor submits it, or skips it when **Can be skipped** is on, whatever made it appear. With it off, the visitor can keep chatting while the form stays on screen. Each submitted or skipped form leaves a small marker in the conversation.

## Frequency

- **Once per visitor:** the form shows once in each visitor's browser, whether they submit it or skip it.
- **Once per conversation:** the form shows once in each conversation, so it comes back when the visitor starts a new one.
- **Every time:** the form shows each time its moment comes.

## Options

- **Required to chat:** the visitor submits the form, or skips it, before they can send a message.
- **Can be skipped:** shows a button to skip the form. In English it reads **Maybe later**.
- **Can be reopened:** a skipped form keeps a **Fill out** button, so the visitor can finish it later, even after a page reload.
- **Answers can be reviewed:** after submitting, the visitor can open a read-only copy of their answers.
- **Share answers with the agent:** the agent sees the answers with every message, so it doesn't need to ask again. Turn it off for sensitive details.

## Conditions

Under **Conditions (optional)**, you can limit when a form shows:

| Condition | The form shows only |
| --- | --- |
| After messages | Once the visitor has sent at least this many messages (0 to 1000) |
| Before messages | Until the visitor has sent more than this many messages (0 to 1000) |
| Page area | On these page areas, comma separated, such as `pricing, checkout` |
| Only if unknown | While your site hasn't passed any of these visitor details, one per line, such as `email` |

**On page area** and the **Page area** condition match an area your site sets: add `data-page-area="checkout"` to the widget's script tag, or call `chat.setPageContext({ area: 'checkout' })` from your code. **Only if unknown** checks the details your site passes, such as `data-user-email` on the script tag. Answers to other forms don't count. See [Tell the AI agent about your visitor and page](https://docs.help.ai/customize-and-extend-the-widget/pass-visitor-and-page-details).

## Open a form from your own code

1. Add the form with **When** set to **Manual (open via code)**, and select **Save changes**.
2. Open the form in **Forms**. Its ID is the part of the page's address right after `/forms/`.
3. Open it from your page:

```js
const chat = await HelpAI.ready();
chat.open();
chat.openForm('FORM_ID');
```

A form opened this way ignores **Frequency** and the conditions.

## Recipes

| Goal | Setup |
| --- | --- |
| Capture leads without a wall | After N messages, Once per visitor, Can be skipped |
| Collect details before the chat | Before chat starts, Once per visitor, Can be skipped off |
| Ask for a rating | When conversation closes, Every time, Can be skipped |
| Ask on the checkout page only | On page area `checkout`, Once per visitor, Can be skipped |

Answers land in **Forms**. See [Review and export form submissions](https://support.help.ai/forms/review-and-export-submissions).

<Tip>
Turn off **Share answers with the agent** and **Answers can be reviewed** for sensitive answers, such as health or financial details.
</Tip>