Skip to content
This site is under construction. Content, screenshots, and workflows may change at any time.

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 dataCustom form
How the visitor answersIn chat. The bot asks for each missing required answer.In a form card with a Submit button.
Where fields come fromFields you define in the dashboard.Dashboard fields, or a Website-registered form (advanced) your website supplies.
DestinationsWebhooks 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 answersThe bot continues the conversation without an automatic success message.The form shows your Completion message after successful delivery.
ChannelsWebsite channelsWebsite 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 POST requests with JSON.
  • For a Website-registered form (advanced), your website must load the chat with the JavaScript widget install code.

Set up Collect data

  1. Open the template. In Action library, select Collect data, then Start customizing.

  2. Complete General. Enter an Action name and review When to use. Select Continue.

  3. 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.

  4. 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.

  5. Choose channels. Turn on the website channels that may use the action, then select Save, or Save & enable.

  6. 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

  1. Open the template. In Action library, select Custom form, then Start customizing.

  2. 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.

  3. 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.

  4. 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.

  5. Choose channels. Turn on the website channels that may show the form, then select Save, or Save & enable.

  6. 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.

SettingWhat it does
Field keyThe key your destination receives. Start with a letter; use letters, numbers and underscores; up to 40 characters.
LabelWhat the visitor sees, up to 80 characters.
Data typeText, Email, Number, Yes or no or Choice. Custom forms also offer Date.
RequiredThe 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 lineThe options for a Choice field, up to 30.
Minimum characters / Maximum charactersLength 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:

HeaderWhat it contains
x-chatbase-signatureA lowercase hexadecimal HMAC-SHA1 of the exact raw request body, using the webhook’s signing secret.
Idempotency-KeyA 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 propertyWhat it does
fields1–20 fields. Each needs a unique name (letter first, up to 40 characters) and a label (up to 80 characters).
typetext, textarea, phone, email, number, boolean, date, select, multiselect, groupselect, groupmultiselect or image.
optionsUp to 30 { value, label } choices for select types.
validationOptional required, minLength, maxLength, min, max and pattern, each as { value }.
placeholder, defaultValue, disabled, arrayOptional presentation and value settings.
submitButtonText, successMessage, showLabelsOptional 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 seesWhat it means
Your Completion message or successMessageEvery 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

ChannelCollect dataCustom form
Chat bubbleYesYes
Help pageYesYes
Center stageYesYes
APINoNo
Fluent SupportNoNo

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.

Next steps