The Zendesk Playbook

Why Zendesk Is The Most Common Starting Point

Zendesk is the most common starting point for Macha customers, and the integration is the deepest in the platform — 17 tools, 8 trigger event types, image vision on attachments, custom field handling, and a built-in Help Center sync. This page covers the patterns that work and the pitfalls that catch teams out.

If you are reading this and only run agents on Zendesk: this is the page that matters most for you. If you run agents elsewhere too: many of the patterns here generalise (the role-based tool sets, the testing flow, the credential health monitoring) — Zendesk is just where the specifics are densest.

The 17 Tools At A Glance

Read tools (no confirmation):

• zendesk_get_ticket — full ticket details + conversation history
• zendesk_get_ticket_custom_fields — labelled custom field values for one ticket
• zendesk_get_ticket_fields — schema definitions for all fields
• zendesk_search_tickets — find tickets by query
• zendesk_search_users — find users by name, email, or role
• zendesk_list_groups — list all active groups for routing
• zendesk_search_articles — search Help Center articles
• zendesk_read_attachment — read PDFs, DOCX, XLSX, CSV; analyse images with AI vision

Write tools (require confirmation in chat mode, auto-approved in autonomous mode):

• zendesk_add_internal_note — private note for the team
• zendesk_add_public_reply — customer-visible reply
• zendesk_update_ticket_status — open / pending / hold / solved / closed
• zendesk_update_ticket_subject — change subject line
• zendesk_update_ticket_priority — urgent / high / normal / low
• zendesk_update_ticket_type — problem / incident / question / task
• zendesk_update_ticket_tags — add or remove tags
• zendesk_update_ticket_fields — set custom fields with validation
• zendesk_assign_ticket — assign to agent, group, or both

The Three Common Agent Roles

Most Zendesk agents on Macha fall into one of three roles. Each has a different tool set, model choice, and trigger configuration.

Role 1: The Triage Agent

Reads incoming tickets, sets priority, type, and tags, optionally routes to the right group. Read-mostly with light writes. Excellent first agent because it has high impact (saves the support team triage time on every ticket) and low risk (no customer-facing actions).

• Tools: zendesk_get_ticket, zendesk_get_ticket_custom_fields, zendesk_get_ticket_fields, zendesk_update_ticket_priority, zendesk_update_ticket_type, zendesk_update_ticket_tags, zendesk_add_internal_note
• Model: GPT-5.4 Mini — the workflow is simple categorisation, runs on every ticket, cost matters.
• Trigger: ticket.created with no extra conditions (it is meant to run on everything). Optional debounce of 5 seconds in case ticket creation events fire close together.
• Internal-notes-only mode: not strictly necessary because the agent is internal-only by design. Still worth a Test Run pass before enabling the trigger.

Role 2: The Reply Agent

Drafts customer-facing replies. The highest-leverage agent type and also the highest-risk. Always start in internal-notes-only mode for a full week.

• Tools: zendesk_get_ticket, zendesk_search_articles (or search_knowledge if you have a non-Zendesk knowledge base), zendesk_read_attachment, zendesk_add_public_reply (swap for zendesk_add_internal_note during testing).
• Model: GPT-5.4 or Claude Sonnet — quality and tone matter on customer-facing copy. Do not skimp here.
• Trigger: ticket.created with narrow conditions for the first few weeks (specific tag, specific brand). Expand only after the team is comfortable.
• Debounce: if the trigger is on messaging.customer_message instead of ticket creation, set a 15-30 second debounce so the agent batches rapid-fire customer messages.

Role 3: The Routing Agent

Looks at incoming tickets and assigns them to the right group or agent. Lighter writes than a reply agent, but higher reasoning load — the agent has to understand the ticket content well enough to pick the right destination.

• Tools: zendesk_get_ticket, zendesk_search_users, zendesk_list_groups, zendesk_assign_ticket, zendesk_add_internal_note
• Model: GPT-5 (default).
• Trigger: ticket.created filtered to unassigned tickets, or run after the triage agent has tagged the ticket.

The routing agent benefits most from the recent group-routing additions. Instead of always picking a specific human (which causes friction when that person is on holiday), the agent can assign tickets straight to a group queue. Have it call zendesk_list_groups first to learn the available groups, then use zendesk_assign_ticket with group_id, assignee_id, or both.

Custom Fields: Fetch The Schema First

Zendesk custom fields are referenced by numeric IDs that are unique per account, and dropdown fields have constrained option values. The reliable pattern is: call zendesk_get_ticket_fields first to learn the schema, then call zendesk_update_ticket_fields with the resolved IDs and validated values.

Bake this into your instructions explicitly:

"Before updating any custom field, call zendesk_get_ticket_fields to learn the field IDs and their allowed values. Never guess a field ID."

Without this rule, the agent will sometimes hallucinate IDs and the writes will fail validation. The schema is cached per connector for five minutes, so calling it on every ticket is cheap.

For tagger (dropdown) and date fields, the validation is enforced server-side — invalid values are rejected with a clear error. For free-text custom fields, validation is looser, so be more careful in your instructions about what kind of value to write.

Image Vision On Attachments

If your tickets routinely include screenshots, receipts, product photos, or scanned documents, image vision is one of the highest-impact features on Macha. The agent downloads the image, encodes it, and sends it to a vision-capable model that can describe the image in detail — read text in screenshots, identify products, parse handwritten notes, recognise UI states.

To enable: assign zendesk_read_attachment as a tool, and pick a vision-capable model (GPT-5.4, GPT-5, GPT-5.4 Mini, Claude Sonnet — Groq does not support vision). Mention attachment reading in the instructions:

"If a ticket has an image attachment, read it with zendesk_read_attachment and describe what you see in the internal note before drafting any reply. If the image shows an error message or product issue, transcribe the relevant text accurately."

Common use cases:

• Customer sends a screenshot of an error → agent reads the error text, drafts a fix.
• Customer attaches a receipt → agent extracts amount, date, order ID.
• Customer sends a photo of a damaged product → agent describes the damage, opens a return.
• Customer sends a screenshot of unclear UI → agent describes what the customer is looking at, drafts a clarification.

Help Center As A Knowledge Source

If your team has a Zendesk Help Center, sync it to Macha as a knowledge source. The articles get embedded and become searchable via zendesk_search_articles, with live webhook updates whenever an article is published or edited.

Reply agents that draw on existing Help Center content are dramatically better than ones that improvise — they cite real policy, stay consistent with what is already published, and the team's existing content investment is leveraged. If you have spent years writing Help Center articles, this is how you turn that investment into agent quality.

Practical tip: link your reply agent's instructions explicitly to the Help Center search:

"Before drafting any reply, search the Help Center with zendesk_search_articles for any article relevant to the customer's question. Cite the article in your reply with a link. If no relevant article exists, draft the reply but add an internal note suggesting we should write one."

Multi-Instance Setups

If your organisation has multiple Zendesk accounts (e.g. a production account and a sandbox, or separate accounts for different brands), you can connect both as separate instances. Macha auto-disambiguates the tool names: zendesk_get_ticket on the production instance becomes zendesk_get_ticket__production, and the sandbox version becomes zendesk_get_ticket__sandbox (the suffix is the instance name in lowercase).

When building agents for multi-instance setups, be explicit in the instructions about which instance the agent should use, and double-check the tool list on the agent — it is easy to accidentally pick a tool from the wrong instance, especially if both instances have similar names.

Messaging vs Ticketing Channels

Zendesk Messaging (WhatsApp, Messenger, Instagram, web chat, etc.) and traditional ticketing have very different rhythms. Messaging is rapid back-and-forth — set a debounce of at least 15 seconds on the messaging.customer_message trigger so the agent batches the customer's messages instead of firing on each one.

Reply tone also differs significantly. Messaging customers expect short, conversational replies — usually one or two sentences. Ticketing customers expect more thorough, structured ones — usually paragraphs with greetings and sign-offs. If you are running both, build two reply agents with different instructions rather than trying to make one agent handle both. The duplication of work is small; the quality gain is large.

Trigger Setup Patterns

The most common Zendesk trigger event types and what they are good for:

• ticket.created — fires on the first customer message, before any agent replies. Best for triage, routing, and initial reply agents.
• ticket.comment_added — fires on every new comment. Use sparingly — without narrow conditions this fires too often. Best when filtered to specific tags or follow-up workflows.
• ticket.status_changed — fires when status changes. Useful for "when a ticket is solved, send a CSAT survey" patterns.
• ticket.priority_changed — fires when priority changes. Useful for "when escalated to urgent, page on-call" patterns.
• ticket.assigned — fires when a ticket gets assigned. Useful for "when assigned to me, summarise the conversation" patterns (where "me" is a specific group or agent).
• messaging.customer_message — fires on every customer message in a Zendesk Messaging conversation. Always use debounce.
• custom.webhook — generates a webhook URL you attach to any Zendesk trigger you set up in Zendesk's own UI. Maximum control over which tickets fire.

The "Custom Webhook" Pattern For Maximum Control

For agents that should only fire on a very specific subset of tickets — say, tickets in a particular brand, with a particular tag, from a particular form — the custom webhook trigger is often easier than trying to filter at the Macha level.

The flow: create a Macha custom webhook trigger (gets a URL + signing secret). In Zendesk, create a native Zendesk trigger with whatever conditions you want. Set the action to "Notify webhook" and point it at the Macha URL. Now you have full Zendesk-trigger-level control over conditions, with Macha doing the work.

Common Zendesk Pitfalls

• Closed tickets are immutable. Once a Zendesk ticket is closed, no further updates work — replies, tags, status changes all fail. If your agent needs to follow up later, prefer the solved status (which is reversible) over closed. Bake this into instructions: "Never close a ticket. Mark as solved instead."
• Public replies cannot be edited or deleted. Once zendesk_add_public_reply fires, the customer has seen it. This is why the internal-notes pattern matters so much during testing.
• Tags are global. Adding a tag to one ticket does not change it on others, but the tag itself is created at the account level. Avoid generating dynamic tags from ticket content (e.g. customer-name-as-tag) — you will pollute your tag namespace with thousands of one-off tags.
• Custom field options are per-account. Dropdown options that exist on your sandbox may not exist on production. The schema-fetch-first pattern catches this; instructions should require the schema lookup before any custom field write.
• Group routing requires the group to exist. Have the agent call zendesk_list_groups rather than guessing a group name from the ticket content. Hallucinated group names produce 404s.
• Webhook signatures must validate. If you see triggers being rejected with 401 errors, check that your Zendesk webhook secret matches what Macha provisioned. The setup modal shows the expected configuration.
• OAuth tokens can expire. If your Zendesk OAuth connection breaks, agents using Zendesk tools get auto-deactivated. You will get an email; reconnect from the Connectors page.
• Sunshine Conversations needs separate setup. If you use Zendesk Messaging via Sunshine Conversations, the conversation history reads via a different API. This is handled internally, but it requires the Sunshine credentials in your Zendesk integration setup.

The Zendesk-Specific Pre-Launch Checklist

Before enabling any Zendesk trigger:

• The connector is connected and the test endpoint passes.
• The agent has both read and write tools — never just one.
• Custom field updates require zendesk_get_ticket_fields as a prerequisite tool.
• Routing agents have zendesk_list_groups if they assign by group.
• Reply agents start in internal-notes-only mode (swap zendesk_add_public_reply for zendesk_add_internal_note).
• The trigger conditions are narrow enough that you would be willing to receive a notification on every fire.
• If using messaging.customer_message, debounce is set to at least 15 seconds.
• Instructions explicitly forbid closing tickets (use solved instead).
• You have run at least 10 Test Run cases including edge cases.
• You have a calendar reminder to check the agent's history on day 1, day 3, and day 7.