insonl
← journal

What an AI Assistant Should Pass to a Zendesk Agent

date
21 November 2026
by
Insonl
read
7 min read

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:

  1. Intent. One normalized intent code for routing and reporting, plus a one-sentence request summary.
  2. 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.
  3. 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.
  4. 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. Use tagger (dropdown) for intent and stop codes, checkbox for binary checks, and lookup to 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_portal and editable_in_portal are true, and GET /api/v2/ticket_fields returns visible_in_portal: true fields to end users. Set visible_in_portal: false and editable_in_portal: false on internal AI fields, and document codes in agent_description.
  • Stay within field and tag limits. Zendesk recommends at most 400 ticket fields per account (or per ticket form) and enforces two multi_lookup fields 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> -&gt; <code>packed_for_dispatch</code><br>2. <code>06:14:07Z</code> <code>carrier.get_scans</code> -&gt; empty (no pickup scan)<br>3. <code>06:14:09Z</code> <code>policy.check_cancel_allowed</code> -&gt; 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:

  1. Tag overwrites, collisions, and closed tickets. Passing tags on update replaces existing tags; append via PUT /api/v2/tickets/{ticket_id}/tags (Add Tags) or additional_tags/remove_tags in Update Many Tickets. Guard single-ticket writes with safe_update: true and updated_stamp (from updated_at): a stale timestamp returns HTTP 409 Conflict ("error": "UpdateConflict"), whereas asynchronous bulk/batch jobs report "UpdateConflict" in job_status. On single-ticket updates, "safe_update": false acts like true—omit it only for an unsafe write; bulk/batch jobs always perform safe updates. Dedicated Add/Set/Remove Tags endpoints cannot edit closed tickets; Tag Endpoint Limitations point closed-ticket tag updates to Update Many Tickets with additional_tags/remove_tags.
  2. Sticky visibility and agent placeholder stripping. Per Ticket Comments, the initial public value persists unless changed—always pass "public": false on internal notes and "public": true on public replies. Placeholder evaluation applies to agent-authored comments; end-user-authored comments (like Step 1 when submitter_id is the requester) treat placeholders as literal text (Requesters and submitters). On agent notes, unsupported {{...}} tokens strip: wrap literal braces in <code>{{...}}</code> inside html_body, or use Zendesk’s documented \\{{...}} escape in decoded body text (\\\\{{...}} in a JSON string).
  3. 64kB truncation, attachment security, and shared update limits. Per Body size limits, comment bodies truncate past 64kB with no error. When attaching long transcripts via comment.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 at 5000 comments (422 thereafter), and per Endpoint rate limits, the 30-updates-per-10-minutes per-(User + Ticket) limit counts every request saving the same ticket—including tag updates—alongside a separate account-level quota (100 requests/min per account, or 300 with High Volume add-on; 429 Too Many Requests, shown in Zendesk-RateLimit-tickets-update).
  4. Formatting, author, and side-effect traps. body strips HTML, collapses spaces/newlines, and renders Markdown only for agent comments—use html_body for structured notes. comment.author_id sets the displayed author, while the authenticated API user stays the ticket updater for triggers and views. description is silently ignored on update, email_ccs are not updated alongside an internal note, and comment order is not guaranteed if triggers add an internal note on creation.
  5. Custom-field formats and audit metadata limits. Per Setting custom field values, tagger expects option tag names (not display text), multiselect takes an array of tag names, date takes an ISO 8601 date without time, and lookup takes a record ID or "external_id:<identifier>". Audit metadata caps at 1 kB, 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