How to set up an AI agent in Zendesk: a complete walkthrough
Most teams who try AI agents in Zendesk give up during setup. Not because the AI is bad — because the setup flow assumes you already know how AI agents work. Here's what it actually takes, end to end.
Most teams who try AI agents in Zendesk give up during setup. Not because the AI is bad — because the setup flow assumes you already know how AI agents work. Here's what it actually takes, end to end. No code, six decisions, and you can be live in under 30 minutes.
Why bother with an AI agent in Zendesk
Look at your last 100 tickets. Roughly 30–50% of them are some variation of the same handful of questions: where's my order, can I get a refund, how do I reset my password, do you ship to my country. These are repetitive. They drain your team. They don't benefit from human empathy because the customer just wants an answer.
An AI agent that handles even half of that volume frees your team to focus on the genuinely hard tickets — the ones where judgment, empathy, and context matter. That's the whole pitch.
"Setup" sounds intimidating, but it's really six decisions: which account to connect, which model to use, what instructions to give the agent, what knowledge to give it, when to fire it, and how to test it before going live. Let's walk through each.
Step 1: Connect Zendesk to Macha
This is where most guides drop you in the weeds. We won't.
OAuth has been the default since April 2026 — Zendesk's global OAuth client is approved, so you just click Connect, sign in, authorize, and you're done. Tokens refresh automatically; you'll never deal with expiry.
If you're on a legacy Zendesk subdomain or want to test with a sandbox, the API key path is still there. You'll need a subdomain + an admin-generated token. Either method takes under a minute.
One thing teams miss: you can connect multiple Zendesk accounts. If you run support for two brands on separate subdomains, name each connector instance (e.g., "Zendesk — Brand A", "Zendesk — Brand B"). Tools auto-disambiguate so your agent knows which one to use.
Step 2: Choose your AI model
Macha gives you a model picker per agent. Defaults:
- GPT-5 (3 credits per message) — the current default. Strong reasoning, 1M context window, handles complex multi-step workflows well. Start here.
- GPT-5.4 (5 credits) — when accuracy matters more than cost. Best for high-stakes tickets like cancellations, billing disputes, or anything customer-facing where a wrong answer hurts.
- GPT-5.4 Mini (1 credit) — for high-volume, lower-stakes work. Fast, cheap, capable. Great for triage, classification, and first-pass replies before a human reviews.
- Claude Sonnet 4.5 (9 credits) — when you need long-form, nuanced reasoning. Slower and pricier; reserve for complex agents.
Practical advice: start with GPT-5 for your first agent. After a week, look at the conversation logs. If the model is over-spec'd for the work (most tickets resolved trivially), move to GPT-5.4 Mini for the cost win. If it's under-spec'd (wrong answers, missed nuance), bump to GPT-5.4. The cluster post on choosing the right AI model has the full decision framework.
Step 3: Write the agent's instructions
This is the highest-leverage decision in the whole setup. The instructions are the agent's brain — they define what it does, what it doesn't do, and how it makes judgment calls.
Write them like you'd write onboarding notes for a new hire:
You're a customer support agent for [Brand]. When a customer asks about their order, look up the order in Zendesk and explain the current status. If the customer asks for a refund under $50, process it without escalation. If over $50, escalate to the team by adding a private note tagged "refund-review".
Always search the Help Center first before answering. If no article matches, look at the customer's previous tickets for context.
Tone: friendly but direct. Use the customer's name. Sign off with "Macha Support" but don't use exclamation marks.
Don't write code. Don't write pseudo-code. Write plain English rules. Keep it under 500 words. You can edit and iterate later — and Macha's AI Agent Builder will help refine the instructions through conversation if you'd rather start that way.
Step 4: Add Help Center as a knowledge source
This is where most setups go wrong: skipping the knowledge base. An agent without knowledge just makes things up. An agent with knowledge cites your existing articles.
Click "Add knowledge source" → pick Zendesk Help Center → done. Macha indexes every published article and auto-syncs new articles via webhook within seconds of publish. If you unpublish, the article is deactivated, not deleted.
Search is hybrid (vector similarity + keyword), which means the agent finds the right article even when the customer's wording is nothing like the title. There's no manual re-training when you update docs. See the deep-dive on how Help Center auto-sync works if you want to understand what's happening underneath.
Step 5: Set up the trigger
The trigger decides when the agent runs. The most common choice — and the one that gives the highest leverage — is Ticket Created: every new ticket fires the agent, which reads the ticket, searches the knowledge base, and replies (or escalates) within seconds.
Other trigger options:
- Comment Added — agent reacts when a customer replies, useful for keeping conversations moving
- Status Changed — fires on solved/pending transitions, useful for satisfaction follow-ups
- Custom Webhook — wire any external system to trigger the agent
The autonomous triggers guide covers the trigger setup in depth, including how to handle the first 24 hours of monitoring before you trust the agent to run unsupervised.
Step 6: Test before going live
Don't skip this. Use Test Run from the agent configuration page. Macha lets you pull a real ticket from your queue and run the agent against it in a sandboxed conversation. You'll see exactly what tools the agent calls, what knowledge it searches, and what reply it would have posted — without actually touching the live ticket.
Run it on 5–10 tickets covering the range of cases you expect. Tune the instructions, re-test, repeat. This is the difference between an agent that works on day one and an agent that takes weeks to debug.
What good looks like 24 hours later
If setup goes well, here's what you should see in your first day:
- 40–60% of new tickets resolved without a human, primarily on the repetitive categories (order status, refund eligibility, basic how-tos)
- Average first-response time drops to seconds for the auto-resolved tickets
- Your team picks up the harder 40% — the escalations, the edge cases, the angry customers who need a human
- CSAT holds steady or improves — customers prefer a fast accurate answer to a slow human one
If the agent is over-replying when it shouldn't, tighten the instructions. If it's escalating too much, loosen them. The first week is iteration; by week two you'll have an agent that earns its keep.
Ready to set it up?
Plans start at $299/month (Starter — 3,000 credits, ~3,000 GPT-5 messages). The Professional plan at $699/month gives you 10,000 credits, 25 agents, and scheduled triggers. See full pricing, or install Macha for Zendesk from the marketplace and start your first agent today.
