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

# Ticketing Best Practices

> Implement effective ticketing workflows with AGO

This guide covers form design, integration strategies, automation, and operational patterns for AGO ticketing.

## Choosing Your Ticketing System

### Decision Framework

| Consideration      | AGO Internal | HelpScout        | HubSpot             | Zendesk           |
| ------------------ | ------------ | ---------------- | ------------------- | ----------------- |
| **Team size**      | 1-5 agents   | 5-20 agents      | 5-50 agents         | 20+ agents        |
| **Existing tools** | None         | Email-centric    | HubSpot CRM         | Enterprise stack  |
| **Budget**         | Included     | Per-user pricing | Service Hub pricing | Per-agent pricing |
| **Setup time**     | Minutes      | Hours            | Hours               | Days              |
| **Customization**  | Basic        | Moderate         | Moderate            | Extensive         |

### When to Use Each System

**AGO Internal**

* Starting from scratch with no existing support tools
* Small teams that don't need advanced workflows
* Development and testing environments
* Simple support needs with basic ticket tracking

**HelpScout**

* Email is your primary support channel
* Conversation-based support style
* Need simple tagging and prioritization
* Small to medium teams (5-20 people)

**HubSpot**

* Already using HubSpot CRM and want a unified customer view
* Sales and support teams need to share context
* Contact auto-creation and property sync from HubSpot
* Owner-based ticket assignment

**Zendesk**

* Enterprise-scale support operations
* Complex routing and assignment rules
* Multi-brand or multi-product support
* Advanced analytics and reporting needs
* Integration with existing enterprise tools

***

## Form Design Best Practices

### Keep Forms Focused

**Do:**

* Ask only for essential information
* Use 5-7 fields maximum for initial forms
* Make most fields optional except critical ones

**Don't:**

* Require every field
* Ask for information available in context
* Include fields "just in case"

### Use Progressive Disclosure

Show complexity only when needed:

```mermaid theme={null}
flowchart LR
    A[Issue Type] --> B[Technical]
    A --> C[Billing]
    A --> D[General]
    B --> E[Error Message, Browser,<br>Steps to Reproduce]
    C --> F[Invoice Number, Amount]
    D --> G[just description]
```

This reduces cognitive load and improves completion rates.

### Write Clear Labels

| Poor Label | Better Label                    |
| ---------- | ------------------------------- |
| Type       | What type of issue is this?     |
| Priority   | How urgent is this?             |
| Category   | Which product area is affected? |
| Details    | Please describe your issue      |

### Provide Helpful Placeholders

```json theme={null}
{
  "id": "description",
  "type": "textarea",
  "label": "Describe your issue",
  "placeholder": "Include what you were trying to do, what happened, and any error messages you saw..."
}
```

### Group Related Options

For long dropdown lists, use hierarchical groups:

```mermaid theme={null}
flowchart TD
    A[Product] --> B[Connectors]
    A --> C[Channels]
    A --> D[Other]
    B --> B1[Slack]
    B --> B2[Notion]
    B --> B3[Zendesk]
    C --> C1[Chat Widget]
    C --> C2[API]
```

***

## Conditional Fields Strategy

### When to Use Conditional Fields

* **Different information needed per category** - Technical issues need error messages, billing needs invoice numbers
* **Reducing form complexity** - Show advanced options only when relevant
* **Routing decisions** - Collect different data based on where the ticket will go

### Best Practices

1. **Limit nesting depth** - Avoid more than 2-3 levels of conditionals
2. **Test all paths** - Ensure every combination displays correctly
3. **Consider mobile** - Deeply nested forms are hard on small screens
4. **Provide defaults** - Pre-select common options when appropriate

### Example: Support Tier Routing

```json theme={null}
{
  "id": "support_tier",
  "type": "select",
  "options": [
    {"value": "standard", "label": "Standard Support"},
    {"value": "priority", "label": "Priority Support"},
    {"value": "enterprise", "label": "Enterprise Support"}
  ]
}
```

Then show different fields:

* **Standard**: Basic description only
* **Priority**: + Urgency level, business impact
* **Enterprise**: + Account manager, SLA reference, escalation contacts

***

## AI Prefilling Optimization

### Writing Effective System Prompts

**Be specific about formats:**

```
Subject: One sentence summary, max 80 characters, no punctuation at end
Body: 2-3 paragraphs describing the issue, include any error messages verbatim
Priority: "High" if user mentions urgent/critical/blocking, otherwise "Normal"
```

**Provide examples:**

```
Example subject: "Cannot export reports to PDF format"
Example body: "When I click the Export button and select PDF..."
```

**List available options:**

```
Category must be one of: Technical, Billing, Account, General
Do not invent new categories.
```

### Testing Prefilling

1. Create test conversations with different issue types
2. Initiate ticket creation and review prefilled values
3. Adjust system prompt based on results
4. Test edge cases (vague requests, multiple issues)

### Common Prefilling Issues

| Issue                | Cause                     | Solution                              |
| -------------------- | ------------------------- | ------------------------------------- |
| Wrong category       | Ambiguous prompt          | List exact category values            |
| Overly long subjects | No length constraint      | Add "max X characters"                |
| Missing context      | Too focused on extraction | Add "include relevant details"        |
| Hallucinated info    | Model filling gaps        | Add "only include stated information" |

***

## External System Integration

### Zendesk Best Practices

**Field Mapping**

* Use `external_id` format: `ticket_field_12345678`
* Test mappings with a dedicated test form first
* Document all field IDs in a reference sheet

**Group Routing**

* Create forms per major department
* Use option-level `zendesk_group_id` for flexible routing
* Test routing with each group to verify permissions

**Tags**

* Use lowercase, hyphenated format: `from-widget`, `needs-review`
* Match tags to Zendesk automation triggers
* Avoid spaces and special characters
* Combine static form tags with user-selected tagger fields

**User Management**

* Default to Zendesk user validation for existing customers
* Use "Allow All Users" for public support portals
* Cache user validation results (30-minute default)

### HubSpot Best Practices

**Private App Setup**

* Enable only the scopes you need (`tickets`, `crm.objects.contacts.read/write`, `files`)
* Store the access token securely — it is only shown once
* Use a dedicated Private App for AGO (not a shared one)

**Property Mapping**

* Use **Import from HubSpot** in the form builder to sync available properties
* Set `hubspot_property_name` on each field to match the internal HubSpot property name
* Test with a sample ticket to confirm values appear in HubSpot

**Owner Assignment**

* Add a dropdown field with `hubspot_owner_id` set on each option
* Find owner IDs via the HubSpot API or Settings > Users & Teams

### HelpScout Best Practices

**OAuth Setup**

* Rotate client secrets periodically
* Monitor token cache hit rates
* Test in sandbox before production

**Tagging Strategy**

* Use priority tags: `priority-low`, `priority-normal`, `priority-high`
* Use typology tags: `type-question`, `type-incident`, `type-task`
* Add custom tags via `tag_helpscout` external\_id

**Mailbox Configuration**

* Verify mailbox ID matches your intended destination
* Test conversation creation permissions
* Configure notification preferences in HelpScout

***

## Success Messages

### Writing Effective Messages

**Include:**

* Confirmation of submission
* Expected response time
* What happens next
* How to follow up

**Example:**

```markdown theme={null}
## Request Received

Your support ticket has been created successfully.

**What happens next:**
1. Our team will review your request within 2 hours
2. You'll receive email updates on progress
3. Average resolution time: 24 hours

For urgent issues, call +1-555-SUPPORT.
```

### Different Messages for Different Forms

| Form Type        | Message Focus                     |
| ---------------- | --------------------------------- |
| Standard Support | Response time, next steps         |
| Enterprise       | SLA commitment, escalation path   |
| Bug Report       | Tracking process, workarounds     |
| Feature Request  | Review process, voting/visibility |

***

## Automation with Triggers

### Common Ticket Triggers

**Auto-categorization:**

* Condition: Subject contains "password" or "login"
* Action: Set category to "Authentication"

**Priority Escalation:**

* Condition: Priority is "Urgent" AND status is "Open" for 1 hour
* Action: Notify support manager

**Routing:**

* Condition: Typology is "Billing"
* Action: Assign to Billing group

### Using Placeholders

Create dynamic notifications:

```
New {{ticket.priority}} ticket from {{ticket.requester.email}}

Subject: {{ticket.subject}}
Type: {{ticket.typology}}

{{ticket.body}}

View ticket: [link]
```

### Trigger Best Practices

1. **Start simple** - Add complexity gradually
2. **Test thoroughly** - Create test tickets for each trigger
3. **Monitor logs** - Watch for trigger execution errors
4. **Avoid conflicts** - Ensure triggers don't fight each other
5. **Document** - Maintain a trigger reference document

***

## Permission Configuration

### Designing Permission Hierarchy

1. **Global Config** (default) — base permissions
2. **Custom Permission** (per user type) — overrides Global Config
3. **Allow All Users** (superadmin override) — overrides everything above

### Permission Strategies

**Restrictive (B2B SaaS)**

* Ticket creation tied to active subscription
* Different access levels per plan tier
* Account admins can grant access to team members

**Open (Consumer Support)**

* Enable "Allow All Users"
* Collect email from widget users
* Validate email format only

**Hybrid (Enterprise)**

* Existing users validated against Zendesk
* New users require manager approval
* Widget users get limited access

### Custom Denied Messages

Create helpful messages instead of generic errors:

```markdown theme={null}
### Account Upgrade Required

Your current plan doesn't include direct ticket support.

**Your options:**
- [Upgrade to Pro](https://billing.example.com) for ticket support
- Visit our [Help Center](https://help.example.com) for self-service
- Email support@example.com for urgent issues
```

***

## Operational Excellence

### Monitoring & Metrics

**Track these metrics:**

* Ticket creation success rate
* Average prefilling accuracy
* Form completion rate
* Time to first response
* Resolution time by category

**Set up alerts for:**

* Spike in ticket creation failures
* External system integration errors
* Unusual volume patterns

### Regular Maintenance

**Weekly:**

* Review trigger execution logs
* Check for integration errors
* Monitor user feedback

**Monthly:**

* Analyze form completion rates
* Review and update category options
* Audit field mappings

**Quarterly:**

* Review and optimize system prompts
* Update success messages
* Evaluate trigger effectiveness

### Documentation

Maintain documentation for:

* Field ID mappings (AGO ↔ external system)
* Trigger logic and conditions
* Permission configurations
* Integration credentials (securely stored)
* Escalation procedures

***

## Common Pitfalls to Avoid

### Form Design

| Pitfall                  | Impact               | Prevention                               |
| ------------------------ | -------------------- | ---------------------------------------- |
| Too many required fields | Low completion rates | Only require truly essential fields      |
| Jargon in labels         | User confusion       | Use clear, customer-facing language      |
| No validation hints      | Form errors          | Add placeholders and validation messages |
| Broken conditionals      | Missing fields       | Test all field combinations              |

### Integration

| Pitfall               | Impact                   | Prevention                    |
| --------------------- | ------------------------ | ----------------------------- |
| Hardcoded field IDs   | Breaks on system changes | Use environment configuration |
| No error handling     | Silent failures          | Log and alert on failures     |
| Missing rate limiting | API throttling           | Implement proper caching      |
| Insecure credentials  | Security breach          | Use secrets management        |

### Operations

| Pitfall                 | Impact               | Prevention                    |
| ----------------------- | -------------------- | ----------------------------- |
| No trigger testing      | Unexpected behavior  | Test environment for triggers |
| Conflicting automations | Inconsistent results | Document trigger interactions |
| Stale configurations    | Poor user experience | Regular review cadence        |
| No monitoring           | Unnoticed failures   | Set up alerts and dashboards  |

***

## Checklist: Launching Ticketing

### Pre-Launch

* [ ] Ticketing system selected and configured
* [ ] Form fields defined and tested
* [ ] External system integration verified
* [ ] Field mappings documented
* [ ] Permissions configured
* [ ] Success messages written
* [ ] AI prefilling tested
* [ ] Triggers configured and tested
* [ ] Denied messages configured

### Launch Day

* [ ] Enable ticketing for production
* [ ] Monitor first 10 tickets closely
* [ ] Verify external system receives tickets
* [ ] Check trigger execution
* [ ] Confirm notifications working

### Post-Launch

* [ ] Collect user feedback
* [ ] Review completion rates
* [ ] Adjust form based on data
* [ ] Optimize prefilling prompts
* [ ] Document lessons learned

***

## Related

* [Ticketing](../features/ticketing) — Core ticketing features
* [Ticket Form Customization](../features/ticket-form-customization) — Form configuration
* [Ticketing Connectors](../data-connector/ticketing-connectors) — External system integration
* [Ticketing Tool](../tools/ticketing-tool) — Agent ticketing tool
* [Set Up Ticket Escalation](./setup-ticketing-howto) — Step-by-step setup guide