> For the complete documentation index, see [llms.txt](https://docs.zipchat.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.zipchat.ai/installation-and-setup/chat-settings/channels/zendesk-connecting-zipchat-to-your-zendesk-account.md). # Zendesk: Connecting Zipchat to Your Zendesk Account Let Zipchat answer your customers inside Zendesk — both email tickets and the Web Widget — and hand off cleanly to your human team when needed. Zipchat works inside Zendesk as a teammate: it answers your customers and escalates to your human agents when needed. It can handle two surfaces, **independently or together**: * **Email & other ticket sources** — Zipchat replies to email, web form and API tickets as a Zendesk agent you choose. * **Zendesk Web Widget (Messaging)** — Zipchat answers the chat bubble on your site. You connect with your Zendesk login (OAuth): no API tokens to create or paste. > ⚠️ **Using Zendesk's built-in AI agent?** Disable it before connecting Zipchat, or customers will get duplicate responses. Admin Center → **AI → AI agents**; for each active agent open **Settings → Brand and channels** and uncheck **Messaging**, **Email**, and **Web form**, then publish. *** ### What you'll need * A **Zendesk administrator** to authorize Zipchat. * A **Zendesk agent for Zipchat's replies**. A dedicated agent (e.g. **Zipchat Bot**, with a plus-alias such as `support+zipchat@yourdomain.com`) works best. Light agents, chat-only agents and contributors can't reply. * Optional: **Zendesk Suite Professional or above**, for Web Widget conversations. *** ### Part 1 — Connect Zendesk #### Step 1 — Authorize Zipchat 1. In Zipchat, open **Channels** and click **Turn on** on the Zendesk card. 2. Enter your **Zendesk address** — your subdomain (e.g. `your-company`) or your Zendesk URL. Always use your *account* address, the one you log in at, even if you use several brands. 3. Click **Connect Zendesk**, sign in to Zendesk as an administrator, and click **Allow**. #### Step 2 — Choose who replies Back in Zipchat, pick the agent under **Reply as** and click **Continue**. Customers see this agent's name on Zipchat's replies; Zipchat also writes internal notes as this agent and is assigned new tickets through it. You can change it later in the Zendesk settings. #### Step 3 — Ticket routing (automatic) Zipchat adds a webhook and two triggers whose names start with **Zipchat** to your Zendesk account (Admin Center → **Apps and integrations**). From then on: * New email, web form and API tickets are assigned to your **Reply as** agent and answered by Zipchat. * Customer replies on tickets still assigned to that agent are answered too. * Agent replies, internal notes and assignment-only updates don't trigger Zipchat. Reassign a ticket to a person and Zipchat stops replying on it. > 💡 Already route tickets with your own rules, or connecting a second store on the same Zendesk account? See *Multiple stores* below — Zipchat leaves existing routing alone. #### Step 4 — Install the handoff skill In Zipchat, open **Prompt and Skills** and install **"Zendesk: escalate to human"** from the gallery. It needs no credentials: it uses your Zendesk connection. When a customer asks for a person, Zipchat adds a private internal note summarizing the request and unassigns the ticket for your team. #### Step 5 — Test the email path Send an email to your support address from a customer email address and verify: the ticket is assigned to your Reply as agent, Zipchat replies within \~15 seconds, and asking for a person unassigns the ticket with an internal summary note. *** ### Part 2 — Web Widget (optional) Requires Zendesk Suite Professional or above, with Messaging enabled. You can do this in the setup wizard (**Handle Web Widget chats**) or later in the Zendesk settings (**Web Widget** tab). #### Step 6 — Create the Conversations integration > ⚠️ **One per Zendesk account — ever.** If another of your stores is already connected to this Zendesk account, skip this step and reuse that integration's shared secret (see *Multiple stores* below). Zendesk rejects a second integration with the same webhook endpoint, and one integration serves all your brands. 1. Admin Center → **Apps and integrations → Conversations integrations → Create integration**. 2. Name it e.g. **Zipchat widget**. 3. Webhook endpoint: the **Conversations webhook URL** shown in Zipchat. 4. Subscribe to **Conversation created** and **Conversation message**. 5. Copy the **Shared secret**. #### Step 7 — Create a Conversations API key 1. Admin Center → **Apps and integrations → APIs → Conversations API → Create API key** (an account-level key, not one inside the integration). 2. Copy the **App ID**, **Key ID** (starts with `app_`) and **Secret key** — the secret is shown only once. #### Step 8 — Save in Zipchat Paste the **Integration shared secret**, **App ID**, **Key ID** and **Secret key**, then click **Save and register switchboard** (in the Zendesk settings, saving registers it). This makes Zipchat the default responder for new widget conversations and hands conversations to Agent Workspace when a customer asks for a person. The handoff skill from Step 4 also covers the widget: on widget conversations Zipchat asks once for the customer's email and adds it to the internal note. #### Step 9 — Test the widget Open the widget preview (Admin Center → **Channels → Messaging** → your widget → **Test it now**) and verify: the welcome message appears, replies render formatting (bold, links, bullets), and asking for a person hands the conversation to Agent Workspace and leaves an unassigned messaging ticket with a summary note. *** ### Already connected with an API token? For each store (about a minute each): 1. In Zipchat, open **Channels** and click **Settings** on the Zendesk card. 2. On the **Tickets** tab, in the **Zendesk account** section, click **Switch to OAuth**. 3. Sign in to Zendesk as an administrator and click **Allow**. 4. Back in Zipchat, check **Reply as** in the same section. Zipchat keeps the same agent when that agent can reply publicly; if another agent is shown, choose yours and click **Save**. Your ticket routing and Web Widget setup stay as they are. Keep your API token until Zipchat support confirms your handoff skill no longer needs it. *** ### Multiple stores on one Zendesk account If you run several stores (Zendesk **brands**) in a single Zendesk account, connect **one Zipchat chat per store**, each authorized separately in Step 1: | Setting | Per store? | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Zendesk address | **Same** on every store (the account address — never a brand subdomain) | | Zendesk brand | **Different** — choose each store's brand in the Zendesk settings, so its support email and **Test channel** use that brand's address | | Ticket routing | Automatic for the **first** store only. For each further store, the **Ticket routing** section shows a **Webhook URL**, **Bearer token** and **JSON payload template**: create one webhook per store and triggers like Zipchat's, with a **Brand Is → (your brand)** condition | | Conversations App ID / Key ID / Secret / shared secret | **Same** on every store — one API key, one integration | | Conversations integration in Zendesk | **One for the whole account** — never create a second one | | Brand widget integration ID | **Different** — this is what routes each brand to its store | | Handoff skill | Install **"Zendesk: escalate to human"** on every store | **Widget routing setup:** 1. Each brand needs its own Web Widget (Admin Center → **Channels → Messaging → Add channel → Web Widget** — Zendesk allows one widget per brand). 2. Connect every store in Zipchat with the same Conversations credentials (Part 2, skipping Step 6 after the first store). 3. In any store's Zendesk settings, open the **Web Widget** tab and click **List brand widgets**. You'll see each brand's widget with its ID. 4. Paste each widget's ID into the matching store's **Brand widget integration ID**. **Map every store, including the first one you connected.** How routing behaves: * A widget conversation goes to the store mapped to that widget. * If a widget isn't mapped to any store, the conversation falls back to a store with an **empty** Brand widget integration ID (if one exists) — otherwise Zipchat stays silent rather than answering as the wrong brand. > 💡 The widget IDs from **List brand widgets** are *not* the "Integration ID" shown on your Conversations integration page in Admin Center — that one identifies the shared Zipchat integration, not a brand widget. *** ### Disconnecting In Zipchat, open **Channels**, click **Settings** on the Zendesk card, and click **Disconnect** at the top of the page. Zipchat hands the Web Widget back to Zendesk (Agent Workspace becomes the default responder again) and disables the webhook and triggers it created. Routing you set up yourself, the Conversations integration and the API key stay in Zendesk — remove them manually if you no longer need them. To stop only the widget, use **Disconnect Web Widget** in the **Web Widget** tab. You can also revoke Zipchat's access in Zendesk at any time. *** ### Troubleshooting | Issue | Fix | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | "Ticket routing isn't set up" | Click **Retry ticket setup**; if Zendesk permissions changed, **Reconnect Zendesk** as an administrator | | Zendesk settings show **Reconnect required** | Zipchat's access was revoked or expired — click **Reconnect Zendesk** in the **Zendesk account** section and approve again | | No reply to new tickets | Check the ticket came in by email, web form or API and is assigned to your Reply as agent | | Zipchat stopped replying after a human took the ticket | Intentional — Zipchat only handles tickets assigned to its agent | | Raw HTML in widget replies, or the widget is silent | The switchboard isn't registered — the **Web Widget** tab shows a warning; fix the reason Zendesk gave and click **Try again** | | Can't create a second Conversations integration | Don't — reuse the first one's shared secret on every store (see *Multiple stores*) | | One brand's widget is silent | That widget isn't mapped to any store and no store has an empty mapping — check **List brand widgets** and the **Brand widget integration ID** on each store | | The wrong store's bot answers a brand's widget | That brand's widget is unmapped and falling back to the store with an empty mapping — map every store explicitly | | Widget mapping rejected as "already taken" | Another of your stores is already mapped to that widget — each widget can route to only one store | --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.zipchat.ai/installation-and-setup/chat-settings/channels/zendesk-connecting-zipchat-to-your-zendesk-account.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.