> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Form Configuration

> Configure dynamic forms for tickets and user input collection

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                                   |

<Note>
  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.
</Note>

***

## Conditional Fields

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

<Info>
  Conditional fields help reduce form complexity by showing only relevant fields based on user choices.
</Info>

### 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**

```json theme={null}
{
  "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**

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

```json theme={null}
{
  "id": "invoice_number",
  "type": "text",
  "label": "Invoice Number",
  "conditional_field": "issue_type",
  "conditional_field_value": "billing"
}
```

### Multiple Conditions

For complex forms, chain conditional fields:

```mermaid theme={null}
flowchart TD
    A[Issue Type] --> B[Technical]
    A --> C[Billing]
    B --> D[Technical Details]
    D --> E[Browser Version]
    C --> F[Invoice Number]
    F --> G[Dispute Reason]
```

***

## Hidden Fields

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

<Warning>
  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.
</Warning>

### Use Cases

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

### Configuration

```json theme={null}
{
  "id": "source_channel",
  "type": "hidden",
  "is_hidden": true,
  "default_value": "chat_widget"
}
```

### Setting Hidden Values Dynamically

Pass hidden field values via the widget API:

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

***

## Validation

<Note>
  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
</Note>

### 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:**

```json theme={null}
{
  "name": "Widget Support Form",
  "tags": "from-widget,chat-originated,needs-review"
}
```

**Brand Assignment:**

```json theme={null}
{
  "name": "Product A Support",
  "brand_id": "123456789"
}
```

**Group Assignment:**

```json theme={null}
{
  "name": "Billing Questions",
  "external_id": "987654321"
}
```

### Complete Ticket Form Example

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<AccordionGroup>
  <Accordion title="Issue: Conditional field not appearing">
    **Problem:** Field doesn't show when parent value is selected.

    **Solutions:**

    1. Verify `conditional_field` matches the parent field's `id` exactly
    2. Check `conditional_field_value` matches an option value (not label)
    3. Ensure parent field is rendered before conditional field
    4. Check browser console for JavaScript errors
  </Accordion>

  <Accordion title="Issue: Validation not triggering">
    **Problem:** Invalid input is accepted.

    **Solutions:**

    1. Confirm validation rules are properly formatted
    2. Check if field is hidden (hidden fields skip validation)
    3. Verify conditional field is visible (hidden conditionals skip validation)
    4. Test regex patterns separately before adding to config
  </Accordion>

  <Accordion title="Issue: Hidden field value not submitted">
    **Problem:** Hidden field data missing from submission.

    **Solutions:**

    1. Verify field has `is_hidden: true` set
    2. Check field is included in form configuration
    3. Ensure `default_value` is set or value passed via widget API
    4. Inspect form submission in browser network tab
  </Accordion>

  <Accordion title="Issue: Form not rendering">
    **Problem:** Form doesn't appear in widget.

    **Solutions:**

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

    ***
  </Accordion>
</AccordionGroup>

## Related Documentation

* [Ticketing System](../features/ticketing) - Complete ticketing documentation
* [Widget Configuration](../features/widget-configuration-admin) - Widget embedding options
* [Ticketing API](./ticketing-api) - Ticket creation API reference