Show a form in the chat widget

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#

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:

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 (opens another site).

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:

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

A form opened this way ignores Frequency and the conditions.

Recipes#

Answers land in Forms. See Review and export form submissions.