Data forms

A data form tells the agent to collect specific details in the conversation, such as a refund request, a callback or a quote. You name the form, say when it applies and list the fields; the agent asks for them one or two at a time, checks every answer, and files the completed form under Collected data, with the option to save the answers on the contact.

Create a form

1. Open Custom Actions and click New data form

   Forms are listed in the Data forms section of the same page, below your actions.

2. Name it and say when to collect it

   Name (up to 60 characters) and When should the agent collect this? (up to 500). The second field is what the agent reads to decide, so describe the situation: "When a customer wants a refund or reports a damaged delivery."

3. Add the fields

   Up to 20, each with a Label (up to 60 characters), a Type, a Required checkbox (ticked by default) and an optional hint for the agent (up to 200), such as "starts with PC-". The key under the field, for example key: order_number, is made from the label and is where answers are stored; renaming the label later keeps it.

4. Choose where the answers go

   Save answers on the contact is on by default. See Save answers on the contact below.

5. Click Create form

   A new form is switched on straight away. The switch on its card turns it off without deleting it; the agent only uses forms that are on.

Field types

A required field with no answer gives Order number is required. The field's label starts each message.

How the agent uses a form

Every form that is on becomes a tool for the agent, described by its name, its "when" text and its fields. When the conversation matches, the agent:

• asks for the fields one or two per message, never as a numbered form, and confirms what the visitor typed;
• never guesses a value, and leaves an optional field out if the visitor declines;
• skips fields about the person (name, email, phone, company) it already knows from the visitor profile;
• submits the form once, with exactly what the visitor gave.

Every answer is checked again on the server. When one fails, the agent gets the message from the table above and asks the visitor to correct it. After a save the agent thanks the visitor briefly and does not ask again. Inside a procedure, it goes straight on to the tool the next step names.

Each completed form counts in the Action calls card on Analytics, for example as Collect data: Refund request.

Save answers on the contact

A submission is linked to a contact whenever an email address is known: the visitor's verified email if they have one, otherwise the first Email field in the form, otherwise an address the session already has. A verified visitor who types another address keeps their own contact; the typed address is only an answer.

That contact is created or updated whatever the setting, with the source Collected data on the Contacts page. A new contact counts as a new lead, so your lead notifications and the lead.created webhook event go out.

With Save answers on the contact on, every answer is also stored as a custom attribute on the contact, under the field's key, and the form fills these columns:

With it off, the answers stay under Collected data only. In later conversations the agent reads a contact's attributes only when the visitor's email is proven, by email verification or your site's identity token.

Test chats

In the Test the agent drawer and in agent tests, the agent goes through the form as usual, but nothing is saved: no row under Collected data, no contact, no webhook. It still counts as called in an agent test.

The Collected data page

Open Collected data in the sidebar, under Support. Submissions are listed newest first, 25 at a time as you scroll.

• Form filters the table; with one form selected, its fields are the columns, in order. Visitor shows the name and the email or customer id, and Open in the Chat column opens the conversation.
• The bin icon deletes one submission after a confirmation.
• Export CSV downloads collected-data-YYYY-MM-DD.csv with every submission of the selected form (or all forms), up to 10,000 rows: Form, Visitor, Email, Customer id, one column per field, Conversation and Submitted (ISO 8601).

In the inbox, a conversation's visitor panel shows each form completed in it, titled with the form name. Deleting a form deletes its submissions too, so export first.

Webhook

Add an endpoint on the Developers page and tick collect_data.submitted ("The agent collected a data form"). It fires once per saved submission, never for test chats:

{
  "id": "evt_...",
  "type": "collect_data.submitted",
  "createdAt": 1762950000000,
  "workspaceId": "...",
  "data": {
    "submissionId": "...",
    "collectionId": "...",
    "collectionName": "Refund request",
    "conversationId": "...",
    "contactId": "...",
    "visitor": {
      "name": "Dana Reyes",
      "email": "[email protected]",
      "externalId": null
    },
    "values": {
      "order_number": "PC-10442",
      "total": 129.5,
      "damaged": true,
      "order_date": "2026-11-02"
    },
    "submittedAt": 1762950000000
  }
}

values is keyed by field key; numbers and yes / no answers arrive as JSON numbers and booleans. contactId and visitor.email are null when no email address was known. Headers, signatures and retries are covered in Webhooks.

Limits

• 20 forms per workspace and 20 fields per form.
• Name 60 characters, "when" text 500, field label 60, hint 200, text answers 1,000.
• Data forms are available on every plan.

Common errors