Pre-Chat Forms

The pre-chat form collects visitor information before a conversation begins. When enabled in the bot configuration, the form is displayed in place of the chat window until the visitor completes and submits it. The submitted data is attached to the conversation as visitor info and is available to the bot flow and live agents.

Configuration

The pre-chat form is configured per-bot in the Operations Portal. The configuration is delivered to the widget at runtime as part of the bot's widget config.

interface PreChatConfig {
  enabled: boolean;
  title?: string;
  description?: string;
  fields: PreChatFormField[];
  submit_button_text?: string;
}

Property	Type	Default	Description
enabled	boolean	false	Whether to show the pre-chat form
title	string	undefined	Heading displayed at the top of the form
description	string	undefined	Descriptive text below the title
fields	PreChatFormField[]	[]	Array of form fields to display
submit_button_text	string	'Start Chat'	Label for the submit button

Field Types

Each field in the form is defined by a PreChatFormField object:

interface PreChatFormField {
  name: string;
  label: string;
  type: 'text' | 'email' | 'phone' | 'select' | 'textarea';
  required?: boolean;
  placeholder?: string;
  options?: string[];  // For select type only
}

Type	HTML Element	Description
text	<input type="text">	General-purpose single-line text input
email	<input type="email">	Email address input with format validation
phone	<input type="tel">	Phone number input with format validation
select	<select>	Dropdown with predefined options array
textarea	<textarea>	Multi-line text input (3 rows)

Required Fields

When a field has required: true, a red asterisk (*) appears next to the label. Screen readers announce the field as required via aria-required="true". The submit button remains disabled until all required fields are filled.

Validation

The widget performs client-side validation when a field loses focus (on blur) and again on form submission.

Field Type	Validation Rule	Error Message
Any required field	Value must not be empty after trimming	"{Label} is required"
email	Must match pattern [^\s@]+@[^\s@]+\.[^\s@]+	"Please enter a valid email address"
phone	Must contain 7 or more characters matching [\d\s\-+()]	"Please enter a valid phone number"

Error Display

• Error messages appear directly below the field that failed validation
• Each error is wrapped in a role="alert" element so screen readers announce it immediately
• The field border turns red to provide a visual indicator
• On form submission with errors, a summary is announced to screen readers and focus moves to the first invalid field

imagePre-chat form displayed in the widget with text input for Full Name, email input for Email Address, phone input for Phone Number, a Department dropdown, and a textarea for the message

Pre-chat form with multiple field types

How It Works

1. The widget connects to the backend in config-only mode to receive the bot configuration, including theme and pre-chat settings
2. If pre_chat.enabled is true, the form is displayed instead of the chat interface
3. The visitor fills in the fields and clicks the submit button
4. Client-side validation runs; if errors exist, they are displayed and the form is not submitted
5. On successful validation, the form data is stored as VisitorInfo and the widget transitions to the chat interface
6. The visitor info is attached as metadata to the first message sent to the backend
7. The bot flow and live agents can read the visitor info throughout the conversation

Data Availability

Submitted pre-chat data is available as visitor_info in the message metadata. Bot flows can reference these values in conditions and actions. Live agents see the data in the Agent Desktop's visitor information panel.

Example Configuration

{
  "enabled": true,
  "title": "Welcome! Let's get started.",
  "description": "Please provide your details so we can assist you better.",
  "fields": [
    {
      "name": "name",
      "label": "Full Name",
      "type": "text",
      "required": true,
      "placeholder": "John Doe"
    },
    {
      "name": "email",
      "label": "Email Address",
      "type": "email",
      "required": true,
      "placeholder": "john@example.com"
    },
    {
      "name": "phone",
      "label": "Phone Number",
      "type": "phone",
      "required": false,
      "placeholder": "+1 (555) 123-4567"
    },
    {
      "name": "department",
      "label": "Department",
      "type": "select",
      "required": true,
      "options": ["Sales", "Support", "Billing", "Other"]
    },
    {
      "name": "message",
      "label": "How can we help?",
      "type": "textarea",
      "required": false,
      "placeholder": "Describe your question or issue..."
    }
  ],
  "submit_button_text": "Start Chat"
}

imagePre-chat form showing validation errors: red border on empty required Name field with 'Full Name is required' message, and red border on invalid email field with 'Please enter a valid email address' message

Form validation error display

Accessibility

The pre-chat form is built with accessibility as a priority:

• Labels linked to inputs -- Every field has a <label> element with a for attribute pointing to the input's id, ensuring screen readers announce the label when the field is focused
• Required field announcement -- Required fields include a visually hidden (required) text in addition to the visible asterisk, so screen readers announce the requirement
• Error announcement -- When validation fails on submission, a live region announces the total number of errors and their descriptions. Each field error is also wrapped in role="alert" for immediate announcement
• Focus management -- On validation failure, focus moves to the first field with an error
• Keyboard navigation -- All form elements are accessible via Tab and Shift+Tab. The submit button can be activated with Enter or Space
• Focus indicators -- All inputs and the submit button display a visible 2px outline when focused via keyboard (focus-visible)
• High contrast support -- In high contrast mode, input borders are thicker and error messages use bold text
• Reduced motion -- The submit button spinner and hover transitions are disabled when the user prefers reduced motion

iOS Zoom Prevention

On mobile devices (< 480px), input font sizes are set to 16px to prevent iOS Safari from zooming into the form when a field is focused.