Pre-chat form and topics

By default the widget asks for nothing: the visitor writes straight into the chat, and the contact is saved under a placeholder name instead of a real one. That’s the right choice for most sites: the fewer steps before the first message, the more people send one.

A pre-chat form makes sense when:

• Your support is offline more often than online, and you need an email address to reply later.
• Conversations go to a CRM, and a contact card without a name and contact details is useless there.

SettingsWidget BuilderForms & Topics. Visitors see the changes after you click Publish.

• A bot asks for the required fields in order (name, email, phone), one question at a time. An indicator under the input shows how many steps are left.
• Answers are checked: the name must be at least 2 characters, the email and phone must look valid. If an answer doesn’t fit, the bot asks again.
• After the last field, the widget saves the details to the contact and asks the visitor to describe their question. The visitor’s next message starts the conversation, and the bot’s questions and the answers are saved in the ticket.
• Quick-reply buttons, if you set them up, appear once the fields are collected.
• The bot’s questions are the widget’s built-in texts in its language (Russian or English). They aren’t in the builder; you can change them in SettingsTexts & broadcastsInterface Texts (the prechat.chat.* keys).

The visitor types their first message, and before it’s sent, a “Please introduce yourself” card appears with fields for the required details and a “Start chat” button. Once the visitor fills it in, the details are saved to the contact and the message goes out. The card’s text is the widget’s built-in text; pre_chat_message doesn’t change it.

Topics (forms.topics) are set up in the same builder section. With at least one topic, the widget asks what the question is about before the first message of a new conversation, like the Telegram bot’s topic menu:

• in the chat, after the name, email and phone (if they’re required), the bot offers the topics as buttons; the visitor can also type one. Then the bot asks the chosen topic’s questions one by one: a “Choice” field’s options are buttons, and an optional field has a “Skip” button;
• in the single form, the topics and the chosen topic’s fields appear in the same card, under the contact fields. The card isn’t sent without a topic and the required fields.

The topic and the answers go out with the first message. A ticket has no separate topic field: ticket.custom_fields gets topic_id, topic_name and the topic’s field values (fields), the same as the bot’s topics, so the operator sees the topic and the answers on the ticket. You can also send the first message with a topic yourself through the widget API (POST /api/webhooks/widget/{workspace_id} with a topic_id).

A topic has an id, a name and custom_fields. Up to 50 topics; id and name are 1 to 100 characters; up to 20 extra fields per topic. A topic field has an id, a label, a type (text, email, phone, number, ip or select), required, a placeholder hint, a regex check (matched from the start of the answer) with its own error_message and, for select, options shaped { value, label }: value is what’s sent and saved on the ticket, label is the caption (the value itself if it’s missing). Plain-string options from older configs are read as { value, label } with the same text. In the builder, a topic’s fields use the same editor as the bot’s topics; for number and ip it fills in a standard check.

The field values go in the same request, in custom_fields: [{ "id": …, "value": … }]. An empty required field, a select value that isn’t one of the options’ values and an answer that fails the regex are rejected with a 422 (required, invalid_option and format). The widget checks the answers the same way before sending.