Ticketing Tool

Create support tickets and escalate conversations to human agents

The AGO Ticketing Tool enables agents to create support tickets and escalate conversations to human agents when needed.

Overview

Tool Name: ago_ticketing

The ticketing tool provides a direct escalation path from AI conversations to human support. When an agent cannot resolve an issue or a user requests human assistance, this tool opens a ticket form for the user to review and submit.

Key Features

• Create support tickets from conversation context
• Escalate to human support teams
• Link tickets to their conversation
• Integrate with external ticketing systems (Zendesk, HelpScout)
• Customizable ticket forms and fields
• Priority and category assignment

---

When to Use

The ticketing tool should be triggered when:

Scenario	Example
User requests human help	”Can I speak to someone?”
Issue requires account access	Password resets, billing changes
Complex issues	Multi-step troubleshooting failures
User frustration detected	Multiple failed attempts
Sensitive topics	Legal, compliance, security
Out of scope requests	Topics agent isn’t trained for

---

Configuration

Per-Agent Configuration

To customize the ticketing tool for a specific agent:

1. Navigate to AI Studio → Tools
2. Click Create Tool
3. Select ago_ticketing as the tool type
4. Configure the tool:
   • Name: Internal identifier (e.g., “support_escalation”)
   • Display Name: User-facing name (e.g., “Contact Support”)
   • Description: When the agent should use this tool
5. Save the tool.
6. Assign the tool to your agent in AI Studio → Agents → [Agent Name] → Tools.

Configure the fields shown to users in the ticket form settings. The ago_ticketing call itself takes no arguments.

---

Ticket Form Fields

Standard Fields

The ticket form settings control which standard fields are shown:

Field	Description
Subject	Ticket subject line
Body	Detailed issue description
Priority	Low, Normal, High, Urgent
Typology	Question, Task, Incident

Custom Fields

Add custom fields to your ticket form based on your ticketing system needs. For example:

Field	Type	Example Values
subject	text	Required ticket subject
product_area	tagger (dropdown)	dashboard, api, integrations, billing
customer_type	tagger (dropdown)	free, pro, enterprise
reproduction_steps	text	Steps to reproduce the issue
browser	text	User’s browser information
urgency_reason	text	Why the issue is urgent

Configure which fields are required in the ticket form settings.

---

Ticket Creation Flow

When the agent opens the ticket form, the chat may also display an accompanying text response. The user reviews and submits the form to create the ticket.

---

AI Pre-Fill

The ticketing tool can extract ticket information from the conversation using AI. When a ticket form is configured with pre-fillable fields, the system automatically generates a prompt that instructs the LLM to extract values for those fields from the conversation.

How It Works

1. Admin marks specific form fields as AI pre-fill enabled in the ticket form configuration
2. When the agent triggers the ticketing tool, the system builds a dynamic extraction prompt listing all pre-fillable fields with their types, options, and validation rules
3. The LLM extracts values from the conversation and pre-fills the form
4. The user reviews and submits the form with pre-filled values

Supported Field Types

AI pre-fill supports text, textarea, tagger, multiselect, checkbox, integer, and regexp-validated fields. For fields with predefined options (tagger, multiselect), the LLM is given the available choices to select from.

Custom Extraction Instructions

Each ticket form has an optional System Prompt field where you can add custom extraction instructions. For example: “Always extract reproduction steps if the user describes a bug” or “Mark priority as High when the user mentions the word urgent.”

---

Embedded Forms

Ticket forms support two display modes:

Mode	Description
Inline Form (default)	AGO renders the form inline in the chat widget
Embedded Form	An external form (e.g. HubSpot) is displayed in the chat using the HTML/script you provide

Configuring Embedded Forms

1. In the ticket form settings, select Embedded Form as the form mode
2. Paste the external form HTML/script in the Embed HTML Code field
3. Optionally add a Description shown above the form

When the agent opens an embedded form, it appears in the chat. AGO detects submissions from standard HTML forms embedded directly in the chat and from supported HubSpot forms. When a submission is detected, AGO uses the captured data to create a ticket. Other external forms may display successfully without triggering AGO ticket creation.

---

Integration with Ticketing Systems

Zendesk Integration

Connect to Zendesk for ticket creation:

1. On the ticket forms page, select Zendesk as the active ticketing system and use Configure ticketing system to enter its connection settings
2. Map ticket fields to Zendesk fields
3. If you use automatic ticket creation, optionally set an assignee email for those tickets

See Zendesk Ticketing Integration for setup.

HelpScout Integration

Connect to HelpScout:

1. On the ticket forms page, select HelpScout as the active ticketing system and use Configure ticketing system.
2. Enter the OAuth2 App ID and OAuth2 App secret from your HelpScout application.
3. Enter the Mailbox ID where tickets should be created and save the settings.

See HelpScout Integration for setup.

Internal Ticketing

Use AGO’s built-in ticketing without external integration:

• Tickets stored in AGO database
• Manage via admin interface
• Export to CSV

---

Conversation Context

Tickets created from a conversation are linked to that conversation. Their private comment can include:

Context	Description
Conversation link	Included by default; a custom private-comment introduction can place the link using {url}
Configured user context	Labeled fields from authentication or widget metadata, when configured and available
Form field values	Included when the form’s option to provide all fields in the comment is enabled

---

Best Practices

Prompt Engineering

Write clear escalation triggers in the agent’s prompt:

## Escalation Rules

Create a support ticket when:
1. User explicitly says "speak to a human" or similar
2. You cannot resolve the issue after 2-3 troubleshooting attempts
3. The issue requires account-level access you don't have
4. User expresses significant frustration

Before creating a ticket:
1. Summarize the issue clearly
2. List what you've already tried
3. Ask the user to confirm they want to create a ticket

User Experience

• Confirm before creating: Always verify with the user
• Set expectations: Provide estimated response times
• Provide reference: Give ticket number for tracking
• Offer alternatives: Suggest self-service options first

Quality Control

• Rich context: Include all relevant details
• Clear categorization: Use accurate priority and category
• Avoid duplicates: Check for existing tickets
• Follow up: Track resolution rates

---

Troubleshooting

Issue: Tickets not being created

Solutions:

1. Verify ticketing tool is assigned to agent
2. Check external ticketing credentials
3. Review tool logs for errors
4. Verify user has ticket creation permissions

Issue: Missing conversation context

Solutions:

1. Check thread ID is being passed correctly
2. Verify conversation history storage
3. Review ticket connector configuration

Issue: Wrong assignee or priority

Solutions:

1. Review ticket form field configuration
2. Check default values
3. Verify mapping rules in connector

---

API Reference

For programmatic access, see:

• Public API v1 Reference - Tool management and read-only ticket access

---

Related Documentation

• Tools Description Guide - Best practices for tool descriptions
• Ticketing Overview - Ticketing system setup
• Tools Overview - Tool configuration
• Zendesk Integration - Zendesk setup
• HelpScout Integration - HelpScout setup