> ## 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.
# Ticket Form Customization
> Customize ticket forms to collect the right information from users
Customize ticket creation forms to collect the right information from users. This reference covers form properties, field types, conditional logic, external system integration, and AI prefilling.
## Overview
Ticket forms control:
* What information users provide when creating tickets
* How fields are displayed and validated
* Integration with external ticketing systems (Zendesk, HelpScout)
* Embedding external forms (HubSpot, Typeform, etc.) directly in the chat
* AI-powered ticket prefilling
* Post-submission user experience
***
## Creating Ticket Forms
### Basic Setup
1. Navigate to **Settings** → **Ticket Forms**
2. Click **Create New Form**
3. Configure form properties
4. Add and arrange fields
5. Save and set as default (optional)
### Form Properties
| Property | Description | Required |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `name` | Internal form name for identification | Yes |
| `mode` | Form mode: **Inline Form** (built-in fields) or **Embedded Form** (external iframe) | No (default: Inline Form) |
| `is_default` | Use as default form when none specified | No |
| `show_subject` | Display subject field (inline mode only) | No |
| `show_body` | Display description field (inline mode only) | No |
| `show_priority` | Allow priority selection (inline mode only) | No |
| `show_typology` | Allow ticket type selection (inline mode only) | No |
| `show_status` | Display status selection in the form (inline mode only) | No (default: off) |
| `priority_typologies` | Restrict priority field to specific typologies. When set, the priority field only appears if the selected typology matches one in the list. Accepted values: `Question`, `Task`, `Incident` | No |
| `override_url_ticket_user` | Custom URL to redirect users to after ticket creation. Use this to send users to an external ticket portal instead of the default success screen | No |
***
## Field Configuration
### Available Field Types
| Type | Description | Best For |
| ------------- | ---------------------- | -------------------------------------- |
| `text` | Single-line input | Names, order numbers, short answers |
| `textarea` | Multi-line input | Descriptions, detailed explanations |
| `select` | Dropdown menu | Categories, departments, single choice |
| `multiselect` | Multiple selection | Tags, affected products |
| `checkbox` | Boolean toggle | Confirmations, opt-ins |
| `email` | Email with validation | Contact information |
| `phone` | Phone number input | Callback requests |
| `number` | Numeric input | Quantities, IDs |
| `tagger` | Tag selector (Zendesk) | Dynamic tagging |
### Field Properties
```json theme={null}
{
"id": "category",
"type": "select",
"label": "Issue Category",
"placeholder": "Select a category...",
"required": true,
"options": [
{"value": "technical", "label": "Technical Issue"},
{"value": "billing", "label": "Billing Question"},
{"value": "account", "label": "Account Management"}
]
}
```
| Property | Type | Description |
| ----------------------- | ------- | ------------------------------------------------------------------------------------- |
| `id` | string | Unique field identifier |
| `type` | string | Field type (see above) |
| `label` | string | Display label |
| `placeholder` | string | Hint text |
| `required` | boolean | Must be filled |
| `options` | array | Choices for select/multiselect |
| `default_value` | any | Pre-filled value |
| `is_hidden` | boolean | Hidden from user |
| `regexp_for_validation` | string | Regular expression pattern to validate input (e.g., `^ORD-[0-9]+$` for order numbers) |
***
## Conditional Fields
Show or hide fields based on user selections to create dynamic, streamlined forms.
### Basic Conditional Field
```json theme={null}
{
"id": "error_message",
"type": "textarea",
"label": "Error Message",
"conditional_field": "category",
"conditional_field_value": "technical"
}
```
This field only appears when `category` equals `technical`.
### Multiple Trigger Values
Show a field for multiple parent values:
```json theme={null}
{
"id": "account_details",
"type": "textarea",
"label": "Account Details",
"conditional_field": "category",
"conditional_field_value": "billing,account"
}
```
### Nested Conditionals
Chain conditions for complex forms:
```mermaid theme={null}
flowchart TD
A[Category] --> B[Technical]
A --> C[Billing]
A --> D[Account]
B --> E[Error Type]
E --> F[Login Issue]
E --> G[Performance]
F --> H[Browser Used]
G --> I[Device Type]
C --> J[Invoice Number]
D --> K[Account Action]
```
### Conditional Options
Options within a select field can also be conditional:
```json theme={null}
{
"id": "sub_category",
"type": "select",
"label": "Sub-Category",
"options": [
{
"value": "password_reset",
"label": "Password Reset",
"conditional_field_value": "account"
},
{
"value": "api_error",
"label": "API Error",
"conditional_field_value": "technical"
},
{
"value": "refund",
"label": "Refund Request",
"conditional_field_value": "billing"
}
]
}
```
***
## Grouped Options
Create hierarchical dropdown menus with option groups.
### Configuration
Add a `group` property to options:
```json theme={null}
{
"id": "product",
"type": "select",
"label": "Product",
"options": [
{"value": "slack", "label": "Slack Connector", "group": "Connectors"},
{"value": "notion", "label": "Notion Connector", "group": "Connectors"},
{"value": "zendesk", "label": "Zendesk Connector", "group": "Connectors"},
{"value": "widget", "label": "Chat Widget", "group": "Channels"},
{"value": "api", "label": "API Integration", "group": "Channels"},
{"value": "other", "label": "Other"}
]
}
```
### Display
Options with groups appear in a hierarchical hover menu:
```mermaid theme={null}
flowchart LR
A[Product] --> B[Connectors]
A --> C[Channels]
A --> D[Other]
B --> B1[Slack Connector]
B --> B2[Notion Connector]
B --> B3[Zendesk Connector]
C --> C1[Chat Widget]
C --> C2[API Integration]
```
***
## Option Messages
Show a contextual message below the field when a specific option is selected. Useful for warning users about expected delays, asking them to attach extra documents, or pointing them to a self-serve resource before submitting.
### Configuration
Open the field builder, expand an option's extras panel, fill in the **Info message** text, and pick a style:
| Style | When to use |
| --------------- | -------------------------------------------------------------------------- |
| Info (blue) | Helpful context, FAQ link, expected response time |
| Warning (amber) | Action recommended (attach a document, double-check the input) |
| Danger (red) | Strong caution — irreversible request, off-hours support, restricted scope |
The message appears immediately below the field as soon as the option is picked, and disappears if the user changes their selection.
***
## External System Integration
### Zendesk Field Mapping
Map form fields to Zendesk custom fields using `external_id`:
```json theme={null}
{
"id": "department",
"type": "select",
"label": "Department",
"external_id": "ticket_field_12345678",
"options": [
{"value": "sales", "label": "Sales"},
{"value": "support", "label": "Support"}
]
}
```
### Zendesk Group Assignment
Route tickets to specific Zendesk groups:
**Via Option external\_id:**
```json theme={null}
{
"id": "team",
"type": "select",
"label": "Team",
"options": [
{"value": "tech", "label": "Technical Team", "external_id": "groups_123456"},
{"value": "billing", "label": "Billing Team", "external_id": "groups_789012"}
]
}
```
**Via zendesk\_group\_id:**
```json theme={null}
{
"id": "product",
"type": "select",
"label": "Product",
"options": [
{"value": "product_a", "label": "Product A", "zendesk_group_id": "111111"},
{"value": "product_b", "label": "Product B", "zendesk_group_id": "222222"}
]
}
```
### Tagger Fields (Zendesk Tags)
Create fields that apply tags to Zendesk tickets:
```json theme={null}
{
"id": "issue_tags",
"type": "tagger",
"label": "Issue Tags",
"options": [
{"value": "urgent", "label": "Urgent"},
{"value": "bug", "label": "Bug Report"},
{"value": "feature-request", "label": "Feature Request"}
]
}
```
Selected values become Zendesk tags automatically.
### HelpScout Tags
For HelpScout, use the special `tag_helpscout` external\_id:
```json theme={null}
{
"id": "helpscout_tag",
"type": "select",
"label": "Category Tag",
"external_id": "tag_helpscout",
"options": [
{"value": "urgent-response", "label": "Urgent Response"},
{"value": "billing-issue", "label": "Billing Issue"}
]
}
```
***
## Name Extraction
Configure fields to extract user names for ticket requesters.
### First Name Field
```json theme={null}
{
"id": "first_name",
"type": "text",
"label": "First Name",
"use_to_set_first_name": true
}
```
### Last Name Field
```json theme={null}
{
"id": "last_name",
"type": "text",
"label": "Last Name",
"use_to_set_last_name": true
}
```
### Full Name Split
For a single "Full Name" field, the system attempts to split it automatically.
***
## Form-Level Settings
### Static Tags
Apply tags to all tickets from this form:
```json theme={null}
{
"name": "Widget Support Form",
"tags": "from-widget,chat-support,needs-triage"
}
```
### Brand Assignment (Zendesk)
Route tickets to a specific Zendesk brand:
```json theme={null}
{
"name": "Product A Support",
"brand_id": "123456789"
}
```
### Group Assignment (Zendesk)
Route all tickets to a specific group:
```json theme={null}
{
"name": "Billing Support",
"external_id": "987654321"
}
```
### Private Comment Content
Include all field values in the private comment:
```json theme={null}
{
"name": "Detailed Support Form",
"provide_all_fields_in_comment": true
}
```
***
## AI Prefilling
Configure AI to extract ticket information from conversations and pre-fill form fields automatically.
### How It Works
When a user requests to create a ticket, the AI analyzes the conversation and extracts relevant information to pre-fill the ticket form. This includes standard fields (subject, body, priority, typology) and any custom fields you enable for AI pre-fill.
Pre-filled fields are marked with a sparkles icon so users can review and adjust the values before submitting.
### Enabling AI Pre-fill for Custom Fields
Each custom field on a ticket form can be individually enabled for AI pre-fill:
1. Navigate to **Settings** > **Ticket Forms**
2. Open a form in the builder
3. In the **Fields** section, click the sparkles icon next to any field to toggle AI pre-fill
4. Save the form
When AI pre-fill is enabled for a field, the AI will attempt to extract its value from the conversation context. For fields with predefined options (select, tagger), the AI selects from the available choices. For text fields, the AI extracts relevant text.
### System Prompt
Customize the AI extraction behavior with a system prompt:
```json theme={null}
{
"name": "Technical Support Form",
"system_prompt": "Extract the following from the conversation:\n- Subject: Brief summary (max 80 characters)\n- Body: Detailed description including any error messages\n- Priority: Use 'High' if user mentions urgent, critical, or blocking; otherwise 'Normal'\n- Category: Match to Technical, Billing, or General"
}
```
You can auto-generate a system prompt from the form fields using the **Generate from fields** button in the form builder. This creates a prompt that lists all AI-prefillable fields with their types and available options.
### Best Practices
* Enable AI pre-fill only for fields where automated extraction adds value
* Be specific about expected formats and lengths in the system prompt
* Provide examples for ambiguous fields
* List available options for select fields
* Define keywords that indicate priority levels
### Example: E-commerce Support
```json theme={null}
{
"system_prompt": "Analyze the conversation and extract:\n\n1. Subject: One-line summary of the issue (under 100 chars)\n2. Body: Full description with relevant details\n3. Order Number: If mentioned, extract in format ORD-XXXXXX\n4. Issue Type: Shipping, Payment, Product Quality, Returns, or Other\n5. Priority: High if order is delayed or payment failed, Normal otherwise"
}
```
***
## Embedded External Forms
Instead of using the built-in inline form, you can embed an external form (such as HubSpot, Typeform, or any web form) directly in the chat. When a user requests to talk to a human, the embedded form is displayed inside the conversation.
### Setting Up Embed Mode
1. Navigate to **Settings** > **Ticket Forms**
2. Create or edit a form
3. In the **General** tab, set **Form Mode** to **Embedded Form**
4. Go to the **Embed** tab
5. Paste your **Embed HTML Code** (e.g., a HubSpot form script tag)
6. Optionally set a **Description** to display above the form
7. Save the form
### Embed HTML Code
Paste raw HTML embed code (such as a HubSpot or Typeform script tag) directly. The HTML is rendered inside the chat conversation and auto-resizes to fit the content.
**Example — HubSpot form:**
```html theme={null}
```
### Submission Detection
The system automatically detects when a user submits the embedded form. Detection is supported for:
* **HubSpot** -- HubSpot form callback events
* **Generic HTML forms** -- standard `