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 confidential Zendesk OAuth client, or an existing API-token connection
• Admin access to both Zendesk and AGO

---

Connect with OAuth

1. Create a confidential OAuth client

   Follow Zendesk’s client credentials setup:

   • Set Client type to Confidential.
   • Leave Redirect URLs empty. AGO uses the client credentials flow, which does not require a redirect URL.
   • For Scopes, allow read tickets:write ticket_attachments:write users:write organizations:write, or leave the field empty.

   Copy the client ID and client secret. The client inherits its associated user’s permissions. AGO requests read access plus write access to tickets, ticket attachments, users, and organizations only.

2. Find your Zendesk subdomain

   Your subdomain is the part before .zendesk.com. For example, in https://company.zendesk.com, it is company.

3. Enter and test the credentials

   Open Tickets > Ticket Forms, select Zendesk as the Active Ticketing System, and click Configure ticketing system (the wrench beside the selector). Enter your subdomain in Zendesk domain, then enter Client ID and Client secret under OAuth. Click that section’s Test connection button.

   Testing uses your unsaved inputs and does not change the live connection. Leave a saved secret blank to keep it.

4. Save the credentials

   Click Save to activate OAuth permanently. AGO obtains and renews access tokens automatically.

Legacy API-key connections

Existing API-key connections continue to work until OAuth is activated. API-key authentication is deprecated in AGO. Use OAuth for new connections.

To switch an OAuth connection back to an API key, clear Client ID and click Save. AGO needs an Admin email and API token: keep the saved ones or enter new ones before saving. AGO removes the saved OAuth credentials.

---

Create a Ticket Form

1. Navigate to Tickets > Ticket Forms
2. Create a new form
3. Add fields and configure custom field mapping to Zendesk
4. Save the form

Zendesk-specific form properties:

Property	Description
external_id	Default Zendesk group ID; a group mapped to a selected field option takes precedence
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

To choose an AGO form automatically from tags on the Zendesk user profile, configure an ordered list of Zendesk user tags → ticket forms in each permission’s Ticket Instructions. Only the user’s highest-priority permission is checked. Its first matching row wins, after any form assigned directly to the user. See Select a Form from Zendesk User Tags.

---

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

Keep Your Native Help Center Form

Your backend can attach an existing Zendesk ticket to the AGO conversation that led to it using the Public API linking endpoint. Send the conversation UUID, ticketing_system: "zendesk" and the ticket’s external_id, authenticated with an AGO API key that has conversations:write.

Your integration must obtain the created ticket ID and verify its association with the conversation’s customer before calling AGO. Keep the API key on your server. This endpoint requires no customer Zendesk JWT and does not verify the ticket requester through Zendesk. The SDK does not provide a browser ticket-linking endpoint.

If your Help Center theme includes attachment handoff, files sent in the AGO chat are automatically added to the native request form when it opens. Review the attachment list and remove any files you do not want to send before submitting. Zendesk applies its own upload limits. If automatic transfer is unavailable, the form provides downloads of the chat files so you can add them manually. Keep the page open until you submit; chat files are not saved across page reloads.

AGO saves the ticket reference and immediately queues the standard Zendesk sync for that ticket to import the subject, description, comments, status, assignee and custom fields. This first refresh runs even when Sync Enabled is off; enable that option for ongoing hourly updates to open tickets. The response confirms the saved link before the refresh finishes. A failed sync leaves the link and original Zendesk ticket intact; repeating the same linking call requests another refresh.

Linking does not create another Zendesk ticket, run AGO’s ticket-creation triggers or add the private conversation-link comment described above. It can be used with AGO’s built-in ticket-creation tool disabled.

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 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 [e-mail]), AGO collects their real email during ticket creation and uses it for the Zendesk request.

---

Ticket Context for Agents

Enable Ticket Context in your agent’s settings to give the agent recent ticket summaries as context for its responses. AGO refreshes known Zendesk tickets before preparing the context, including tickets associated with an anonymous visitor. With a verified customer identity, AGO can also find tickets created outside AGO by matching the customer’s email.

Customer history lookup uses the email supplied by your existing authentication: Clerk, validated widget JWTs, successfully resolved authentication tokens, or your configured trusted authentication proxy. JWTs do not need an email_verified claim; if present, it must be the boolean true for wider history lookup. Without an authenticated email, AGO refreshes only tickets already associated with the visitor.

The agent receives up to ten summaries with the subject, status, update date, and ticket link. Your configured days limit still applies. Closed tickets, descriptions, replies, and private notes are excluded. Ticket links keep your configured overrides; tickets discovered only in Zendesk use your system override or a Zendesk customer request link.

Results are cached for up to one minute, and Zendesk search can take a few minutes to include new tickets. If a refresh fails, AGO keeps available stored details and tells the agent they may be out of date. This feature uses your existing Zendesk connection and does not require Sync Enabled. It refreshes conversation context without importing additional tickets into the AGO ticket list.

For anonymous visitors, entering an email address in a ticket form does not reveal other tickets belonging to that address. AGO uses the existing ticket associations for that visitor, including older tickets, and your current Zendesk connection.

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 the OAuth client ID, client secret, and Zendesk domain 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.

---

Related

• Ticketing — Ticketing feature overview
• Ticket Form Customization — Form field configuration and embedded forms
• Ticketing Connectors — Compare available connectors
• HelpScout Integration — Alternative ticketing connector
• HubSpot Integration — Alternative ticketing connector
• Zendesk Knowledge Base — Knowledge base connector (separate from ticketing)

Automatic ticket creation

In Ticketing System Configuration → Advanced, set Automatic ticket creation for your active Zendesk system:

• Disabled (default): no automatic tickets are created.
• 2, 4, 8 or 12 hours, or Every day (24 hours): create solved tickets once a conversation has been inactive for that long.

Conversations are checked every two hours after reaching the selected inactivity delay; backlogs, errors or scheduler outages can delay creation. Conversations already linked to a ticket are skipped. This selector is currently available only for the active Zendesk system. Saving Disabled stops future automatic creation; it does not delete existing tickets or disable manual creation.

Comments on auto-resolved tickets

In Ticketing System Configuration → Advanced, two independent switches control comments for Zendesk tickets created directly as solved, both automatically after inactivity and manually from a conversation:

• Public reply on auto-resolved tickets (off by default): generates a customer-facing reply from the visible conversation. Set Public reply instructions to describe the content, language and format you want, up to 10,000 characters. Leaving it blank produces a concise summary in the customer’s language. The reply is generated in Markdown and converted to HTML before sending, preserving bold text, lists, links and line breaks. Zendesk notification triggers may send it to the requester. If generation fails, AGO creates the ticket privately without publishing the transcript.
• Private conversation on auto-resolved tickets (off by default): copies the visible user and assistant conversation into numbered private comments, alongside the configured private context (which includes a link to AGO by default). Internal messages and system instructions are excluded. Enable this to include the transcript; when no public reply is sent, the initial private comment still contains the configured private context.

Long private conversations are split across several comments in order, including when a single message is too long. Each part includes a link to the full AGO conversation. AGO limits each comment body to 48,000 UTF-8 bytes and each comment request to 60,000 bytes, including JSON encoding. If Zendesk explicitly rejects a part as too large, AGO tries smaller parts. Other errors stop the copy to avoid sending a duplicate after an uncertain response. AGO attempts to add a short notice with the conversation link when the copy stops; the notice itself can also fail.

Public replies are checked again after HTML conversion. A reply exceeding 48,000 UTF-8 bytes is discarded and the ticket is created privately, so HTML is never cut mid-tag. AGO keeps the complete conversation. These options do not change ordinary escalated tickets or separately configured AI-generated internal notes.

When the private conversation switch is enabled, AGO creates and links the ticket first, then sends the conversation as private comments, whether or not a public reply is enabled. A failed copy leaves the ticket and previously accepted comments in place; it does not create another ticket. This applies to automatic and manual resolved ticket creation.