Forms

A form rich message collects structured input from the visitor inline in the chat. When the visitor submits, the values are recorded in the conversation, written to the visitor profile where they match standard fields, and (optionally) resume a paused Flow.

Submitting a form

The widget handles submission itself — the visitor fills the form in chat and taps submit; there is nothing to wire up on your side. Submissions are authenticated as the visitor's own session and validated server-side: values must be a non-empty object, up to 50 keys are kept, keys are capped at 100 characters and values at 2000 characters.

What happens on submit

1. Recorded as a visitor message. The submission becomes a message in the conversation with a readable field: value body. AI auto-reply is skipped for submissions (structured data does not need an AI answer).
2. Written to the profile. Keys that match standard fields (email, phone) are validated and written to the visitor profile when the column is empty; conflicts are kept as an audit trail instead of overwriting. Other keys are stored under traits.form_data.
3. Resumes a waiting Flow. If the form was sent by a Flow that is paused waiting for this submission, the values are injected as form.* variables and the Flow resumes. If nothing is waiting, the message is simply recorded.

Authoring a form

Forms are authored in Flows via the send_rich_message action with type: "form". Each field has an id, a label, a type (text, email, select, ...), and an optional required flag. The form's submit_action can point at a flow_step_id (to resume the Flow) and/or a webhook_url. See Flows.

Field labels, placeholders, and the submit label all support per-language {lang: text} maps and {{variable}} interpolation — see Template variables.