> For the complete documentation index, see [llms.txt](https://docs.eesel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eesel.ai/integrations/zendesk.md).

# Zendesk

Connect Zendesk to train your agent on your help center, past tickets, and macros — then automate ticket responses, triage, and more.

**Connection modes:**

1. **Full connection (OAuth):** Enter Zendesk subdomain → authenticate via OAuth. Unlocks all sources, triggers, and actions.
2. **Help Center only (URL crawl):** Paste public Help Center URL. No account needed. Read-only access to public articles. No triggers or actions.

**Multibrand:** Fully supported. Each brand/domain appears as a subfolder. Each brand can have independent triggers, actions, and a different bot account per agent.

***

## What your agentt can do

* Train your agent on your Zendesk Help Center articles, macros, and past tickets
* Automatically reply to customer tickets or draft responses for your team
* Tag, assign, close, and update tickets
* Look up customer and organization information
* Connect Zendesk Messenger for live chat

***

## Connecting Zendesk

You have two connection options:

### OAuth (recommended)

Connect your full Zendesk account for access to tickets, macros, and all actions.

1. Go to **Integrations > Zendesk**
2. Select **OAuth**
3. Click **Connect** and authorize eesel AI in your Zendesk account
4. Grant the requested permissions

### Quick Start

Enter your Zendesk Help Center URL and your agent starts learning from your published articles. No authentication needed — but you won't have access to tickets, macros, or actions.

1. Go to **Integrations > Zendesk**
2. Select **Quick Start**
3. Enter your help center URL (e.g., `https://yourcompany.zendesk.com/hc`)
4. Click **Connect**

### Connecting a specific brand

If your Zendesk account has multiple brands and you want eesel to scope to one brand, follow these steps in order:

1. **Sign in to Zendesk as an agent on your account subdomain first.** Open `https://<your-account-subdomain>.zendesk.com` (the subdomain you normally use to sign in as an agent) and complete the sign-in. This establishes an active agent session, which Zendesk requires before it will grant OAuth on any brand subdomain.
   * Confirm the page header reads **"Sign in to&#x20;*****(your brand name)*****"** so you know you are on the right brand.
   * Make sure you are on the **agent** sign-in form. If the page is showing the end-user sign-in, click **"Switch to agent sign-in"** before entering your credentials.
2. In a new tab, open eesel, select the agent you want to integrate with this specific brand, and go to **Integrations > Zendesk**.
3. Select **OAuth**.
4. When prompted for your subdomain, paste the **brand subdomain** you want to connect (for example `https://<your-account-subdomain>.zendesk.com`).
5. Click **Connect**, after you successfully connected, eesel detects the brand from the subdomain you entered and scopes ticket sync and help center to that brand.

> **Why the sign-in step matters.** Zendesk routes every agent sign-in to your account's default agent brand. If you start the OAuth flow on a brand subdomain without an active agent session, Zendesk sends you to the agent brand to sign in and the original authorization request is lost. Signing in first keeps your session valid so the brand subdomain OAuth completes cleanly.

***

## Training your agent

### Available knowledge sources

| Source          | Description                                                                                                                  | Requires             |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------- |
| **Help Center** | Your published support articles                                                                                              | Quick Start or OAuth |
| **Macros**      | Shared and personal macros — filter by group                                                                                 | OAuth                |
| **Tickets**     | Past resolved tickets — filter by status and date, with optional [PII redaction](/security/pii-redaction.md) before indexing | OAuth                |

### Tips for training

* **Start with your Help Center** — it's the quickest win and covers most common questions
* **Add past tickets** to teach your agent your team's voice and handling style
* **Filter tickets by status** — focus on "Solved" and "Closed" tickets for the best training data
* **Import macros** if your team relies on canned responses for consistency
* **Turn on** [**PII redaction**](/security/pii-redaction.md) if your tickets may contain customer PII you don't want in the training corpus

***

## Triggers

| Trigger                             | Description                                             | Best for                  |
| ----------------------------------- | ------------------------------------------------------- | ------------------------- |
| **Any Customer Message**            | Fires on any new or updated ticket                      | Full AI Agent automation  |
| **First Customer Message**          | Fires only on the first message, before any agent reply | AI Triage                 |
| **Support Request Closed/Resolved** | Fires when a ticket is marked closed or resolved        | Post-resolution follow-up |
| **Agent Requests AI Help**          | Fires when @eesel is mentioned in an internal note      | On-demand AI Copilot      |

***

## Actions

### Responding to customers

| Action                  | Description                                                        |
| ----------------------- | ------------------------------------------------------------------ |
| **Leave Public Reply**  | Send a customer-visible reply. Supports Human in the Loop.         |
| **Leave Draft Reply**   | Create a draft for your team to review — never sends automatically |
| **Leave Internal Note** | Add a note only your team can see                                  |

### Ticket management

| Action              | Description                                  |
| ------------------- | -------------------------------------------- |
| **Tag Ticket**      | Add tags for categorization                  |
| **Create Ticket**   | Create a new ticket                          |
| **Assign Ticket**   | Assign to a specific agent                   |
| **Assign to Group** | Route to a team queue (e.g., "Billing Team") |
| **Close Ticket**    | Mark ticket as resolved                      |
| **Update Ticket**   | Change status, priority, or custom fields    |

### Information lookup

| Action                         | Description                                    |
| ------------------------------ | ---------------------------------------------- |
| **Read Ticket**                | Read the full ticket with conversation history |
| **Search Tickets**             | Search using Zendesk query syntax              |
| **List Tickets**               | List tickets with optional filters             |
| **Get User by Email**          | Look up a Zendesk user by their email          |
| **Get Organization for Email** | Retrieve organization context for a user       |
| **Get Ticket Fields**          | Read the values of ticket custom fields        |

## Zendesk Messenger

See our Zendesk Messneger integration guide for more details about setup and best practices here.

## Tips and best practices

**Start with draft replies.** Configure "Leave Draft Reply" as your first action. Review responses for a few days before switching to "Leave Public Reply."

**Use the triage trigger for routing.** Set up a separate triage agent using the "First Customer Message" trigger with Tag and Assign actions to organize your queue.

**Connect past tickets for better quality.** Agents trained on past tickets sound significantly more natural and consistent with your team's style.

**Set up escalation.** Configure "Assign Ticket" or "Assign to Group" actions and write clear escalation rules in your instructions.

## Troubleshooting

**Help Center not syncing?**

* Make sure your Help Center URL is correct and publicly accessible
* Check that articles are published, not drafts

**OAuth connection failing?**

* Ensure you have admin permissions in Zendesk
* Try disconnecting and reconnecting

**Agent not responding to tickets?**

* Verify the trigger is enabled in Settings > Triggers
* Check that the trigger type matches your use case

## FAQ

<details>

<summary>Can my agent reply and leave an internal note at the same time?</summary>

Yes. Configure both "Leave Public Reply" and "Leave Internal Note" as actions. In your instructions, tell the agent when to use each one. For example: "Always reply to the customer and leave an internal note summarizing the resolution."

</details>

<details>

<summary>Can I control which tickets the agent responds to?</summary>

Yes. You can configure trigger conditions to filter tickets, or use AI Triage to tag tickets first and have the agent only respond to specific tags.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.eesel.ai/integrations/zendesk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.