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 Tickets → Ticket Forms
2. Click Create Form
3. Configure form properties
4. Add and arrange fields
5. Save the form. Default-form selection is configured separately

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)
show_subject	Display subject field (inline mode only)	No
show_body	Require the detailed context. The built-in chat form displays this input even when it is optional	No
show_priority	Allow priority selection (inline mode only)	No
show_typology	Allow ticket type selection (inline mode only)	No
show_status	Stored form setting; the built-in chat form does not render a status selector	No (default: off)
priority_typologies	Restrict priority field to specific typologies. When a typology has been selected, hide priority if it is outside this list. Accepted values: Question, Task, Incident	No

---

Which Form a User Gets

When someone opens a ticket from the chat, AGO picks the form in this order:

1. The form attached to the user — set on their profile, in Settings → User Management → Users → open the user → Ticket Form
2. A form matching the Zendesk tag rules on their highest-priority permission — when Zendesk is the active ticketing system
3. The form attached to their highest-priority permission — set when editing a permission
4. The default form — the one marked as default

The first match wins. Lower-priority permissions never supply an alternative form. If the highest-priority permission has no tag rules or assigned form, AGO uses the default form. Attach a form to a user when one person needs a different form from everyone else sharing their permission — for example a key account who must fill in a contract number that other customers don’t have.

To remove a direct assignment, set the user’s ticket form to Use the form from permissions. Zendesk tag mappings on the highest-priority permission, when configured, are then checked before that permission’s form.

Select a Form from Zendesk User Tags

With Zendesk as the active ticketing system, open a permission and select Ticket Instructions. Under Zendesk user tags → ticket forms:

1. Click Add mapping.
2. Enter the exact tag from the Zendesk user profile and select an AGO ticket form belonging to Zendesk.
3. Add more mappings as needed. Use the arrows to put higher-priority rules first.
4. Click Save.

Only the user’s highest-priority permission supplies tag rules. Rules on lower-priority permissions are ignored, even when the highest permission has no matching rule. New permissions start without rules.

For example, map premium to a Premium Support form and partner to a Partner Support form. If someone has both tags, the first matching row wins. Each tag can appear once; several tags can select the same form.

AGO reads user-profile tags for signed-in users whose authenticated email matches an active Zendesk user. Ticket tags and organization tags do not trigger these rules. Tag changes can take up to one minute to be reflected; reload the chat configuration afterward. If no rule matches, the mapped form was deleted, or Zendesk is unavailable, AGO falls back to the remaining rules on that permission, its ticket form, and then the default form. A manually assigned user form always takes priority.

---

Automatic Internal Notes

For an inline Ago or Zendesk form, open Advanced and enter instructions in Automatic internal note. Save the form to enable it. Leave the instructions empty to disable it. Each form can use its own format and language, up to 10,000 characters.

After a ticket is successfully submitted, AGO generates a private note from the saved ticket and the full visible conversation. For Zendesk, it reads the accepted ticket, including custom field labels and selected choices. The ticket supplies the current request; the conversation supplies the history, attempted solutions and results. Opening or cancelling the form does not generate a note.

Example instructions:

Use these headings: Issue and impact; Steps tried and results; Unresolved questions; Next action.
Write in French. Use the saved ticket for the current request and the conversation for history.
Identify conflicting information and do not invent missing facts.

The note appears as an internal message in Ago or a private comment in Zendesk, separately from the usual ticket metadata comment. Customers do not receive it as a public reply. Embedded forms and other providers do not generate these notes.

Generation runs in the background. If it fails, the ticket stays created without an automatic note. There is no automatic retry. Refresh the ticket to see the note once it has been added.

Generation uses the existing ticket and conversation without saving separate working copies. Delivered notes follow normal ticket retention. Test form creates a real ticket using saved settings; because no conversation is attached, its note uses ticket details only.

---

Field Configuration

Available Field Types

The built-in chat form renders a checkbox for checkbox fields, a single-choice select for fields with options, and a single-line text input for other custom fields. A custom type name alone does not add multiple selection or email or number validation. Use the form’s detailed context input for multiline text, and a validation pattern for custom text formats.

Field Properties

Configure fields in the form builder. Field and option settings are separate; these tables describe the available settings rather than a complete API request.

Field setting	Description
title	Label shown to the visitor
active	Include the field in the form
required	Require a value when the field applies
is_hidden	Keep the field out of the visible form
always_visible	Bypass progressive display while still respecting conditions
regexp_for_validation	Validate text against a pattern, such as ^ORD-[0-9]+$
external_id	Field identifier used by the ticketing integration

Option setting	Description
name	Label shown in the list
value	Value saved when selected
is_default	Preselect this option when the form opens
position	Order in the list
group	Group related choices

---

Conditional Fields

Show or hide fields based on user selections to create dynamic, streamlined forms.

Basic Conditional Field

Choose a parent field and a value that makes the dependent question relevant. For example, show Error Message only when Issue Category is Technical. The trigger uses the parent’s saved option value, not its display label.

Multiple Trigger Values

A question can accept several parent answers. For example, show Account Details when Issue Category is either Billing or Account Management. Field conditions store these accepted values as a comma-separated list, such as billing,account.

The SDK chat widget supports these questions across ticketing providers. Conditions may refer to a field UUID or its external ID. When an answer changes, responses from branches or choices that no longer apply are cleared. Active hidden fields retain defaults when both the field and its selected option still apply.

Nested Conditionals

Chain conditions for complex forms:

Conditional Options

Individual choices can depend on another answer too. Configure both the parent field and the accepted values for each conditional option.

Choice	Parent question	Accepted parent value
Password Reset	Issue Category	account
API Error	Issue Category	technical
Refund Request	Issue Category	billing

For API integrations, option conditions use conditional_field_id and the array conditional_field_values, for example ["account", "billing"]. Unlike a field condition, an option condition does not use a singular comma-separated value.

---

Grouped Options

Create hierarchical dropdown menus with option groups.

Configuration

Give related options the same group value. For example, place Slack Connector and Notion Connector in Connectors, and Chat Widget in Channels. Leave group empty for choices that do not need a group.

Display

The hosted chat uses a hierarchical hover menu. The SDK widget uses native select groups. Both present the choices under their configured group names:

---

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

Import a Zendesk Form

Rebuild an existing Zendesk ticket form in AGO instead of recreating it by hand:

1. Create or open a form whose ticketing system is Zendesk.
2. In Custom Fields, click Import a Zendesk form and pick a form from the list.
3. Review the fields, then click Save to update the form.

The import loads:

• The custom fields customers can edit, in the Zendesk order. Fields and options missing from AGO are created as soon as you import, even if you do not save the form.
• The conditions shown to customers (Zendesk end-user conditions) on drop-down and checkbox fields.
• Show Subject, Show Body, Show Status, Show Priority and Show Typology, turned on for the Zendesk system fields customers can edit and off for the others.
• The Zendesk ticket form ID, and the form name if it was empty.

The import replaces the fields currently in the form. AI pre-fill stays enabled on fields that were already in it.

A notice lists what could not be carried over: agent-only or inactive fields, conditions on other field types, and fields that depend on several fields in Zendesk. AGO shows a field based on a single parent field, so only the first condition is kept in that case; adjust it in the field’s conditions if needed. Agent conditions are not imported.

Zendesk Field Mapping

Set the numeric zendesk_field_id for a custom field. The integration also recognizes an external_id such as ticket_field_12345678 when no explicit Zendesk field ID is set.

Zendesk Group Assignment

An option can route the ticket with its numeric zendesk_group_id. The fallback option identifier format is groups_123456.

Tagger Fields (Zendesk Tags)

Selected values of tagger fields are included in the ticket’s tags. Configure option values to match the tags you want to send.

HelpScout Tags

For HelpScout, a field with the external ID tag_helpscout supplies a tag from its selected value.

---

Name Extraction

Configure fields to extract user names for ticket requesters.

First Name Field

A field marked use_to_set_first_name supplies its complete value as the first name for integrations that support requester name extraction.

Last Name Field

A field marked use_to_set_last_name supplies its complete value as the last name.

Full Name Split

There is no automatic split of a full-name answer. Use separate designated fields when your integration needs separate first and last names.

---

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.

Visitors can review and edit pre-filled values before submitting. The sparkles icon in the admin field manager controls which custom fields the AI may pre-fill.

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 Tickets > 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 Tickets > 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. Auto-fill supports the following standard names, including HubSpot names with a prefix ending in /email, /subject, or the corresponding property name. Matching custom-field names can also be filled from the extracted custom values:

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

Match your form property names to the standard or custom values you want to pre-fill.

Form Data Capture

AGO captures submitted values from forms that emit a standard HTML submit event and from supported HubSpot callbacks. Custom AJAX forms need one of these supported events; arbitrary network submissions are not detected automatically. Captured subject and body values populate the ticket when available, and the supported captured fields are stored for reference. Files, empty values, provider tracking and consent fields, and text values longer than 2,000 characters are excluded. Large captured payloads may be truncated before storage.

Limitations

• Submission detection depends on the form provider supporting cross-origin messaging (HubSpot is supported; Google Forms is not)
• Auto-fill requires matching standard or custom property names

---

Success Messages

Customize the confirmation text and ticket link label. A configured ticket URL prefix changes the link destination by appending the external ticket ID; it does not automatically redirect the visitor away from the success screen.

Basic Message

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

Message Formatting

Success messages are plain text. Line breaks are preserved; Markdown headings and bold markers are not rendered as formatting.

With Action Link

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

---

Complete Form Examples

Use these as form-builder layouts rather than JSON import payloads.

Simple Contact Form

Show the subject and detailed context, hide priority, and add a short success message. The requester email input is separate from custom fields.

Enterprise Support Form

Question	Configuration
Company Name	Required text field
First Name / Last Name	Separate text fields for requester name extraction
Environment	Choices: production, staging, development
Severity	Choices: critical, high, medium, low
Affected Users	Text field with a numeric validation pattern; show for critical or high severity

Add static tags as a list of values and set a plain-text success message.

Multi-Product Form with Routing

Use a product choice with a Zendesk group ID on each option. Add an issue-type question, then show Integration Name only when the issue type is Integration. A separate tagger field can add the selected tag to the ticket.

---

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
• Explain expected formats - Give examples in the question title when needed
• Order logically - Most important fields first

Field Configuration

• Set sensible defaults - Pre-fill when possible
• Validate custom text formats - Configure a pattern when a field requires an email, number or specific identifier
• 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 the condition references the intended parent field
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