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 submits form values to:

POST https://api.lane.chat/v1/forms/submit

Rate limit: 30 requests / 60 seconds.

Request

{
  "app_id": "app_1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d",
  "chat_id": 12345,
  "visitor_id": "<visitor_token or fingerprint>",
  "message_id": 67890,
  "form_id": "book_demo",
  "values": {
    "email": "[email protected]",
    "team_size": "11-50"
  }
}

• app_id and chat_id are required.
• Visitor identity comes from the JWT (sent by the widget) with visitor_id as a fallback.
• values must be a non-empty object. Up to 50 keys are kept; keys are capped at 100 characters and values at 2000 characters.

Response

{ "code": 0, "msg": "success", "data": { "message_id": 112233 } }

Code	Meaning
0	Recorded.
400	Missing app_id or chat_id.
401	Visitor could not be authenticated.
403	Visitor is banned.
404	Application or chat not found.
422	values was empty.

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.