# Connecting an AI Agent to Zendesk: Tickets, Macros, Help Center

> A trigger fires a webhook when a matching ticket arrives, your agent reads the ticket, its comments and relevant Help Center articles through the API, and writes a suggestion back as an internal note. Public replies stay with a human until the suggestions have proven reliable.

Canonical URL: https://www.ruebstudio.de/en/guides/ai-agent-integrations/connect-ai-agent-zendesk  
Author: Dr.-Ing. Marcus Rüb, CEO  
Published: 2026-11-10

For many support teams, Zendesk is where every customer request ends up: a ticket with a history, fields, tags and an owner. If you introduce your own AI agent, that is the place to plug it in rather than adding yet another tool next to it. This guide covers the interfaces Zendesk offers for this, how the pieces fit together and where the limits are. All API details refer to the Zendesk developer documentation as of November 2026.

## What does connecting an AI agent to Zendesk actually mean?

A connected agent is a separate service that runs outside Zendesk. Zendesk calls it when a ticket is created or updated, the agent reads the ticket and the relevant knowledge, and it writes its result back. Zendesk remains the system of record. The agent assists; it does not decide on its own unless you explicitly allow it to.

Typical jobs for such an agent:

- **Draft replies:** propose an answer for the customer, grounded in Help Center articles and similar solved tickets.
- **Classify:** detect category, priority, language or product and set a tag or field.
- **Summarise:** condense a long back-and-forth into a few lines before the ticket moves to another group.
- **Look things up:** pull a serial, order or contract number from the ticket and check it against other systems.

Zendesk sells its own [AI Agents](https://www.zendesk.de/service/ai/ai-agents/), which the vendor says are part of its Suite and Support plans. Building your own makes sense when you want control over the model, the data and the logic: for example, when answers depend on knowledge in an ERP, a PLM system or file shares that never reaches Zendesk, or when the model has to run in your own data centre. For the business side of what a support agent can do, see the overview of [AI customer service agents](https://www.ruebstudio.de/en/guides/ai-agents-by-department/ai-customer-service-agent-b2b). This article is about the Zendesk plumbing.

## How does the integration work? Four building blocks

There are four parts: a trigger that decides when the agent runs, a webhook that tells your service about the ticket, the Ticket API for reading and writing, and the Help Center as the knowledge source. All four are documented and available without an add-on product.

### Triggers: deciding when the agent runs

[Triggers](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/) are evaluated on every ticket create and update. Each one has conditions (grouped as `all` and `any`) and actions. Zendesk checks triggers in order of their `position`, and one trigger's actions can change whether a later trigger matches. Keep the conditions tight: "ticket is new", "channel is email", "group is first-line" is a better starting point than "any ticket".

### Webhooks: how Zendesk calls your agent

A [webhook](https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/) sends an HTTP request to your endpoint. For trigger use, pick the "trigger or automation" connection type, which is `subscriptions: ["conditional_ticket_events"]` in the API. The trigger then gets a "Notify webhook" action; in the API that is `notification_webhook`, whose value is an array of the webhook ID and the message body. According to [Zendesk's help article](https://support.zendesk.com/hc/en-us/articles/4408839108378), the JSON payload can contain placeholders for ticket data, and payloads are capped at 16,000 characters.

Keep the payload minimal. Send the ticket ID and the reason, and let the agent fetch everything else. That way it always works with the current state of the ticket.

```json
{
  "ticket_id": "{{ticket.id}}",
  "event": "ticket_created"
}
```

The other connection type, "Zendesk events", posts a fixed JSON payload for events such as ticket, user or Help Center activity. You cannot change its method or content, and a webhook cannot switch connection type after it has been created.

### Ticket API: reading and writing back

The agent reads with `GET /api/v2/tickets/{id}` and `GET /api/v2/tickets/{id}/comments`, which returns up to 100 comments per page. There is no endpoint for creating a comment on its own. Per the [Ticket Comments reference](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/), you add a `comment` object to a ticket update.

### Help Center: the agent's knowledge

The [Help Center API](https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/) lists articles across the whole Help Center, or by category, section or locale. The text sits in `body` as HTML, and `user_segment_id` controls who may view an article. The article on [enterprise RAG architecture](https://www.ruebstudio.de/en/guides/ai-agent-architecture/enterprise-rag-architecture) explains how such an index is built in general. For keeping it fresh, `GET /api/v2/help_center/incremental/articles?start_time=<unix time>` returns only what changed since a given moment.

## Internal note or public reply: the switch that matters most

Every comment has a `public` field. `true` means a public reply the customer sees; `false` means an internal note visible only to agents. Start with internal notes. A person then sees every suggestion before it reaches a customer ([human in the loop](https://www.ruebstudio.de/en/glossary/human-in-the-loop)), and you learn how good the agent is without exposing anyone to its mistakes.

The documentation points out a quirk: the `public` value set when a ticket is created carries over to later comments unless you change it. Set the field explicitly on every write. Writing a note and a tag looks like this:

```bash
# Write the agent's suggestion back as an internal note
curl -s -X PUT "https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${TICKET_ID}.json" \
  -H "Authorization: Bearer ${ZENDESK_OAUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"ticket": {"comment": {"body": "Suggested reply (AI agent): ...", "public": false}}}'

# Add a marker tag without replacing existing tags
curl -s -X PUT "https://${ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/${TICKET_ID}/tags.json" \
  -H "Authorization: Bearer ${ZENDESK_OAUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["ai_suggestion"]}'
```

The second call uses the [Add Tags](https://developer.zendesk.com/api-reference/ticketing/ticket-management/tags/) endpoint, which keeps existing tags. Sending `tags` inside a ticket update would overwrite them.

Other details from the reference that matter in production:

- `body` strips HTML and only renders Markdown when the author is an agent. `html_body` accepts HTML and is the recommended option for Agent Workspace.
- Comment bodies are limited to 64 kB, and anything longer is **truncated silently**. Check the length before you send.
- A ticket holds at most 5,000 comments.
- `author_id` lets another user appear as the author, but the API user is still recorded as the updater, which affects business rules and views.

## Macros: reuse the answers you already have

Macros are saved actions that set fields and insert standard text. An agent can use them instead of inventing its own wording: pick the right macro, take its changes and add only what is specific to the case.

The [Macros API](https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/) offers `GET /api/v2/macros/active` for the active macros the user can access, a title search and two preview endpoints. The documentation is explicit that the apply endpoints do not change the ticket. `GET /api/v2/tickets/{ticket_id}/macros/{macro_id}/apply` returns what the ticket would look like afterwards, and your agent then writes the result with a normal ticket update. That gives you a natural checkpoint: compare the preview with the ticket and fall back to a note when in doubt.

Give the agent a curated list of macros it may use, exposed as a tool, rather than access to all of them. Clear titles and categories make the choice far more reliable.

## Use cases and variants

The same building blocks support different goals. Three variants cover most projects. They differ mainly in how much the agent is allowed to write and which knowledge sources it needs.

**Draft reply as an internal note.** The agent reads new tickets, finds matching Help Center articles and similar solved tickets, and writes a draft with references as an internal note. A person accepts, edits or discards it. This is the usual starting point because the risk is small and you quickly see whether your knowledge base is good enough.

**Triage and routing.** The agent sets tags, priority or group. It writes fields rather than text, which is easier to verify, but it acts directly on your business rules: a new group can fire further triggers. Try this in a sandbox or with very narrow conditions first.

**Technical service with system lookups.** For fault reports on machines or equipment, the agent reads the serial number and error code, looks up manuals, service history and spare parts lists, and leaves a structured note. The [technical service agent](https://www.ruebstudio.de/en/ai-agents/technical-service) page describes how such agents are set up, and the [knowledge management agent](https://www.ruebstudio.de/en/ai-agents/knowledge-management) covers why a maintained knowledge base matters.

A step-by-step tutorial with code for the first variant will follow as a separate article, as will a guide for Freshdesk, where the ideas are the same but the terms and endpoints differ.

## Prerequisites: access, data, ownership

You need admin access to Zendesk, a service Zendesk can reach over HTTPS, a language model, and a Help Center that reflects your current products. On the organisational side, someone has to review suggestions and close the gaps the agent exposes.

**API access.** The [security documentation](https://developer.zendesk.com/api-reference/introduction/security-and-auth/) recommends OAuth access tokens sent as bearer tokens. It lists API tokens under "deprecated" and warns that they can be used to impersonate anyone in the account, including admins. For a new integration, use OAuth.

**Rate limits.** The [limits](https://developer.zendesk.com/api-reference/introduction/rate-limits/) depend on your plan: 200 requests per minute on Team, 400 on Professional and 700 on Enterprise. Ticket updates are also limited to 30 per 10 minutes per user per ticket, and to 100 requests per minute across the account. When you hit a limit, the API returns 429 with a `Retry-After` header, and your service must respect it.

**Knowledge.** The agent is only as good as the articles it finds. Outdated or contradictory Help Center content turns straight into poor suggestions. Budget time for a content review before launch.

**Data protection.** Tickets contain personal data. Decide where the model runs, which fields it sees and how long data is kept. With a self-hosted model or an EU-based provider, such an agent can be operated in line with the GDPR; the [sovereign AI](https://www.ruebstudio.de/en/sovereign-ai) page outlines the options. Treat this as orientation, not legal advice.

## A step-by-step approach

Six steps take you from idea to production. They deliberately start with read access and internal notes, and widen permissions only when results from your own tickets justify it.

1. **Pick one goal and one ticket type.** For example delivery status or documentation requests, not every ticket.
2. **Index the knowledge.** Load Help Center articles through the API, split them into chunks, make them searchable and keep them current with the incremental endpoint.
3. **Create the webhook and trigger.** Trigger connection type, narrow conditions, an exclusion tag, and a payload with just the ticket ID.
4. **Verify signatures.** Check every incoming request before the agent does any work (code below).
5. **Write notes and measure.** Review weekly how often suggestions were accepted, edited or discarded.
6. **Widen permissions gradually.** Fields and tags first. Public replies only for narrow cases, and only if the numbers support it.

Signature verification follows [Zendesk's guide](https://developer.zendesk.com/documentation/webhooks/verifying/): an HMAC-SHA256 over the timestamp followed by the raw request body, Base64-encoded and compared with the `X-Zendesk-Webhook-Signature` header. The timestamp comes from `X-Zendesk-Webhook-Signature-Timestamp`. This version uses only the Python 3.12 standard library:

```python
import base64
import hashlib
import hmac
import os

SECRET = os.environ["ZENDESK_WEBHOOK_SECRET"].encode()

def is_valid_signature(raw_body: bytes, timestamp: str, signature: str) -> bool:
    # Zendesk signs timestamp + raw body
    message = timestamp.encode() + raw_body
    digest = hmac.new(SECRET, message, hashlib.sha256).digest()
    expected = base64.b64encode(digest).decode()
    # Constant-time comparison
    return hmac.compare_digest(expected, signature)
```

Use the **raw** body. If your framework parses the JSON and you serialise it again before checking, the bytes differ and the signature will not match. Until the webhook exists, the documentation provides a static test secret; after that, use the webhook's own secret from Admin Center.

## Limits and risks

The main risks are not in the model but in how it interacts with Zendesk's rules: loops between trigger and agent, missed webhook calls, silently truncated text and overly broad permissions. Each has a simple mitigation.

- **Trigger loops.** When the agent writes to a ticket, that is another update, so triggers run again. Without an exclusion, the trigger keeps calling the agent. Have the agent add a tag such as `ai_suggestion` and add the condition "tags contain none of ai_suggestion" to the trigger.
- **No delivery guarantee.** The help article says Zendesk retries failed calls up to three times for certain response codes. Ordering is not guaranteed and delays can occur. Run a periodic sync through the API to catch missed tickets, and make sure duplicate calls for the same ticket are harmless.
- **Truncated comments.** Anything over 64 kB is cut without an error. Shorten long summaries or link to an internal system instead.
- **Misplaced trust.** A fluent draft looks right even when it rests on an outdated article. Including the sources in every note makes it checkable.
- **Permissions.** An API user with admin rights can change everything. Give the technical user only what the chosen variant needs.

A custom agent is the wrong choice if all your knowledge already lives in the Help Center, you do not want to run your own model and nobody will own the service long term. In that case, Zendesk's built-in option is usually the shorter path.

## Where do I start?

Start with one ticket type, read access and internal notes. After a few weeks, the acceptance rate on your own tickets shows whether expanding is worth it and which knowledge gaps to close first.

A useful first step is a short inventory. Which ticket types are most frequent, how many could be answered from existing Help Center articles, and which systems outside Zendesk would the agent need to know about? The answers define the scope of the first agent. For how we design such agents and embed them in existing systems, see the overview of [AI agents](https://www.ruebstudio.de/en/ai-agents); the business view of support automation is covered in the guide to [AI customer service agents](https://www.ruebstudio.de/en/guides/ai-agents-by-department/ai-customer-service-agent-b2b).

## Frequently asked questions

### Do I need a Marketplace app to connect my own agent?

No. A webhook, a trigger and OAuth access to the API are enough to start. A sidebar app only becomes worth building when agents should accept or reject suggestions inside the ticket view.

### Can the AI agent apply macros on its own?

The macro apply endpoints only return a preview of the changes. Your agent has to write the result with a ticket update, which is also a convenient place for a check.

### How do support staff tell which notes came from the agent?

Use a dedicated technical user as the author and a fixed tag per action. Views, reports and triggers can then filter on both.

### What happens if the agent service is down?

Zendesk retries failed webhook calls only a few times. Tickets carry on without a suggestion, and a scheduled sync through the API can catch up on anything that was missed.

## Sources

- [Zendesk Developer Docs: Ticket Comments](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/)
- [Zendesk Developer Docs: Tags](https://developer.zendesk.com/api-reference/ticketing/ticket-management/tags/)
- [Zendesk Developer Docs: Webhooks API](https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/)
- [Zendesk Developer Docs: Verifying webhook authenticity](https://developer.zendesk.com/documentation/webhooks/verifying/)
- [Zendesk Help: Creating webhooks to interact with third-party systems](https://support.zendesk.com/hc/en-us/articles/4408839108378)
- [Zendesk Developer Docs: Triggers](https://developer.zendesk.com/api-reference/ticketing/business-rules/triggers/)
- [Zendesk Developer Docs: Actions reference](https://developer.zendesk.com/documentation/ticketing/reference-guides/actions-reference/)
- [Zendesk Developer Docs: Macros](https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/)
- [Zendesk Developer Docs: Help Center Articles](https://developer.zendesk.com/api-reference/help_center/help-center-api/articles/)
- [Zendesk Developer Docs: Rate limits](https://developer.zendesk.com/api-reference/introduction/rate-limits/)
- [Zendesk Developer Docs: Security and authentication](https://developer.zendesk.com/api-reference/introduction/security-and-auth/)
- [Zendesk: AI Agents](https://www.zendesk.de/service/ai/ai-agents/)
