Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ansa.so/llms.txt

Use this file to discover all available pages before exploring further.

Overview

Form tools display interactive forms within the chat widget to collect structured data from users. Use them for:
  • Lead capture
  • Contact forms
  • Support ticket creation
  • Surveys and feedback
  • User onboarding
Form in widget

Creating a Form Tool

{
  "name": "contact_form",
  "description": "Show this form when user wants to contact support, has an issue you cannot resolve, or requests human assistance.",
  "executionType": "form",
  "formSchema": {
    "fields": [
      {
        "name": "email",
        "label": "Email",
        "type": "email",
        "placeholder": "you@example.com",
        "validation": {
          "required": { "value": true, "message": "Email is required" }
        }
      },
      {
        "name": "message",
        "label": "Message",
        "type": "textarea",
        "placeholder": "How can we help?"
      }
    ],
    "submitLabel": "Send Message",
    "successMessage": "Thanks! We'll get back to you soon.",
    "errorMessage": "Something went wrong. Please try again."
  }
}

Field Types

Ansa supports 11 field types:

Text Input

Single-line text entry.
{
  "name": "name",
  "label": "Full Name",
  "type": "text",
  "placeholder": "John Smith"
}

Email

Email input with format validation.
{
  "name": "email",
  "label": "Email Address",
  "type": "email",
  "placeholder": "you@company.com"
}

Phone (Tel)

Phone number input.
{
  "name": "phone",
  "label": "Phone Number",
  "type": "tel",
  "placeholder": "+1 (555) 123-4567"
}

Number

Numeric input with optional min/max.
{
  "name": "quantity",
  "label": "Quantity",
  "type": "number",
  "validation": {
    "min": { "value": 1, "message": "Minimum is 1" },
    "max": { "value": 100, "message": "Maximum is 100" }
  }
}

Textarea

Multi-line text input.
{
  "name": "description",
  "label": "Description",
  "type": "textarea",
  "placeholder": "Tell us more..."
}

Select (Dropdown)

Single selection from options.
{
  "name": "department",
  "label": "Department",
  "type": "select",
  "options": [
    { "label": "Sales", "value": "sales" },
    { "label": "Support", "value": "support" },
    { "label": "Billing", "value": "billing" }
  ]
}

Multi-Select

Multiple selections from options.
{
  "name": "interests",
  "label": "Interests",
  "type": "multiselect",
  "options": [
    { "label": "Product Updates", "value": "updates" },
    { "label": "Tips & Tutorials", "value": "tips" },
    { "label": "Case Studies", "value": "cases" }
  ]
}

Date

Date picker.
{
  "name": "preferred_date",
  "label": "Preferred Date",
  "type": "date",
  "validation": {
    "min": { "value": "2024-01-01", "message": "Date must be in 2024 or later" }
  }
}

DateTime

Date and time picker.
{
  "name": "appointment",
  "label": "Appointment Time",
  "type": "datetime"
}

File Upload

File upload (max 5MB, base64 encoded).
{
  "name": "attachment",
  "label": "Attachment",
  "type": "file"
}

Image Upload

Image upload (max 5MB, base64 encoded).
{
  "name": "screenshot",
  "label": "Screenshot",
  "type": "image"
}

Field Properties

Every field supports these properties:
PropertyTypeDescription
namestringField identifier (required)
labelstringDisplay label (required)
typestringField type (required)
placeholderstringPlaceholder text
defaultValuestringPre-filled value
disabledbooleanMake field read-only
validationobjectValidation rules
optionsarrayFor select/multiselect only

Validation

Add validation rules with custom error messages:

Required

{
  "validation": {
    "required": {
      "value": true,
      "message": "This field is required"
    }
  }
}

Min/Max Length (Text)

{
  "validation": {
    "minLength": {
      "value": 10,
      "message": "Please enter at least 10 characters"
    },
    "maxLength": {
      "value": 500,
      "message": "Maximum 500 characters"
    }
  }
}

Min/Max Value (Numbers/Dates)

{
  "validation": {
    "min": {
      "value": 1,
      "message": "Must be at least 1"
    },
    "max": {
      "value": 100,
      "message": "Cannot exceed 100"
    }
  }
}

Pattern (Regex)

{
  "validation": {
    "pattern": {
      "value": "^[A-Z]{2}[0-9]{6}$",
      "message": "Please enter a valid order number (e.g., AB123456)"
    }
  }
}

Combined Validation

{
  "name": "email",
  "type": "email",
  "validation": {
    "required": { "value": true, "message": "Email is required" },
    "pattern": {
      "value": "^[^@]+@[^@]+\\.[^@]+$",
      "message": "Please enter a valid email"
    }
  }
}

Default Values

Static Defaults

{
  "name": "country",
  "type": "select",
  "defaultValue": "us"
}

Template Defaults

Use user data to pre-fill fields:
{
  "name": "email",
  "type": "email",
  "defaultValue": "{{user.email}}"
}
Available template variables:
  • {{user.email}} — Identified user’s email
  • {{user.name}} — Identified user’s name
  • {{user.userId}} — User ID
  • {{user.metadata.field}} — Any custom metadata field
  • {{context.previousResult.field}} — Data from previous tool result

Form Schema

The complete form structure:
{
  "formSchema": {
    "fields": [...],
    "submitLabel": "Submit",
    "successMessage": "Form submitted successfully!",
    "errorMessage": "Something went wrong. Please try again."
  }
}
PropertyDefaultDescription
fieldsrequiredArray of field definitions
submitLabel”Submit”Button text
successMessage”Submitted”Shown after success
errorMessage”Error”Shown on failure

Execution Modes

Control how form submissions are handled:
ModeDescription
webhookData sent to server/webhook only
clientHandled by client-side JavaScript only
bothSent to webhook AND processed by client
{
  "formExecutionMode": "webhook"
}
See Triggering Forms in Code for client-side handling.

Complete Example

A comprehensive lead capture form:
{
  "name": "lead_capture",
  "description": "Capture lead information when visitor expresses interest in a demo, pricing, or wants to be contacted.",
  "executionType": "form",
  "formSchema": {
    "fields": [
      {
        "name": "firstName",
        "label": "First Name",
        "type": "text",
        "placeholder": "Jane",
        "validation": {
          "required": { "value": true, "message": "First name is required" }
        }
      },
      {
        "name": "lastName",
        "label": "Last Name",
        "type": "text",
        "placeholder": "Smith"
      },
      {
        "name": "email",
        "label": "Work Email",
        "type": "email",
        "placeholder": "jane@company.com",
        "defaultValue": "{{user.email}}",
        "validation": {
          "required": { "value": true, "message": "Email is required" }
        }
      },
      {
        "name": "phone",
        "label": "Phone",
        "type": "tel",
        "placeholder": "+1 (555) 123-4567"
      },
      {
        "name": "company",
        "label": "Company",
        "type": "text",
        "placeholder": "Acme Inc"
      },
      {
        "name": "companySize",
        "label": "Company Size",
        "type": "select",
        "options": [
          { "label": "1-10 employees", "value": "1-10" },
          { "label": "11-50 employees", "value": "11-50" },
          { "label": "51-200 employees", "value": "51-200" },
          { "label": "201-500 employees", "value": "201-500" },
          { "label": "500+ employees", "value": "500+" }
        ]
      },
      {
        "name": "interest",
        "label": "What are you interested in?",
        "type": "multiselect",
        "options": [
          { "label": "Product Demo", "value": "demo" },
          { "label": "Pricing", "value": "pricing" },
          { "label": "Technical Questions", "value": "technical" },
          { "label": "Integration Help", "value": "integration" }
        ]
      },
      {
        "name": "message",
        "label": "Anything else?",
        "type": "textarea",
        "placeholder": "Tell us about your use case..."
      }
    ],
    "submitLabel": "Request Demo",
    "successMessage": "Thanks! Our team will reach out within 24 hours."
  },
  "formPostActions": [
    {
      "type": "webhook",
      "url": "https://hooks.zapier.com/hooks/catch/123/abc"
    },
    {
      "type": "slack",
      "webhookUrl": "https://hooks.slack.com/services/...",
      "messageTemplate": "🎯 *New Lead*\n\n*Name:* {{firstName}} {{lastName}}\n*Email:* {{email}}\n*Company:* {{company}} ({{companySize}})\n*Interest:* {{interest}}"
    }
  ]
}

See Also