Collect data and custom forms
FluentChat has two actions for gathering information from visitors. Collect data asks for the details in the conversation. Custom form shows a form in the chat that the visitor fills in and submits. Both send the answers to destinations you configure.
Open Bot > Actions > Action library, then select Collect data or Custom form.
Best for: lead capture, feedback, callback requests and support intake.
Common requests:
- “I’d like someone to call me back.”
- “Can I send my details?”
- “I want to leave feedback about the product I used.”
Choose Collect data or Custom form
| Collect data | Custom form | |
|---|---|---|
| How the visitor answers | In chat. The bot asks for each missing required answer. | In a form card with a Submit button. |
| Where fields come from | Fields you define in the dashboard. | Dashboard fields, or a Website-registered form (advanced) your website supplies. |
| Destinations | Webhooks or an email notification. At least one is required to enable it. | Webhooks. Optional: “Without a destination, submitted answers are validated and discarded.” |
| After the visitor answers | The bot continues the conversation without an automatic success message. | The form shows your Completion message after successful delivery. |
| Channels | Website channels | Website channels |
Website channels are Chat bubble, Help page and Center stage.
Before you start
- You need the Owner, Team Admin or Bot Admin role.
- For a webhook, you need a public HTTPS endpoint that accepts
POSTrequests with JSON. - For a Website-registered form (advanced), your website must load the chat with the JavaScript widget install code.
Set up Collect data
-
Open the template. In Action library, select Collect data, then Start customizing.
-
Complete General. Enter an Action name and review When to use. Select Continue.
-
Add fields. Under Data to collect, list the information the bot should collect from the visitor. Select Add data input for each field, then Continue.
-
Add a destination. Under Webhooks, enter an HTTPS URL and select Create webhook, or turn on Email notification and enter a Notification email. Select Save and continue.
-
Choose channels. Turn on the website channels that may use the action, then select Save, or Save & enable.
-
Enable the action. Turn on Enable action if you didn’t use Save & enable.
The action is saved when you select Save and continue in Destinations. Until then, the editor says “Your action is saved after its configuration is complete.”
Set up a custom form
-
Open the template. In Action library, select Custom form, then Start customizing.
-
Complete General. Enter an Action name and a When to use description, such as “Use this form to collect some information from the user. Example queries: Sign up, Register”. Select Save and continue.
-
Build the form. In Fields, choose a Form source, enter a Form title, and add fields. For Dashboard fields, also set the Completion message. Select Save and continue.
-
Add a webhook (optional). In Webhooks, enter an HTTPS URL and select Create webhook. Then select Save and continue, even if you add no webhook. Skip moves on without saving.
-
Choose channels. Turn on the website channels that may show the form, then select Save, or Save & enable.
-
Enable the action. Turn on Enable action if you didn’t use Save & enable.
Fields
For Collect data and custom forms with Dashboard fields, each field has these settings. Open Labels, choices and validation limits in Collect data to see all of them.
| Setting | What it does |
|---|---|
| Field key | The key your destination receives. Start with a letter; use letters, numbers and underscores; up to 40 characters. |
| Label | What the visitor sees, up to 80 characters. |
| Data type | Text, Email, Number, Yes or no or Choice. Custom forms also offer Date. |
| Required | The bot asks for it, or the form won’t submit without it. |
| Help text (optional) | Extra guidance, up to 300 characters. |
| Prefilled answer (optional) | A default value. It prefills a visible form; the bot never invents a value from it. |
| Choices, one per line | The options for a Choice field, up to 30. |
| Minimum characters / Maximum characters | Length limits for text, from 1 to 2,000. |
You can add up to 20 fields.
Destinations
Webhooks
Collect data and Custom form send each submission as a POST request with JSON to every webhook you add. You can add up to 3 webhooks per action. Each must be a unique public HTTPS URL without credentials or a fragment.
When you select Create webhook, the Webhook created dialog shows a Signing secret. Select Copy and store it on your server. “It will not be shown again.” Then select Done.
Email notification
Collect data only. Turn on Email notification (“Send an email for each submission.”) and enter a Notification email, such as team@example.com. Any single valid address works, including one outside your team.
Webhook requests
Each request includes these headers:
| Header | What it contains |
|---|---|
x-chatbase-signature | A lowercase hexadecimal HMAC-SHA1 of the exact raw request body, using the webhook’s signing secret. |
Idempotency-Key | A unique ID for this submission. Use it to ignore duplicates. |
A Collect data request body looks like this, where support_request is the action name:
{ "eventType": "support_request_collect_data.submit", "chatbotId": "YOUR_BOT_ID", "payload": { "conversationId": "…", "customFields": { "email": "user@example.com" } }}A Custom form request uses {action_name}_custom_form.submit and puts answers in data:
{ "eventType": "support_request_form_custom_form.submit", "chatbotId": "YOUR_BOT_ID", "payload": { "conversationId": "…", "data": { "email": "user@example.com" }, "error": null }}Verify the signature against the exact bytes you received, before parsing:
import crypto from "node:crypto";
function isValidSignature(rawBody, signature, secret) { const expected = crypto.createHmac("sha1", secret).update(rawBody).digest("hex"); return ( typeof signature === "string" && signature.length === expected.length && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected)) );}Respond with a 2xx status quickly. FluentChat waits up to 3 seconds, doesn’t follow redirects, and never resends a submission automatically.
Website-registered forms
With Form source set to Website-registered form (advanced), your website supplies the visitor-facing fields through widget.registerFormSchema(). The editor shows the name to register under: the action’s name. The inputs in Collect data inputs for action (optional) are arguments the AI passes when it opens the form.
Register the schema inside the .then() callback of your install code. The callback receives the AI’s arguments and returns the form:
window.FluentChat.mount({ botId: "YOUR_BOT_ID" }).then((widget) => { window.fluentChatWidget = widget; widget.registerFormSchema({ support_request_form: async (args) => ({ fields: [ { name: "email", label: "Email", type: "email", defaultValue: args.email, validation: { required: { value: true } }, }, { name: "topic", label: "Topic", type: "select", options: [ { value: "billing", label: "Billing" }, { value: "technical", label: "Technical" }, ], }, { name: "details", label: "Details", type: "textarea" }, ], submitButtonText: "Send", successMessage: "Thanks. We received your request.", }), });});| Schema property | What it does |
|---|---|
fields | 1–20 fields. Each needs a unique name (letter first, up to 40 characters) and a label (up to 80 characters). |
type | text, textarea, phone, email, number, boolean, date, select, multiselect, groupselect, groupmultiselect or image. |
options | Up to 30 { value, label } choices for select types. |
validation | Optional required, minLength, maxLength, min, max and pattern, each as { value }. |
placeholder, defaultValue, disabled, array | Optional presentation and value settings. |
submitButtonText, successMessage, showLabels | Optional form-level text and label display. |
Image fields accept JPEG, PNG, GIF and WebP files up to 2 MB each and 10 MB per submission. Webhooks receive image URLs.
A website schema controls presentation only. It can’t change destinations, which always come from the dashboard. See Widget SDK for the full widget API.
Submission outcomes
| Visitor sees | What it means |
|---|---|
Your Completion message or successMessage | Every destination accepted the submission. |
| ”Delivery has not been confirmed. Your answers will not be resent automatically.” | A destination didn’t respond in time or the result is unknown. The visitor can select Check delivery status. |
| ”Your answers could not be delivered. They have not been resent.” | Delivery failed. |
| ”Form dismissed.” | The visitor selected Dismiss. |
Channel compatibility
| Channel | Collect data | Custom form |
|---|---|---|
| Chat bubble | Yes | Yes |
| Help page | Yes | Yes |
| Center stage | Yes | Yes |
| API | No | No |
| Fluent Support | No | No |
Limitations
- Collect data needs a destination. You can’t enable it without a webhook or email notification.
- A custom form without a webhook discards answers. They are validated, then dropped.
- Collect data fields hold single values. Custom form fields can turn on Allow multiple values. Record tables aren’t supported in either action.
- One delivery attempt per submission. FluentChat doesn’t retry a failed or uncertain delivery.
- Website-registered forms need the JavaScript widget. If the page hasn’t registered the schema, the visitor sees “This form is not registered on this website.”
Troubleshooting
Configure a destination before enabling this action.
Possible cause: The Collect data action has no webhook and email notification is off.
Solution: Open Destinations, add a webhook or turn on Email notification, and select Save and continue.
Enter a unique public HTTPS URL without credentials or a fragment.
Possible cause: The URL uses http, contains a username, password or #, or is already in the list.
Solution: Enter a different public https URL.
Your webhook rejects requests as unsigned
Possible cause: The receiver checks a different secret, or computes the signature over parsed JSON instead of the raw body.
Solution: Use the Signing secret shown when you created that webhook, and sign the exact raw body. If you lost the secret, edit the webhook to issue a new one, then save the action.
This form could not be loaded. Please contact the website team.
Possible cause: The website-registered schema callback threw an error, returned an invalid schema, or didn’t return within 10 seconds.
Solution: Check the browser console and compare the schema with the table above.