When a team puts a generative AI assistant in front of Zendesk Support, a transcript-only handoff—leaving Zendesk AI escalation ticket fields blank while dumping raw chat into one comment—forces the agent to skim the log, re-ask for an order number, and repeat lookups.
Start with a four-part handoff record—intent, verified facts, prior actions, and escalation reason—mapped to the Zendesk surfaces built for each part.
Drawing on Zendesk’s third-party docs (not an Insonl client)—Tickets, Ticket Comments, Ticket Fields, Tags, Ticket Audits, Creating and updating tickets, Rate limits, and Configuring attachment security—this post defines that record, walks through a made-up escalation payload, and flags API behaviors that drop or expose context.
Define a four-part handoff record before touching Zendesk
A transcript records conversation, not agent-ready state. Before wiring CRM and ticketing workflows, require four blocks on every escalation:
- Intent. One normalized intent code for routing and reporting, plus a one-sentence request summary.
- Verified facts versus claimed facts. Separate data confirmed against a system of record or authenticated session (account ID, order status, payment state) from unverified text typed in chat.
- Prior actions. An ordered list of every lookup, policy check, or attempted mutation—with timestamp and outcome—so agents do not repeat checks or issue duplicate refunds.
- Reason for escalation. Closed stop codes (
policy_blocked,identity_unverified,tool_timeout,low_confidence,customer_requested_human) instead of free prose—the same boundary scoping needed in AI customer enquiry automation.
If the assistant cannot emit these blocks reliably, fix tool logging and schemas upstream first.
Mapping the handoff record to Zendesk AI escalation ticket fields
Zendesk’s Tickets API splits ticket state across standard fields, custom fields, comments, tags, and audit metadata:
| Handoff element | Zendesk destination | Why it fits | Where it does not fit |
|---|---|---|---|
| Requester, queue, urgency, session link | Standard fields (requester_id/requester, group_id, priority, type, status, support_type, external_id, subject) |
Native assignment and SLAs; external_id links to the local AI session. |
Do not bury routing codes or session IDs only in subject. |
| Intent, escalation reason, verification flag, record ID | Custom fields (custom_fields via tagger, checkbox, text, date, or lookup) |
Drives views, triggers, and reporting; hidden from end users only when configured with visible_in_portal: false. |
Do not put multi-step logs or raw JSON in textarea fields. |
| Verified vs. claimed facts, prior actions, summary | Private comment (comment with "public": false and html_body) |
Agent-only comment formatted cleanly in Agent Workspace. | Never put internal traces in public comments or past 64kB. |
| Customer’s actual request | Requester’s public comment (comment with "public": true) |
Matches Tickets vs. Requests—end users see public comments. | Never expose confidence scores, rule codes, or backend errors. |
| Coarse workflow flags | Ticket tags (Add Tags or additional_tags) |
Lightweight trigger markers when a custom field is unnecessary. | Never emit high-cardinality tags or reuse custom-field tags. |
| Machine correlation (schema or build) | Audit metadata (write-only on create/update) |
Keeps up to 1 kB of custom JSON on the audit off agent UI. |
Not an editable agent field; never store resolution facts here. |
Three documented rules in Ticket Fields constrain custom fields:
- Choose types once. Field
type(text,textarea,checkbox,date,integer,decimal,regexp,partialcreditcard,multiselect,tagger,lookup,multi_lookup) is editable only on creation. Usetagger(dropdown) for intent and stop codes,checkboxfor binary checks, andlookupto reference a user, organization, ticket, or custom object (zen:custom_object:{key}). - Configure portal visibility explicitly. Custom fields are not inherently agent-only: a field shows on the Help Center request form when both
visible_in_portalandeditable_in_portalaretrue, andGET /api/v2/ticket_fieldsreturnsvisible_in_portal: truefields to end users. Setvisible_in_portal: falseandeditable_in_portal: falseon internal AI fields, and document codes inagent_description. - Stay within field and tag limits. Zendesk recommends at most
400ticket fields per account (or per ticket form) and enforces twomulti_lookupfields per account on creation. Tags cannot be reused across custom fields—reuse is not validated and can block future edits.
Worked example: a made-up escalation payload
(Illustrative example—not a real company, customer, order, or Insonl client. All IDs, order numbers, timestamps, and session IDs below are made up.)
Suppose an authenticated shopper asks an AI assistant to cancel and refund delayed order ORD-2026-88412. The assistant checks the order system (packed_for_dispatch, blocking auto-cancel), checks carrier scans, and stops without changing the order.
Because POST /api/v2/tickets takes one comment object, separating the customer’s public request from the private note takes two calls. This example assumes custom fields 310001–310004 use visible_in_portal: false and editable_in_portal: false.
Step 1: Create the ticket (POST /api/v2/tickets)
Setting submitter_id equal to requester_id makes the customer the first comment author (omitting it defaults to the authenticated API user). support_type: "ai_agent" records AI handling, external_id links the session, and field 310002 carries the declared policy_blocked stop code.
{
"ticket": {
"subject": "Cancel and refund delayed order ORD-2026-88412",
"requester_id": 901284,
"submitter_id": 901284,
"group_id": 44012,
"priority": "normal",
"type": "incident",
"status": "open",
"support_type": "ai_agent",
"external_id": "ai_sess_7f3a91c0",
"custom_fields": [
{ "id": 310001, "value": "intent_order_cancel_refund" },
{ "id": 310002, "value": "policy_blocked" },
{ "id": 310003, "value": true },
{ "id": 310004, "value": "ORD-2026-88412" }
],
"tags": ["ai_escalated"],
"metadata": {
"handoff_schema": "v1",
"assistant_build": "support-router-2026-11-18"
},
"comment": {
"public": true,
"body": "My order ORD-2026-88412 has been stuck for two days. Please cancel it and refund my card."
}
}
}
Step 2: Append the private handoff note (PUT /api/v2/tickets/{ticket_id})
Using id and updated_at from Step 1, the service appends an internal note ("public": false) via html_body (recommended for Agent Workspace in Ticket Comments), with updated_stamp and safe_update: true. Long transcripts can attach via comment.uploads only if the account’s attachment security settings protect downloads.
{
"ticket": {
"updated_stamp": "2026-11-21T06:14:22Z",
"safe_update": true,
"comment": {
"public": false,
"html_body": "<p><strong>AI Handoff</strong> (<code>ai_sess_7f3a91c0</code>)</p><p><strong>Intent:</strong> Cancel and refund (<code>intent_order_cancel_refund</code>)<br><strong>Reason:</strong> <code>policy_blocked</code> (auto-cancel blocked once <code>packed_for_dispatch</code>)</p><p><strong>Verified (OMS + carrier + SSO):</strong> requester <code>901284</code>; <code>ORD-2026-88412</code> <code>packed_for_dispatch</code> since <code>2026-11-21T05:40:00Z</code>; <code>carrier.get_scans</code> returned no pickup scan at <code>06:14:07Z</code>.<br><strong>Claimed:</strong> Customer reported order stuck for two days and asked to cancel and refund their card; eligibility needs agent review.</p><p><strong>Prior actions:</strong><br>1. <code>06:14:05Z</code> <code>oms.get_order</code> -> <code>packed_for_dispatch</code><br>2. <code>06:14:07Z</code> <code>carrier.get_scans</code> -> empty (no pickup scan)<br>3. <code>06:14:09Z</code> <code>policy.check_cancel_allowed</code> -> denied (<code>NO_AUTO_CANCEL_AFTER_PACK</code>)<br>4. No cancel or refund executed.</p>"
}
}
}
With "public": false on Step 2 and visible_in_portal: false on custom fields, internal rule codes stay off the requester’s thread; if a transcript is also attached via uploads, enable secure downloads so attachment URLs require sign-in.
Zendesk API edge cases that break AI escalations
Five documented behaviors cause silent data loss or leaks if unguarded:
- Tag overwrites, collisions, and closed tickets. Passing
tagson update replaces existing tags; append viaPUT /api/v2/tickets/{ticket_id}/tags(Add Tags) oradditional_tags/remove_tagsin Update Many Tickets. Guard single-ticket writes withsafe_update: trueandupdated_stamp(fromupdated_at): a stale timestamp returns HTTP409 Conflict("error": "UpdateConflict"), whereas asynchronous bulk/batch jobs report"UpdateConflict"injob_status. On single-ticket updates,"safe_update": falseacts liketrue—omit it only for an unsafe write; bulk/batch jobs always perform safe updates. DedicatedAdd/Set/Remove Tagsendpoints cannot editclosedtickets; Tag Endpoint Limitations point closed-ticket tag updates toUpdate Many Ticketswithadditional_tags/remove_tags. - Sticky visibility and agent placeholder stripping. Per Ticket Comments, the initial
publicvalue persists unless changed—always pass"public": falseon internal notes and"public": trueon public replies. Placeholder evaluation applies to agent-authored comments; end-user-authored comments (like Step 1 whensubmitter_idis the requester) treat placeholders as literal text (Requesters and submitters). On agent notes, unsupported{{...}}tokens strip: wrap literal braces in<code>{{...}}</code>insidehtml_body, or use Zendesk’s documented\\{{...}}escape in decodedbodytext (\\\\{{...}}in a JSON string). 64kBtruncation, attachment security, and shared update limits. Per Body size limits, comment bodies truncate past64kBwith no error. When attaching long transcripts viacomment.uploads, check Configuring attachment security: with secure downloads off, regular attachment URLs use a random token that anyone holding the URL and token can open. Never post one comment per bot turn: tickets cap at5000comments (422thereafter), and per Endpoint rate limits, the30-updates-per-10-minutesper-(User + Ticket)limit counts every request saving the same ticket—including tag updates—alongside a separate account-level quota (100requests/min per account, or300with High Volume add-on;429 Too Many Requests, shown inZendesk-RateLimit-tickets-update).- Formatting, author, and side-effect traps.
bodystrips HTML, collapses spaces/newlines, and renders Markdown only for agent comments—usehtml_bodyfor structured notes.comment.author_idsets the displayed author, while the authenticated API user stays the ticket updater for triggers and views.descriptionis silently ignored on update,email_ccsare not updated alongside an internal note, and comment order is not guaranteed if triggers add an internal note on creation. - Custom-field formats and audit metadata limits. Per Setting custom field values,
taggerexpects option tag names (not display text),multiselecttakes an array of tag names,datetakes an ISO 8601 date without time, andlookuptakes a record ID or"external_id:<identifier>". Auditmetadatacaps at1kB, is dropped unless a ticket property changes, and reading it via Ticket Audits requires a global"read"OAuth scope ("tickets:read"and"auditlogs:read"are not accepted).
Audit your support escalation workflow before adding more automation
Insonl is a Ho Chi Minh City engineering studio building CRM and ticketing integrations and generative AI pipelines. If your agents still read raw transcripts or repeat lookups on escalated tickets, start with our free AI workflow audit (see what our AI workflow audit covers).
The audit is free; work after it is quoted separately.
Sources
- Zendesk Developer Docs (third-party docs), Tickets — Ticketing API Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/
- Zendesk Developer Docs (third-party docs), Ticket Comments — Ticketing API Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/
- Zendesk Developer Docs (third-party docs), Ticket Fields — Ticketing API Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/
- Zendesk Developer Docs (third-party docs), Tags — Ticketing API Reference: https://developer.zendesk.com/api-reference/ticketing/ticket-management/tags/
- Zendesk Developer Docs (third-party docs), Ticket Audits — Ticketing API Reference: https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_audits/
- Zendesk Developer Docs (third-party docs), Creating and updating tickets — Ticketing Developer Guide: https://developer.zendesk.com/documentation/ticketing/managing-tickets/creating-and-updating-tickets/
- Zendesk Developer Docs (third-party docs), Rate limits — API Reference: https://developer.zendesk.com/api-reference/introduction/rate-limits/
- Zendesk Help Center (third-party docs), Configuring attachment security: https://support.zendesk.com/hc/en-us/articles/11348969859994-Configuring-attachment-security
- Insonl: CRM Solutions · Generative AI · Free AI workflow audit · AI Customer Enquiry Automation in Vietnam · AI Workflow Audit: What It Covers and How to Run One
