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

# Zendesk Ticketing

> Create support tickets in Zendesk from AGO conversations

Connect AGO to Zendesk so your agents can create support tickets directly in Zendesk when they need to escalate a conversation.

## Prerequisites

* An active Zendesk Support account
* A Zendesk admin or agent user with API token access
* Admin access to both Zendesk and AGO

***

## Step 1: Generate a Zendesk API Token

1. Go to **Zendesk Admin Center** > **Apps and integrations** > **APIs** > **Zendesk API**
2. Click the **Settings** tab
3. Enable **Token Access**
4. Click **Add API token**
5. Copy the generated token — you will not be able to see it again

<Warning>
  ### API Token is Tied to a Zendesk User

  Zendesk API tokens are linked to the user who created them. There is no "service account" in Zendesk — you must use a real user's credentials. Use an Admin user. If that user is deactivated or loses permissions, the API token stops working.
</Warning>

***

## Step 2: Get Your Subdomain

Find your Zendesk subdomain in the URL:

```
https://company.zendesk.com/...
         ^^^^^^^
         This is your subdomain
```

***

## Step 3: Configure in AGO

1. Navigate to **Ticketing** > **Settings**
2. Set **Active Ticketing System** to **Zendesk**
3. Enter your credentials:
   * **Admin Email**: email address of the user who created the API token
   * **API Token**: from Step 1
   * **Subdomain**: from Step 2
4. Click **Save**

***

## Step 4: Create a Ticket Form

1. Navigate to **Ticketing** > **Ticket Forms**
2. Create a new form
3. Add fields and configure [custom field mapping](../features/ticket-form-customization#external-system-integration) to Zendesk
4. Save the form

**Zendesk-specific form properties:**

| Property                        | Description                                                    |
| ------------------------------- | -------------------------------------------------------------- |
| `external_id`                   | Zendesk group ID — all tickets from this form go to that group |
| `brand_id`                      | Zendesk brand ID for multi-brand accounts                      |
| `tags`                          | Static tags applied to every ticket from this form             |
| `provide_all_fields_in_comment` | Include all field values in the private comment                |

***

## How It Works

When a user creates a ticket through AGO:

1. AGO validates the user (checks if they exist in Zendesk, or auto-creates if "Allow All Users" is enabled)
2. Files are uploaded to Zendesk and receive upload tokens
3. A ticket is created with subject, body, priority, type, custom fields, tags, group assignment, brand, and file tokens
4. A private comment is added with a link to the AGO conversation thread (plus JWT fields and field values if configured)
5. AGO triggers are processed, and the Zendesk support team is notified

### Field Mapping

| AGO Field     | Zendesk Field    | Notes                                                                       |
| ------------- | ---------------- | --------------------------------------------------------------------------- |
| Subject       | `subject`        | Ticket title                                                                |
| Body          | `comment.body`   | Initial ticket description                                                  |
| Priority      | `priority`       | Converted to lowercase (e.g., "High" becomes "high")                        |
| Typology      | `type`           | Ticket type, converted to lowercase                                         |
| Custom fields | Custom field IDs | Mapped via `external_id` (e.g., `ticket_field_12345`) or `zendesk_field_id` |
| Files         | Upload tokens    | Uploaded individually, then attached to the ticket comment                  |

### Custom Fields, Tags, and Group Assignment

Map AGO form fields to Zendesk custom fields using `external_id` or `zendesk_field_id` (numeric, takes priority when set). Use tagger fields for user-selected tags, and static form tags for routing rules. Route tickets to groups at the form, field, or option level.

See [Ticket Form Customization](../features/ticket-form-customization#external-system-integration) for full details.

### Brand Support

For multi-brand Zendesk accounts, set `brand_id` on a ticket form to create tickets under a specific brand.

**Finding Brand IDs:** Go to Zendesk Admin Center > Account > Brand management, click a brand, and find the ID in the URL.

### Name Extraction

AGO extracts user names in this order:

1. Ticket fields marked with `use_to_set_first_name` / `use_to_set_last_name`
2. First and last name from the AGO user profile
3. Username part of the email address (before @)

***

## User Permission Models

AGO supports two models for determining who can create Zendesk tickets.

### Model 1: Zendesk User Validation (Default)

Users must exist and be active in your Zendesk account. AGO searches for their email, and if found with `active: true` and not `suspended: true`, caches their Zendesk user ID for 30 minutes.

**Best for:** Organizations with defined user lists in Zendesk.

### Model 2: Allow All Users

Any AGO user can create tickets, even without a Zendesk account. Zendesk auto-creates a new user from the email address. Enable this via the "Allow All Users to Create Tickets" setting.

**Best for:** Customer-facing widgets, public support portals.

For widget users with auto-generated emails (like `unknown_ago@domain.com`), AGO collects their real email during ticket creation and uses it for the Zendesk request.

***

## Ticket Sync

AGO can sync ticket data from Zendesk back into the admin dashboard, keeping statuses, assignees, and comments up to date.

### What Gets Synced

| Zendesk Data  | AGO Field                | Notes                                               |
| ------------- | ------------------------ | --------------------------------------------------- |
| Status        | Ticket status            | Mapped to: new, open, pending, hold, solved, closed |
| Priority      | Priority                 | Updated from Zendesk                                |
| Subject       | Subject                  | Ticket title                                        |
| Description   | Body                     | First comment body                                  |
| Type          | Typology                 | question, incident, problem, task                   |
| Tags          | Tags                     | Full tag list                                       |
| Assignee      | Assignee name and email  | Who is handling the ticket                          |
| Requester     | Requester name and email | Who submitted the ticket                            |
| Custom fields | Custom fields            | Titles and values (empty/false values excluded)     |
| Comments      | Messages                 | Public and private, with sender info                |
| Attachments   | Message content          | Links appended to each message                      |

### Enabling Sync

1. Navigate to your Zendesk ticketing system configuration in the admin interface
2. Enable the **Sync Enabled** option
3. Tickets sync automatically every hour

### Manual Sync

* **Tickets list page**: Click **Sync Tickets** to sync all open tickets
* **Ticket detail page**: Click **Sync Now** to sync a single ticket immediately

### Sync Behavior

* Only open tickets with an external ID are synced (closed tickets are skipped)
* Unchanged tickets are skipped for efficiency
* Zendesk agent comments appear with the agent's name and an external system badge
* Private comments are imported as internal notes
* You can add internal notes from the AGO detail page (these stay in AGO only)
* AGO respects Zendesk API rate limits — large syncs may take several minutes

***

## Troubleshooting

| Issue                                | Cause                                          | Fix                                                                             |
| ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------- |
| "User not allowed to create tickets" | User not found or not active in Zendesk        | Add user to Zendesk or enable "Allow All Users to Create Tickets"               |
| "Zendesk configuration not found"    | Missing API credentials                        | Verify admin email, API token, and subdomain in Ticketing settings              |
| "Failed to upload file"              | File too large or network issue                | Check Zendesk file size limits; verify connectivity                             |
| Custom field not mapping             | `external_id` does not match Zendesk field     | Verify format: `ticket_field_12345` (the number is the Zendesk custom field ID) |
| Group assignment not working         | Group ID incorrect or insufficient permissions | Verify group ID in Zendesk Admin Center > People > Groups                       |

If issues persist, test with a simple ticket (no custom fields or attachments), then check AGO logs for detailed error messages.

For tips on field mapping, tag strategy, and routing, see [Ticketing Best Practices](../guides/ticketing-best-practices).

***

## Related

* [Ticketing](../features/ticketing) — Ticketing feature overview
* [Ticket Form Customization](../features/ticket-form-customization) — Form field configuration and embedded forms
* [Ticketing Connectors](../data-connector/ticketing-connectors) — Compare available connectors
* [HelpScout Integration](../data-connector/helpscout-integration) — Alternative ticketing connector
* [HubSpot Integration](../data-connector/hubspot-integration) — Alternative ticketing connector
* [Zendesk Knowledge Base](../data-connector/zendesk-integration) — Knowledge base connector (separate from ticketing)