Form Configuration - AGO Documentation

Configure dynamic forms for ticket creation, contact forms, and user input collection. AGO’s form system supports conditional fields, validation rules, and hidden values for flexible data collection.

Overview

Form configuration enables:

Dynamic field visibility based on user selections
Hidden fields for metadata and routing
Validation rules for data integrity
Custom field types for different input needs

Prerequisites

Admin access to configure forms
Understanding of your ticketing workflow
Field definitions for your use case

Field Types

Type	Description	Use Case
`text`	Single-line text input	Names, short answers
`textarea`	Multi-line text input	Descriptions, long answers
`integer`	Numeric input	Quantities, IDs
`regexp`	Text input with regex validation	Formatted inputs (emails, phone numbers, order IDs)
`checkbox`	Boolean toggle	Confirmations, opt-ins
`multiselect`	Multiple selections	Tags, multiple categories
`tagger`	Tag selection	Categorization, tagging
`subject`	Ticket subject field	Ticket subject line
`description`	Description field	Ticket body/description
`priority`	Priority selection	Ticket priority level
`status`	Status selection	Ticket status
`assignee`	Assignee selection	Ticket assignment

To create a field that behaves as hidden (not visible to users but included in submissions), set the is_hidden property to true on any field type.

Conditional Fields

Conditional fields display based on the value of another field. This creates dynamic forms that adapt to user selections.

Conditional fields help reduce form complexity by showing only relevant fields based on user choices.

Configuration Options

Option	Type	Description
`is_hidden`	boolean	Pass values without showing the field
`conditional_field`	string	Field ID this depends on
`conditional_field_value`	string	Value that triggers visibility

Example: Issue Type Routing

Create fields that appear based on issue type selection: Step 1: Create the parent field

{
  "id": "issue_type",
  "type": "select",
  "label": "Issue Type",
  "required": true,
  "options": [
    {"value": "technical", "label": "Technical Issue"},
    {"value": "billing", "label": "Billing Question"},
    {"value": "general", "label": "General Inquiry"}
  ]
}

Step 2: Create conditional child fields

{
  "id": "technical_details",
  "type": "textarea",
  "label": "Technical Details",
  "placeholder": "Describe the error message or behavior...",
  "conditional_field": "issue_type",
  "conditional_field_value": "technical"
}

{
  "id": "invoice_number",
  "type": "text",
  "label": "Invoice Number",
  "conditional_field": "issue_type",
  "conditional_field_value": "billing"
}

Multiple Conditions

For complex forms, chain conditional fields:

Hidden Fields

Hidden fields pass values to the ticketing system without displaying them to users.

Hidden field values can be inspected in browser developer tools. Do not use hidden fields for sensitive data that users shouldn’t see at all.

Use Cases

Use Case	Example Value
Source tracking	`source: "widget"`
Routing metadata	`department: "support"`
Context preservation	`page_url: "https://..."`
Auto-categorization	`priority: "normal"`

Configuration

{
  "id": "source_channel",
  "type": "hidden",
  "is_hidden": true,
  "default_value": "chat_widget"
}

Setting Hidden Values Dynamically

Pass hidden field values via the widget API:

AGO.init({
  agentId: 'your-agent-id',
  formData: {
    source_channel: 'main_website',
    user_segment: 'enterprise',
    page_context: window.location.pathname
  }
});

Validation

Validation behavior varies by field visibility:

Hidden fields: Not validated
Conditional fields: Validated only when visible
Required conditional fields: Error shown only when field is displayed

Available Validation Options

Option	Type	Description
`required`	boolean	Field must have a value
`regexp_for_validation`	string	Regex pattern the field value must match

Regex Validation

Use the regexp field type or set regexp_for_validation on any field to enforce a pattern:

{
  "id": "order_number",
  "type": "regexp",
  "label": "Order Number",
  "regexp_for_validation": "^ORD-[0-9]{6}$"
}

Ticket Form Settings

When configuring forms for ticketing, additional settings control behavior and integration with external systems.

Form-Level Properties

Property	Type	Description
`external_id`	string	Zendesk group ID for automatic assignment
`brand_id`	string	Zendesk brand ID for multi-brand accounts
`tags`	string	Static tags applied to all tickets (comma-separated)
`system_prompt`	string	Custom AI instructions for ticket prefilling
`success_message_text`	string	Custom message after ticket creation (supports markdown)
`success_message_url_label`	string	Label for optional action link
`provide_all_fields_in_comment`	boolean	Include all field values in private comment

Success Messages

Customize what users see after submitting a ticket:

{
  "name": "Support Form",
  "success_message_text": "Thank you! Your request has been received. Our team will respond within 24 hours.",
  "success_message_url_label": "View your tickets"
}

With Markdown:

{
  "success_message_text": "## Request Submitted\n\nYour ticket has been created. You can:\n- Check your email for updates\n- [View our FAQ](/help/faq) for quick answers"
}

AI Prefilling (System Prompt)

Configure how AI extracts ticket information from conversations:

{
  "name": "Technical Support Form",
  "system_prompt": "Extract the following from the conversation:\n- Subject: Brief summary (max 80 chars)\n- Body: Detailed description including error messages\n- Priority: urgent keywords = High, otherwise Normal\n- Category: Technical, Billing, or General"
}

Best Practices for System Prompts:

Be specific about field formats and lengths
Provide examples of expected output
Mention keywords that indicate priority levels
List available categories/options for select fields

Zendesk-Specific Settings

Static Tags:

{
  "name": "Widget Support Form",
  "tags": "from-widget,chat-originated,needs-review"
}

Brand Assignment:

{
  "name": "Product A Support",
  "brand_id": "123456789"
}

Group Assignment:

{
  "name": "Billing Questions",
  "external_id": "987654321"
}

Complete Ticket Form Example

{
  "name": "Enterprise Support Form",
  "external_id": "12345",
  "brand_id": "67890",
  "tags": "enterprise,priority-support",
  "system_prompt": "Extract subject and detailed description from conversation. Mark as High priority if user mentions urgent, critical, or blocking.",
  "success_message_text": "## Thank You!\n\nYour enterprise support ticket has been created. Our dedicated team will respond within 4 hours.\n\n**Ticket Reference:** Check your email for details.",
  "success_message_url_label": "Contact your Account Manager",
  "provide_all_fields_in_comment": true,
  "fields": [
    {
      "id": "subject",
      "type": "text",
      "label": "Subject",
      "required": true
    },
    {
      "id": "category",
      "type": "select",
      "label": "Category",
      "required": true,
      "options": [
        {"value": "technical", "label": "Technical Issue"},
        {"value": "integration", "label": "Integration Support"},
        {"value": "account", "label": "Account Management"}
      ]
    },
    {
      "id": "description",
      "type": "textarea",
      "label": "Description",
      "required": true
    }
  ]
}

Complete Form Example

Here’s a comprehensive form configuration with conditional fields and validation:

{
  "name": "Customer Support Form",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "label": "Your Name",
      "required": true,
      "placeholder": "John Doe"
    },
    {
      "id": "email",
      "type": "email",
      "label": "Email Address",
      "required": true,
      "placeholder": "john@example.com"
    },
    {
      "id": "issue_type",
      "type": "select",
      "label": "What can we help you with?",
      "required": true,
      "options": [
        {"value": "technical", "label": "Technical Support"},
        {"value": "billing", "label": "Billing & Payments"},
        {"value": "account", "label": "Account Management"},
        {"value": "other", "label": "Other"}
      ]
    },
    {
      "id": "error_message",
      "type": "textarea",
      "label": "Error Message",
      "placeholder": "Paste the error message here...",
      "conditional_field": "issue_type",
      "conditional_field_value": "technical"
    },
    {
      "id": "invoice_number",
      "type": "text",
      "label": "Invoice Number",
      "validation": {
        "pattern": "^INV-[0-9]+$",
        "message": "Please enter a valid invoice number (INV-12345)"
      },
      "conditional_field": "issue_type",
      "conditional_field_value": "billing"
    },
    {
      "id": "description",
      "type": "textarea",
      "label": "Please describe your issue",
      "required": true,
      "min_length": 20,
      "placeholder": "Provide as much detail as possible..."
    },
    {
      "id": "priority",
      "type": "hidden",
      "is_hidden": true,
      "default_value": "normal"
    },
    {
      "id": "source",
      "type": "hidden",
      "is_hidden": true,
      "default_value": "web_form"
    }
  ]
}

Best Practices

Form Design

Keep forms short: Only ask for essential information
Use conditional fields: Hide complexity until needed
Provide helpful placeholders: Guide users on expected input
Order logically: Most important fields first

Validation

Validate on blur: Give immediate feedback
Use clear error messages: Explain what’s wrong and how to fix it
Don’t over-validate: Accept reasonable variations

Hidden Fields

Document hidden fields: Track what metadata is being captured
Don’t rely on hidden fields for security: They’re visible in source
Use for routing and context: Perfect for ticket categorization

Troubleshooting

Issue: Conditional field not appearing

Problem: Field doesn’t show when parent value is selected.Solutions:

Verify conditional_field matches the parent field’s id exactly
Check conditional_field_value matches an option value (not label)
Ensure parent field is rendered before conditional field
Check browser console for JavaScript errors

Issue: Validation not triggering

Problem: Invalid input is accepted.Solutions:

Confirm validation rules are properly formatted
Check if field is hidden (hidden fields skip validation)
Verify conditional field is visible (hidden conditionals skip validation)
Test regex patterns separately before adding to config

Issue: Hidden field value not submitted

Problem: Hidden field data missing from submission.Solutions:

Verify field has is_hidden: true set
Check field is included in form configuration
Ensure default_value is set or value passed via widget API
Inspect form submission in browser network tab

Issue: Form not rendering

Problem: Form doesn’t appear in widget.Solutions:

Verify form is associated with the correct agent
Check form configuration for JSON syntax errors
Ensure all required field properties are present
Review browser console for rendering errors

Ticketing System - Complete ticketing documentation
Widget Configuration - Widget embedding options
Ticketing API - Ticket creation API reference

​Overview

​Prerequisites

​Field Types

​Conditional Fields

​Configuration Options

​Example: Issue Type Routing

​Multiple Conditions

​Hidden Fields

​Use Cases

​Configuration

​Setting Hidden Values Dynamically

​Validation

​Available Validation Options

​Regex Validation

​Ticket Form Settings

​Form-Level Properties

​Success Messages

​AI Prefilling (System Prompt)

​Zendesk-Specific Settings

​Complete Ticket Form Example

​Complete Form Example

​Best Practices

​Form Design

​Validation

​Hidden Fields

​Troubleshooting

​Related Documentation

Overview

Prerequisites

Field Types

Conditional Fields

Configuration Options

Example: Issue Type Routing

Multiple Conditions

Hidden Fields

Use Cases

Configuration

Setting Hidden Values Dynamically

Validation

Available Validation Options

Regex Validation

Ticket Form Settings

Form-Level Properties

Success Messages

AI Prefilling (System Prompt)

Zendesk-Specific Settings

Complete Ticket Form Example

Complete Form Example

Best Practices

Form Design

Validation

Hidden Fields

Troubleshooting

Related Documentation