# Zendesk: Connecting Zipchat to Your Zendesk Account

The Zendesk channel lets Zipchat answer your customers from inside Zendesk, just like it does from your storefront chat bubble. Zipchat shows up as a teammate in your Zendesk workspace — it replies to tickets as a dedicated bot agent, hands off to your human team when it can't help, and stays on whichever surface the customer first reached you on.

It covers both ways a shopper can reach you on Zendesk:

* **Email and other ticket sources** — when a customer emails `support@yourbrand.zendesk.com` (or contacts you through any source that creates a ticket), Zipchat is auto-assigned, replies in the ticket as a public comment, and hands off cleanly when it needs a human.
* **Zendesk Web Widget** — the chat bubble you embed on your storefront. Zipchat answers inline with the same rich formatting as our native widget (bold, lists, clickable product links). When the customer asks for a human, control passes to Zendesk's Agent Workspace and your team takes over from there.

You can enable just the email path, just the widget path, or both. Setup happens in a single card on the channels page of your chat.

> Heads-up: if you already use Zendesk's built-in AI agent, disable it before you connect Zipchat. Otherwise customers will see two AI replies on every ticket. We'll cover this in Step 0.

***

#### Step 0 — Disable Zendesk's native AI agent (only if you use it)

Skip this step if you don't have a Zendesk AI agent set up.

1. In Zendesk, go to **Admin Center → AI → AI agents**.
2. For each live AI agent, open it → **Settings → Brand and channels**.
3. Uncheck **Messaging**, **Email**, and **Web form**.
4. Click **Publish**.

***

### Email path — answering Zendesk tickets

This is the path you want if customers reach your support team by emailing your Zendesk inbox, using a contact form, or any other source that creates a regular Zendesk ticket.

#### Step 1 — Create a bot Agent user in Zendesk

Zipchat replies as a dedicated user in your Zendesk workspace, so customers can tell it apart from your human team.

1. **Admin Center → People → Team → Team members → Create team member**.
2. Name it something like `Zipchat Bot` and pick an email address you control.
3. Set the role to **Agent**. (A Light Agent can't be assigned tickets, so it won't work.)
4. Open the welcome email Zendesk sent to that address and verify the account.

#### Step 2 — Generate an API token

1. **Admin Center → Apps and integrations → APIs → API configuration**.
2. Check **Allow API token access**.
3. Switch to the **API tokens** tab → **Add API token**.
4. **Copy the token immediately** — Zendesk only shows it once. If you lose it, you'll have to create a new one.

#### Step 3 — Connect Zendesk in Zipchat

1. In Zipchat, open your chat's **Channels** page.
2. Find the **Zendesk** card and click **Start setup**.
3. Fill in:
   * **Zendesk subdomain** — the part before `.zendesk.com` (e.g. `acme` for `acme.zendesk.com`).
   * **Bot agent email** — the email from Step 1.
   * **API token** — the token from Step 2.
4. Click **Save**.

The card now reveals three values you'll paste into Zendesk in the next steps: a **Webhook URL**, a **Bearer token**, and a **JSON payload template**.

#### Step 4 — Create the webhook in Zendesk

1. **Admin Center → Apps and integrations → Webhooks → Create webhook → Trigger or automation**.
2. Fill in:
   * **Name**: `Zipchat events`
   * **Endpoint URL**: paste the Webhook URL from the Zipchat card.
   * **Request method**: `POST`
   * **Request format**: `JSON`
   * **Authentication**: `Bearer token` → paste the Bearer token from the Zipchat card.
3. Click **Create webhook**.

#### Step 5 — Create two triggers

Zendesk needs two triggers: one that assigns Zipchat to brand-new tickets, and one that lets Zipchat know when the customer replies to an existing one.

**Trigger 1 — assign and notify on new ticket**

1. **Admin Center → Objects and rules → Business rules → Triggers → Create trigger**.
2. **Name**: `Zipchat: assign and notify on new ticket`.
3. **Conditions (meet ALL)**: `Ticket is → Created`.
4. **Actions**:
   * `Assignee → Zipchat Bot` (the user from Step 1).
   * `Notify by → Active webhook → Zipchat events` — paste the JSON payload template from the Zipchat card. Leave `event` set to `"ticket_created"`.
5. Save.

**Trigger 2 — notify on customer reply**

1. Create another trigger named `Zipchat: notify on customer reply`.
2. **Conditions (meet ALL)**:
   * `Ticket > Ticket Is → Updated` — this matters. Without it, the trigger also fires on ticket creation and Zipchat replies twice.
   * `Assignee is → Zipchat Bot`.
   * `Current user is → (end-user)`.
   * `Comment is → Present`.
3. **Actions**:
   * `Notify by → Active webhook → Zipchat events` — paste the same JSON payload, but change `event` to `"comment_added"`.
4. Save.

#### Step 6 — Install the escalation tool

So Zipchat can hand a ticket off to your human team, install the **Zendesk: escalate to human** custom tool.

1. In Zipchat, open your chat's **Custom tools** page.
2. Find **Zendesk: escalate to human** in the gallery and click **Install**.
3. The tool has six variables. For the email path, fill in the first three using the values you already have:
   * `ZENDESK_SUBDOMAIN`
   * `ZENDESK_BOT_EMAIL`
   * `ZENDESK_API_TOKEN`
4. Leave `ZENDESK_APP_ID`, `ZENDESK_KEY_ID`, and `ZENDESK_KEY_SECRET` blank for now — they're only needed if you also enable the Web Widget path (Step 12).
5. Save.

#### Step 7 — Try it

Send a test email to `support@yourbrand.zendesk.com` from an address that isn't on your Zendesk team (a personal Gmail works). You should see:

* A new ticket in Zendesk, with **Zipchat Bot** as the assignee.
* A public reply from Zipchat within about 15 seconds.
* The conversation appearing under your chat in Zipchat with a **Zendesk** channel badge.

Reply to the bot from the requester side (use an incognito window, the Zendesk Help Center, or just reply to the bot's email) — Zipchat should respond again on the same ticket.

To check escalation, tell the bot something like *"I want to talk to a human."* It will ask for a bit of context, then unassign itself from the ticket and leave a private internal note for your team. The customer only sees the bot's friendly handoff message — not the internal note.

***

### Web Widget path — answering messages from the Zendesk chat bubble

Use this path if you embed Zendesk's Web Widget on your storefront. The widget doesn't create tickets like email does — it runs on Zendesk's messaging backend (Sunshine Conversations) — so it needs its own credentials. You can skip this section if you only care about email.

#### Step 8 — Create a Conversations API key

1. **Admin Center → Apps and integrations → APIs → Conversations API → Create API key**.
2. Copy and save the **App ID**, **Key ID**, and **Secret key**. The Secret key is only shown once.

#### Step 9 — Create a Conversations integration

1. **Admin Center → Apps and integrations → Conversations integrations → Create integration**.
2. **Name**: anything you like (e.g. `Zipchat widget`).
3. **Webhook target URL**: paste the **Conversations webhook URL** shown on the Zipchat Zendesk card.
4. **Subscribe to**: `conversation:message` powers the bot's replies; `conversation:create` lets the bot send the welcome message when a visitor opens.
5. Save, then copy the **Shared secret** Zendesk shows you on the next screen.

#### Step 10 — Paste the four credentials into Zipchat

1. Back in Zipchat, open the Zendesk card and click **Edit settings**.
2. Fill in:
   * **App ID** (Step 8)
   * **Key ID** (Step 8)
   * **Secret key** (Step 8)
   * **Integration shared secret** (Step 9)
3. Save. The card now shows a **Web Widget** section with a **Register Switchboard** button.

#### Step 11 — Click Register Switchboard

One click wires up three things behind the scenes:

* Standby event delivery, so Zipchat keeps receiving widget messages even after a human takes over.
* The escalation route from Zipchat to Zendesk's Agent Workspace.
* The default responder, so the bot picks up again automatically once a ticket is closed.

You should see a success message. If you ever change your Sunshine credentials, click **Register Switchboard** again.

#### Step 12 — Fill in the remaining escalation tool variables

1. Open your chat's **Custom tools** page.
2. Edit the **Zendesk: escalate to human** tool you installed in Step 6.
3. Fill in the three remaining variables from Step 8:
   * `ZENDESK_APP_ID`
   * `ZENDESK_KEY_ID`
   * `ZENDESK_KEY_SECRET`
4. Save.

#### Step 13 — Try the widget

1. **Admin Center → Channels → Messaging** → preview your widget (or load it on a real page).
2. Send a message. You should see a bot reply inline within about 15 seconds, with proper formatting (bold, links, bullets).
3. Send a follow-up message — Zipchat should reply again.

Behind the scenes, Zendesk auto-creates a messaging ticket (titled `Conversation with Web User …`) as a read-only mirror of the conversation. That's expected.

To check widget escalation, send something like *"I want to speak with a human about a refund."* The bot will ask for some context, then reply with a handoff message and stop responding. The messaging ticket gets unassigned and tagged with an internal note summarizing the handoff. Reply from Agent Workspace and your message lands directly in the widget. When you close the ticket, future messages from that same customer go to the bot again.

***

### Disconnecting Zendesk

To turn the integration off, click **Disconnect** on the Zendesk card and confirm. Zipchat stops responding to Zendesk webhooks immediately and your saved credentials are deleted.

Note that the Zendesk-side configuration — your triggers, webhook, Conversations integration, and switchboard registration — stays in place. If you want a clean slate, remove those manually in Zendesk:

1. Delete the two triggers from Step 5.
2. Delete the `Zipchat events` webhook from Step 4.
3. Delete the Conversations integration from Step 9 (if you set it up).
4. Optionally delete the bot Agent user from Step 1.

***

### Troubleshooting

**The bot doesn't reply to new tickets.** Open the ticket in Zendesk and check that **Zipchat Bot** is the assignee. If it isn't, Trigger 1 didn't fire — re-check that the condition is `Ticket is → Created` and the action assigns to your bot user.

**The bot replies twice on new tickets.** Trigger 2 is missing the `Ticket Is → Updated` condition, so it's firing on creation as well as updates. Edit Trigger 2 and add the condition.

**The bot doesn't reply when the customer responds.** Check Trigger 2's conditions: `Assignee is → Zipchat Bot`, `Current user is → (end-user)`, and `Comment is → Present` all need to be set. If any human on your team replied first and the assignee changed, the bot will stop responding on that ticket — that's intentional.

**The widget shows raw HTML instead of formatted text.** Make sure Step 11 (Register Switchboard) completed successfully. If you changed your Sunshine credentials, click it again.

**I'm getting a 401 from the webhook.** The Bearer token in your `Zipchat events` webhook doesn't match what Zipchat is currently using. Open the Zipchat Zendesk card, copy the Bearer token, and update it in the Zendesk webhook config.

***

If you get stuck at any point, reach out to us at <support@zipchat.ai> and we'll help you get connected.


---

# Agent Instructions: 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.zipchat.ai/installation-and-setup/chat-settings/channels/zendesk-connecting-zipchat-to-your-zendesk-account.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.