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

{
  "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

{
  "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:

{
  "id": "account_details",
  "type": "textarea",
  "label": "Account Details",
  "conditional_field": "category",
  "conditional_field_value": "billing,account"
}

Nested Conditionals

Chain conditions for complex forms:

Conditional Options

Options within a select field can also be conditional:

{
  "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:

{
  "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:

---

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

{
  "id": "first_name",
  "type": "text",
  "label": "First Name",
  "use_to_set_first_name": true
}

Last Name Field

{
  "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:

{
  "name": "Widget Support Form",
  "tags": "from-widget,chat-support,needs-triage"
}

Brand Assignment (Zendesk)

Route tickets to a specific Zendesk brand:

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

Group Assignment (Zendesk)

Route all tickets to a specific group:

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

Private Comment Content

Include all field values in the private comment:

{
  "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:

{
  "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

{
  "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:

<script charset="utf-8" type="text/javascript" src="//js.hsforms.net/forms/embed/v2.js"></script>
<script>
  hbspt.forms.create({
    region: "na1",
    portalId: "12345678",
    formId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
  });
</script>

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 <form> submit events

After submission is detected, a configurable success message is shown, a ticket record is created in the system, and the conversation is blocked from further input. Ticket triggers and email notifications are processed the same way as inline form submissions.

AI Prefilling in Embed Mode

AI prefilling works in embed mode. When a user requests to create a ticket, the AI analyzes the conversation to extract relevant information and automatically fills matching fields in the embedded form. Field matching uses exact name matching against the following standardized field names:

Field name	Description
email	Contact email
firstname	First name
lastname	Last name
phone	Phone number
subject	Ticket subject
body	Ticket body

Verify your HubSpot form properties use these internal names for auto-fill to work.

Form Data Capture

When a user submits an embedded form, the system captures the form field values and stores them in the ticket record. This works automatically for standard HTML forms, HubSpot forms, and AJAX-based form submissions. The captured data is used to populate the ticket subject and body, and the raw field values are stored for reference.

Limitations

• Submission detection depends on the form provider supporting cross-origin messaging (HubSpot is supported; Google Forms is not)
• Auto-fill requires form fields to use the standardized field names listed above

---

Success Messages

Customize post-submission experience.

Basic Message

{
  "name": "Support Form",
  "success_message_text": "Thank you! Your request has been submitted. We'll respond within 24 hours."
}

With Markdown

{
  "success_message_text": "## Request Received\n\nYour support ticket has been created successfully.\n\n**What happens next:**\n- You'll receive a confirmation email\n- Our team will review within 2 hours\n- Check your email for updates"
}

With Action Link

{
  "success_message_text": "Your ticket has been submitted!",
  "success_message_url_label": "View your tickets"
}

---

Complete Form Examples

Simple Contact Form

{
  "name": "Quick Support",
  "show_subject": true,
  "show_body": true,
  "show_priority": false,
  "success_message_text": "Thanks! We'll be in touch soon.",
  "fields": [
    {
      "id": "email",
      "type": "email",
      "label": "Your Email",
      "required": true
    }
  ]
}

Enterprise Support Form

{
  "name": "Enterprise Support",
  "external_id": "enterprise_group_id",
  "tags": "enterprise,priority-support",
  "provide_all_fields_in_comment": true,
  "system_prompt": "Extract detailed issue information. Mark as High priority if user mentions production, outage, or critical.",
  "success_message_text": "## Priority Support Request Received\n\nYour enterprise support ticket has been created. Our dedicated team will respond within 4 hours.\n\n**For urgent issues:** Call your dedicated support line.",
  "success_message_url_label": "Contact Account Manager",
  "fields": [
    {
      "id": "company_name",
      "type": "text",
      "label": "Company Name",
      "required": true
    },
    {
      "id": "contact_name",
      "type": "text",
      "label": "Your Name",
      "required": true,
      "use_to_set_first_name": true
    },
    {
      "id": "environment",
      "type": "select",
      "label": "Environment",
      "required": true,
      "options": [
        {"value": "production", "label": "Production"},
        {"value": "staging", "label": "Staging"},
        {"value": "development", "label": "Development"}
      ]
    },
    {
      "id": "severity",
      "type": "select",
      "label": "Severity",
      "required": true,
      "options": [
        {"value": "critical", "label": "Critical - System Down"},
        {"value": "high", "label": "High - Major Feature Broken"},
        {"value": "medium", "label": "Medium - Workaround Available"},
        {"value": "low", "label": "Low - Minor Issue"}
      ]
    },
    {
      "id": "affected_users",
      "type": "number",
      "label": "Number of Affected Users",
      "conditional_field": "severity",
      "conditional_field_value": "critical,high"
    }
  ]
}

Multi-Product Form with Routing

{
  "name": "Product Support",
  "system_prompt": "Identify the product and issue type from conversation. Use the product name for routing.",
  "fields": [
    {
      "id": "product",
      "type": "select",
      "label": "Product",
      "required": true,
      "options": [
        {"value": "analytics", "label": "Analytics Platform", "zendesk_group_id": "111111"},
        {"value": "crm", "label": "CRM Suite", "zendesk_group_id": "222222"},
        {"value": "marketing", "label": "Marketing Tools", "zendesk_group_id": "333333"}
      ]
    },
    {
      "id": "issue_type",
      "type": "select",
      "label": "Issue Type",
      "required": true,
      "options": [
        {"value": "bug", "label": "Bug Report"},
        {"value": "feature", "label": "Feature Request"},
        {"value": "how_to", "label": "How-To Question"},
        {"value": "integration", "label": "Integration Issue"}
      ]
    },
    {
      "id": "integration_name",
      "type": "text",
      "label": "Integration Name",
      "conditional_field": "issue_type",
      "conditional_field_value": "integration"
    },
    {
      "id": "tags",
      "type": "tagger",
      "label": "Additional Tags",
      "options": [
        {"value": "urgent", "label": "Urgent"},
        {"value": "regression", "label": "Regression"},
        {"value": "documentation", "label": "Needs Documentation"}
      ]
    }
  ]
}

---

Best Practices

Form Design

• Keep forms concise - Only ask for essential information
• Use conditional fields - Show complexity only when needed
• Provide clear labels - Avoid jargon and abbreviations
• Add placeholders - Give examples of expected input
• Order logically - Most important fields first

Field Configuration

• Set sensible defaults - Pre-fill when possible
• Use appropriate types - Email fields validate emails, etc.
• Mark critical fields required - But don’t overdo it
• Group related options - Use hierarchical dropdowns

Integration

• Test field mappings - Create test tickets to verify
• Validate external IDs - Double-check Zendesk/HelpScout IDs
• Monitor for errors - Check logs after deployment

---

Troubleshooting

Field not appearing

1. Check conditional_field matches parent field ID exactly
2. Verify conditional_field_value matches option value (not label)
3. Verify field is included in form configuration
4. Check browser console for errors

Values not mapping to external system

1. Verify external_id format (e.g., ticket_field_12345 for Zendesk)
2. Check field type matches external system expectations
3. Test with a simple ticket first
4. Review AGO logs for mapping errors

Prefilling not working

1. Verify system_prompt is set on the form
2. Verify AI pre-fill is enabled (sparkles icon) on the desired custom fields
3. Check conversation has enough context
4. Review AI instructions for clarity
5. Test with explicit conversation content

---

Related

• Ticketing — Feature overview
• Ticketing Tool — Agent ticketing tool