Custom Forms

A Custom form is an AI action that shows a form inside the chat. When the conversation needs structured answers, such as a booking request, a return, a quote or a support ticket, the chatbot calls the action, the form appears under its reply, and the visitor fills it in. The answers come back as a visitor message, so the chatbot reads them and replies straight away. Every submission can also be sent to your own server.

Create a custom form

Open Settings → AI Actions (https://www.chat-data.com/chatbot/{chatbotId}/settings/actions) and choose the Custom form card. You can also add one from the actions panel of an AI Conversation or AI Agent node in a workflow.

1. Details. The name is how the chatbot refers to the form (letters, numbers and _, like quote_request). The description tells the chatbot when to show it, for example "Show this when the visitor asks for a quote."

2. Form. Choose where the form comes from:

   • No-code builder: add the fields in the dashboard, no code.
   • Write code: JavaScript that returns the form, loaded onto your website.
   • On my website: your developer adds the form to your pages with the SDK.

   Forms returned by code also get Inputs (the parameters the chatbot fills in), and Write code a Test step.

3. On submit. Turn on Require an answer if the visitor must submit before chatting on. Otherwise the visitor can close the form. Optionally, turn on Send submissions and set the webhook URL that receives each one.

4. Save and enable the action.

Fields

Each field has a name, a type and a label. These types are available:

A field can also have a placeholder, a default value, and be read-only (disabled, showing its default value). Validation rules each take a value and an optional message:

• required
• minLength, maxLength for text
• min, max for numbers
• pattern, a regular expression

If a rule has no message, the field shows its default error message, or a generic one. Text answers are limited to 5,000 characters.

pattern is checked in the visitor's browser only, to guide them while typing. A determined visitor can bypass it, so if a value must match a pattern (an order number, for example), check it again in your webhook handler.

The form itself has a submit button text, a show labels switch, a success message and an error message.

AI can fill this in

For a form built in the dashboard, turn on AI can fill this in for a field and the chatbot fills it in from the conversation. If the visitor said "my email is [email protected]", the form opens with the email already entered, and the visitor only checks and submits. A value the chatbot gets wrong (text in a number field, an option that doesn't exist) is left empty instead.

Forms returned by code

For Write code and On my website, a function returns the form. It receives the same three arguments as browser actions:

• args: the parameters you defined under Inputs, filled in by the chatbot;
• user: what you sent with sendUserInfo, or null;
• context: { chatbotId, conversationId, pageUrl }.

To register the form on your website, call window.chatbot.registerFormSchema with the action's name. window.chatbot comes from the Chat Data SDK, so load chatbotsdk.min.js on the page before this code runs. The chat bubble embed alone doesn't define it.

<script src="https://www.chat-data.com/static/chatbotsdk.min.js" data-chatbot-id="YOUR_CHATBOT_ID"></script>
<script>
  window.chatbot.registerFormSchema({
    quote_request: async (args, user) => ({
      fields: [
        {
          name: 'full_name',
          label: 'Full name',
          type: 'text',
          defaultValue: user?.name || '',
          validation: { required: { value: true, message: 'Please enter your name' } },
        },
        {
          name: 'email',
          label: 'Email',
          type: 'email',
          validation: { required: { value: true } },
        },
        {
          name: 'product',
          label: 'Product',
          type: 'select',
          options: [
            { value: 'starter', label: 'Starter kit' },
            { value: 'pro', label: 'Pro kit' },
          ],
        },
        { name: 'quantity', label: 'Quantity', type: 'number', defaultValue: args.quantity, validation: { min: { value: 1 } } },
      ],
      submitButtonText: 'Request quote',
      showLabels: true,
      successMessage: 'Thanks! We will email your quote shortly.',
    }),
  });
</script>

registerFormSchema can be called more than once: it adds forms, replaces a form with the same name, and removes one when you pass null. The chatbot offers a registered form only on pages that registered it.

The returned form is checked before it is shown. If it is invalid (a field without a type, two fields with the same name, a select without options), or the function throws or takes longer than 30 seconds, no form appears and the chatbot tells the visitor it couldn't open the form. For Write code, use the Test step in the editor to see the form your code returns, or the problem with it.

The code is public: it runs in your visitors' browsers. Never put secrets in it.

What the visitor sees

• The form opens under the chatbot's reply, with validation as they type.
• A skippable form has a close button. A form with Require an answer stops the visitor sending other messages until they submit.
• Each form can be submitted once, and then becomes a read-only summary of the answers.
• A form that isn't submitted within 24 hours expires. The visitor can ask again to get a new one.

The webhook

When a webhook URL is set, every accepted submission is sent as a POST with the event {action name}_custom_form.submit:

{
  "event": "quote_request_custom_form.submit",
  "chatbot_id": "6582e8e9f5b3a1c2d4e5f6a7",
  "chatbot_name": "Support bot",
  "chatbot_display_name": "Support",
  "payload": {
    "conversationId": "c2a1f0de-8b5a-4c3e-9f1d-7e6b5a4c3d2e",
    "data": { "full_name": "Jane Doe", "email": "[email protected]", "product": "pro", "quantity": 3 },
    "error": null
  }
}

data holds the answers keyed by field name, with numbers as numbers. The request is signed with the action's signing secret, shown in the editor after the first save: verify the x-chat-data-hmac-sha256 header as described in Webhooks Setup. Failed deliveries appear in Webhook Events; a failing endpoint never affects the visitor, who still sees the success message.

Where custom forms work

• The chat bubble and the iframe, in standard chat, AI Agent mode, and the AI Conversation and AI Agent workflow nodes.
• Forms built in the dashboard also work in the Playground.
• Forms returned by code work only on your website.
• Custom forms are not offered over the API, messaging channels or phone calls.

In a workflow, the node waits at the form, and later nodes (an email, an API call) run on the visitor's next message. That is usually their submission, but it can also be what they type after closing the form or after it expires, so don't assume later nodes always have the form's answers.

Forms don't approve other actions

A form collects answers from the visitor. It does not hold back other actions the chatbot calls in the same turn: in AI Agent mode, the chatbot could call a refund API at the same time as a "confirm refund" form, before the visitor answers. To act only after the visitor confirms, put the step after the form:

• a workflow node after the form's node, which waits for the submission;
• your webhook handler, which receives the submission;
• or a check in your own API that the request was confirmed.