Client-Side Custom Forms

Overview

Custom forms can only run be configured on the client side. Server-side configuration is not yet available. This approach allows for greater flexibility and control over the form’s behavior and appearance. By leveraging client-side configuration, developers can create dynamic and interactive forms enhancing the user experience.

How to Set Up Client-Side Custom Forms

Embed the Chatbot using the new Script:

To ensure that you can register client-side custom forms, you need to embed the Chatbase script correctly. Follow these steps to get the embed code:

Visit the Chatbase Dashboard.
Navigate to Connect > Embed > Embed code with identity.
Copy the embed code and add it to your application.

Note: If you don’t need to verify the identity of logged-in users, you can skip the first script in the embed code and only use the chatbot embed script.

Here’s an example of the embed code you’ll find on the dashboard:

Create the Client-Side Custom Form:

To create a client-side custom form:

Visit the Chatbase Dashboard
Navigate to Actions > Create action > Custom form.
Fill in the required fields, ensuring the form type is set to client-side.

Use the SDK registerFormSchema method: Load the Chatbase script and call the registerFormSchema method with all the form fields. The form names must match those written in the custom form page.

Method Parameters

Each custom form method receives two parameters:

args: Contains all the arguments defined in your custom form configuration
user: Contains the authenticated user information if identity verification is properly configured

Complete Example

Here’s a complete example showing how to register a custom form schema. Important: The function name in your code (e.g., userProfileForm) must exactly match the name you give to your AI Action in the Chatbase dashboard.

window.chatbase.registerFormSchema({
  userProfileForm: async (args, user) => {
    // args contains parameters defined in your custom form
    // user contains authenticated user data if identity verification is set up
      return {
        fields: [
          {
            name: "name",
            label: "First Name",
            type: "text",
            defaultValue: args.name,
            validation: {
              required: {
                value: true,
                message: "Name is required"
              },
              minLength: {
                value: 3,
                message: "Please enter at least 3 characters"
              },
              maxLength: {
                value: 10,
                message: "Please enter less than 10 characters"
              }
            }
          },
          {
            name: "age",
            label: "Age",
            type: "number",
            validation: {
              required: {
                value: true,
                message: "Age is required"
              },
              min: {
                value: 18
              },
              max: {
                value: 100
              },
              defaultErrorMessage: "Please enter a valid age"
            }
          },
          {
            name: "officeLocation",
            type: "groupselect",
            label: "Office Location",
            options: {
              "North America": [
                { value: "nyc", label: "New York City" },
                { value: "sf", label: "San Francisco" },
              ],
              "Europe": [
                { value: "london", label: "London" },
                { value: "berlin", label: "Berlin" },
              ]
            },
          },
          {
            name: "profileImage",
            label: "Click or drop your profile image here",
            type: "image",
          }
        ],
        submitButtonText: "Update Profile",
        successMessage: "Profile updated successfully!",
        errorMessage: "Failed to update profile"
      }
  }
});

Method Return Schema

The registerFormSchema function returns a schema that defines the structure and validation of the custom form. Below is a table detailing each field in the return schema:

Field Name	Explanation	Requirements
`fields`	An array of form field definitions, each specifying the field’s properties.	Must be an array of objects conforming to `Field Schema` defined below.
`submitButtonText`	Optional text for the submit button. Default text is “Submit”.	Must be a string if provided.
`showLabels`	Whether to show the labels for the form fields. Default is false.	Must be a boolean, optional.
`successMessage`	Optional message displayed upon successful form submission. Default message is “Form submitted successfully”.	Must be a string if provided.
`errorMessage`	Optional message displayed if form submission fails. Default message is “Error submitting form”.	Must be a string if provided.

Field Schema

Each field in the fields array must adhere to the following structure:

Field Property	Explanation	Requirements
`name`	The unique identifier for the form field.	Must be a string.
`type`	The type of the form field.	Must be one of the available `Field Types` defined below.
`label`	The display label for the form field.	Must be a string.
`placeholder`	The placeholder text for the form field. If not provided, the label will be used as placeholder.	Must be a string, optional.
`defaultValue`	The default value for the form field.	Can be any type, optional.
`disabled`	Whether the field is disabled.	Must be a boolean, optional.
`validation`	An object defining validation rules for the field.	Must be a strict object with optional properties for each validation rule following the `Validation Rules` defined below.
`options`	Available options for selection fields.	For `select` and `multiselect`: Must be an array of objects with `label` and `value` properties. For `groupselect` and `groupmultiselect`: Must be an object where each key is a group name and its value is an array of objects with `label` and `value` properties.

Field Types

Field Type	Explanation	Requirements
`text`	A single-line text input.	Validation rules can include `required`, `minLength`, `maxLength`, `pattern`.
`textarea`	A multi-line text input.	Validation rules can include `required`, `minLength`, `maxLength`.
`email`	An input for email addresses.	Validation rules can include `required`, `pattern`.
`phone`	An input for phone numbers.	Must follow the format `/^\+[1-9]\d{1,14}$/` (a valid phone number starting with + and country code (e.g., +1234567890)). Validation rules can include `required`, `pattern`.
`number`	An input for numeric values.	Validation rules can include `required`, `min`, `max`.
`select`	A dropdown selection input.	Must include `options` array. Validation rules can include `required`.
`multiselect`	An input allowing multiple selections.	Must include `options` array. Validation rules can include `required`.
`groupselect`	A dropdown selection input with grouped options.	Must include `options` object where each key is a group name and its value is an array of options. Each option must have `label` and `value` properties. Validation rules can include `required`.
`groupmultiselect`	A dropdown selection input with grouped options allowing multiple selections from grouped options.	Must include `options` object where each key is a group name and its value is an array of options. Each option must have `label` and `value` properties. Validation rules can include `required`.
`image`	An input for image file uploads.	Accepts only `'image/jpeg', 'image/jpg', 'image/png', 'image/gif', 'image/webp'` and has a maximum size of 2MB. Validation rules can include `required`.

Validation Rules

The validation object can include different validation rules. Each rule is an object with a value and message property. The message property indicates the error message to be displayed if the validation rule is violated. There is also a default error message field that will be displayed if the validation rule is violated and no custom message is provided. The following rules are available:

Validation Rule	Explanation	Requirements
`required`	Specifies if the field is mandatory.	Must be an object with `value` (boolean) and `message` (string).
`pattern`	A regex pattern the field value must match.	Must be an object with `value` (string) and `message` (string).
`min`	Minimum numeric value allowed for the field.	Must be an object with `value` (number) and `message` (string).
`max`	Maximum numeric value allowed for the field.	Must be an object with `value` (number) and `message` (string).
`minLength`	Minimum length of the field value.	Must be an object with `value` (number) and `message` (string).
`maxLength`	Maximum length of the field value.	Must be an object with `value` (number) and `message` (string).
`defaultErrorMessage`	Default error message if validation fails.	Must be a string, optional.

Webhooks

You can configure webhooks for form submission events in the custom form action tab or in the Settings > Webhooks section. Learn more about webhooks.

Important Notes

Multiple Registrations: Calling registerFormSchema multiple times will override previous forms. Make sure to provide all desired forms in a single registerFormSchema call. Environment Limitations: Client-side custom forms will not work in the Chatbase Playground, Action Preview, or Compare features, as these environments don’t support client-side code execution.

Javascript SDK

Help Page

API

Client-Side Custom Forms

Overview

How to Set Up Client-Side Custom Forms

Method Parameters

Complete Example

Method Return Schema

Field Schema

Field Types

Validation Rules

Webhooks

Important Notes

Javascript SDK

Help Page

API

​Overview

​How to Set Up Client-Side Custom Forms

​Method Parameters

​Complete Example

​Method Return Schema

​Field Schema

​Field Types

​Validation Rules

​Webhooks

​Important Notes

Overview

How to Set Up Client-Side Custom Forms

Method Parameters

Complete Example

Method Return Schema

Field Schema

Field Types

Validation Rules

Webhooks

Important Notes