Working With Zendesk Custom Fields in AI Agents (Labels, Not Raw IDs)

Here's the catch most people hit on day two: Zendesk doesn't hand those fields back in a form an AI model can use. A ticket's custom_fields come out as raw numeric IDs paired with raw values — field_1900003089273: 013724827106 — with no hint of what the field is called. The agent sees a long number and a string and has no idea that one is an order number and the other is a German label for it. This post is about that specific gap, why it exists in Zendesk, and how Macha's Get Ticket Custom Fields tool closes it by resolving every field to its human label before the model ever reads it.

What Zendesk actually returns

When you fetch a ticket through the Zendesk API, custom fields come back like this (trimmed):

"custom_fields": [
  { "id": 1900003089273, "value": "013724827106" },
  { "id": 1900002847112, "value": "vip" },
  { "id": 1900002901559, "value": "de" }
]

That's it. An id and a value. No title, no type, no options. Zendesk's own ticket object reference confirms the shape: each entry "specifies a field ID and its value." The friendly name you gave the field in the admin panel — "Order number", "Account tier", "Language" — is nowhere in the ticket payload.

To get the names, you have to call a second, separate resource: the Ticket Fields API, which returns the schema — id, title, type, and (for drop-downs) the list of options. Only by joining the two can you turn 1900003089273 into "Order number."

There's a second twist for drop-down, multi-select, and checkbox fields. Those store the raw tag value of the selected option, not the label the customer saw. Zendesk's own docs note that these field types "generate tags" — so a field whose options read "Standard / Express / Overnight" might come back as shipping_overnight. The model reading that has to guess what it means.

So a faithful, model-ready view of one ticket's custom fields needs three joins: ID → title (field schema), raw value → option label (field schema again, for choice fields), and ideally a skip of any empty fields so the model isn't drowning in nulls. That is exactly the plumbing you don't want to hand-build inside every agent prompt.

Why ID-first approaches don't scale for agents

If you've followed the existing guides on this — the eesel custom ticket fields walkthroughs or community write-ups like internalnote's "Working with custom fields in Zendesk Messaging and AI Agents" — you'll notice they're all ID-first. The standard advice is to hard-code a reference like zen:ticket_field:7662882404114 and assume you already know that number. That works for a single static automation. It falls apart for AI agents for a few reasons:

• You have to look up every ID by hand. Each field is a trip to Admin Center → Ticket fields → copy the number out of the URL. Miss one and the agent is blind to it.
• The model reasons over labels, not numbers. An LLM handles "Account tier: VIP" beautifully. Feed it "1900002847112: vip" and you've thrown away the part it needs to reason — the field's meaning — and kept the part it can't use.
• It breaks when fields change. Someone renames a field, adds a drop-down option, or spins up a new form, and your hard-coded ID list is silently stale.
• It doesn't generalize across brands. Multi-brand Zendesk instances have overlapping but non-identical field sets; a fixed ID list can't follow.

For a workflow that's supposed to read whatever ticket lands in front of it, "memorize the IDs" is the wrong primitive.

How Macha's Get Ticket Custom Fields tool works

Macha is an AI agent layer that sits on top of your existing Zendesk — it doesn't replace the helpdesk, it reads from and writes to it through tools. One of those tools, shipped in the April 17 release, is Get Ticket Custom Fields, and it does the join for you.

When an agent calls it, the tool fetches the ticket's custom field values and the connector's field schema, then returns every populated field as a clean label-and-value pair. Instead of this:

field_1900003089273: 013724827106
field_1900002847112: vip
field_1900002901559: de

the model sees this:

Order number (Bestellnummer): 013724827106
Account tier: VIP
Language: German

The title comes straight from your Zendesk field schema, so it always matches whatever you named the field — including non-English labels like Bestellnummer. No mapping table, no per-agent configuration, no IDs in your prompt.

A couple of design details worth knowing:

• Schema caching. Field definitions are cached per connector for five minutes, so the schema fetch happens once per connector window rather than on every single ticket. On a busy queue that's the difference between one schema call and thousands.
• Read, not write. Get Ticket Custom Fields is a read tool — safe to enable on any agent. When you need to write a value back, that's the separate Update Fields tool, which validates against the schema (drop-down options are checked, dates are formatted) so the agent can't push a value Zendesk would reject.

What this unlocks in practice

Once the agent can read fields by label, the field data becomes a first-class input to routing, replies, and downstream tool calls. A few patterns this enables directly:

• Order lookups that just work. An agent handling a where-is-my-order question reads the Order number field by name and passes it straight to a Shopify or Stripe lookup — no regex on the message body hoping the customer typed it.
• VIP-aware triage. A ticket-triage agent reads Account tier: VIP and routes or prioritizes accordingly, then uses Macha's other Zendesk tools (Assign Ticket, Update Priority) to act on it.
• Language-correct replies. The Language field tells the agent to answer in German before it writes a word.
• Cleaner escalations. When an agent escalates with a context bundle, labelled fields make the internal note readable by a human instead of a wall of numbers.

The common thread: the agent reasons over what your fields mean, because it's reading what they're called.

Watch-outs and when this isn't the answer

This tool solves one specific problem well. It's worth being clear about its edges.

• It reads, it doesn't reconcile. If your field schema itself is messy — three near-duplicate "Order #" fields from different forms — labels will be clearer than IDs, but they won't be clean. Resolving labels doesn't fix a sprawling field taxonomy; you still want to tidy that up in Zendesk.
• Empty fields aren't context. The tool returns populated fields; if a value was never set on the ticket, there's nothing to resolve. An agent can't read a field the workflow never filled in.
• Five-minute cache, by design. If you rename a field mid-shift, the new title can take up to five minutes to appear in agent output as the per-connector cache expires. That's a deliberate performance trade, not a bug — but worth knowing if you're testing a freshly renamed field.
• Reading isn't writing. Get Ticket Custom Fields never changes a ticket. If your goal is to populate a field from a conversation, reach for Update Fields instead — and gate it with a confirmation in chat mode before it goes autonomous.
• System fields vs custom fields. Status, priority, type, tags, subject and requester aren't custom fields — they come through other Zendesk tools (Get Ticket, Update Status, Update Priority). This tool is specifically for the custom fields your team defined.

If all you ever need is one fixed field on one fixed automation, a hard-coded ID in a native trigger is genuinely fine. The label-resolution approach earns its keep the moment an agent has to read whatever fields happen to be on whatever ticket arrives — which is most agent work.

FAQ

Why doesn't Zendesk just return the field names? Performance and normalization. The ticket object stores only the field ID and value; the names, types, and options live once on the Ticket Fields schema so they aren't duplicated onto every ticket. It's clean database design — it just means a consumer has to do the join, which is what Macha's tool handles.

How does the agent know what field_1900003089273 is called? Macha's Get Ticket Custom Fields tool fetches your connector's field schema and resolves each ID to its title (and each drop-down value to its option label) before the model reads it. You never type an ID.

Can the agent update a custom field, not just read it? Yes — that's the separate Update Fields tool. It validates against the field schema (checks drop-down options, formats dates) so the agent can't write a value Zendesk would reject. Keep it behind a confirmation step until you trust the flow.

Does this work with drop-down and multi-select fields? Yes. Those are the fields most prone to returning a raw tag like shipping_overnight instead of "Overnight," so resolving them to their option labels is exactly where this helps most.

Do I need to configure field mappings per agent? No. There's no mapping table to maintain — the tool reads your live Zendesk field schema, so renamed and newly added fields show up automatically (within the five-minute cache window).

Try it

If your agents are reading order numbers off the subject line because the custom fields come back as numbers, this is the fix. Start a 7-day free trial, no credit card required, connect Zendesk, and turn on Get Ticket Custom Fields for one agent — see the Zendesk integration page for the full action set, or the docs for setup. Macha runs on top of the Zendesk you already use; nothing about your fields, forms, or automations has to change.

Pricing is credit-based — you pay per AI action, default GPT-5.4 Mini at 1 credit per message — with no per-resolution surcharge. See the pricing page for current plans.

Written by Abbas (Customer Support & AI, Macha) · Reviewed by Ankeet Guha (Co-founder & CTO) · Published 2026-06-24 · Last updated 2026-06-24.