# Zendesk: Connecting Zipchat to Your Zendesk Account 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 tickets as a dedicated agent. * **Zendesk Web Widget (Messaging)** — Zipchat answers the chat bubble on your site. Pick the path(s) you need. Both start from the same core setup below. > ⚠️ **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. *** ### Part 1 — Core setup (required for every path) #### Step 1 — Create a bot agent user 1. Admin Center → **People → Team → Team members → Create**. 2. Name it something recognisable, e.g. **Zipchat Bot**. 3. Role: **Agent** (a Light Agent won't work). 4. Verify the account via the welcome email. Tip: use a plus-alias on an existing inbox (e.g. `support+zipchat@yourdomain.com`) so the verification email lands somewhere you already read. #### Step 2 — Generate an API token 1. Admin Center → **Apps and integrations → APIs → API configuration**. 2. Enable **Allow API token access**. 3. **API tokens** tab → **Add API token** — copy it immediately (it's shown only once). #### Step 3 — Connect in Zipchat 1. In Zipchat, open the **Channels** page and click **Start setup** on the Zendesk card. 2. Enter your **Zendesk subdomain** (always your *account* subdomain — the one you log in at, even if you use multiple brands), the **bot agent email**, and the **API token**. 3. Save. The card now shows the values you'll need for the paths below. #### Step 4 — Install the escalation tool 1. Open the **Custom tools** page and install **"Zendesk: escalate to human"**. 2. Fill in `ZENDESK_SUBDOMAIN`, `ZENDESK_BOT_EMAIL`, `ZENDESK_API_TOKEN`. 3. If you're doing the Web Widget path, you'll fill the remaining three variables in Part 3. Core setup done. Continue with **Part 2 (email)**, **Part 3 (Web Widget)**, or both. *** ### Part 2 — Email & ticket path (optional) #### Step 5 — Create the webhook 1. Admin Center → **Apps and integrations → Webhooks → Create webhook**. 2. Connection: **Trigger or automation**. 3. Name: **Zipchat events**. Method: **POST**, format: **JSON**. 4. Endpoint URL: the **Webhook URL** from the Zipchat Zendesk card. 5. Authentication: **Bearer token**, using the **Bearer token** from the card. #### Step 6 — Create two triggers **Trigger 1 — new tickets** * Name: *Zipchat: assign and notify on new ticket*. * Condition: **Ticket Is → Created**. * Actions: **Assign to Zipchat Bot**, and **Notify active webhook → Zipchat events** with the JSON payload template from the card, setting `"event": "ticket_created"`. **Trigger 2 — customer replies** * Name: *Zipchat: notify on customer reply*. * Conditions: **Ticket Is → Updated**, **Assignee is → Zipchat Bot**, **Current user is → (end user)**, **Comment is → Present and requester can see**. * Action: **Notify active webhook → Zipchat events** with the same payload, setting `"event": "comment_added"`. > ⚠️ Without the **Ticket Is → Updated** condition on Trigger 2, the bot replies twice to new tickets. #### Step 7 — Test the email path Send an email to your support address (e.g. `support@yourbrand.zendesk.com`) and verify: a ticket is created and assigned to Zipchat Bot, the bot replies within \~15 seconds, and asking for a human unassigns the ticket with an internal summary note. *** ### Part 3 — Web Widget path (optional) Requires Zendesk Suite Professional or above, with Messaging enabled. #### Step 8 — Create a Conversations API key 1. Admin Center → **Apps and integrations → APIs → Conversations API → Create API key**. 2. Save the **App ID**, **Key ID**, and **Secret key** (the secret is shown only once). #### Step 9 — 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** from the Zipchat Zendesk card. 4. Subscribe to **conversation:message** and **conversation:create**. 5. Copy the **Shared secret**. #### Step 10 — Paste credentials in Zipchat On the Zendesk card click **Edit settings** and fill the **App ID**, **Key ID**, **Secret key**, and **Integration shared secret**. (Leave **Brand widget integration ID** empty unless you run multiple stores on this Zendesk account — see below.) #### Step 11 — Register the Switchboard Click **Register Switchboard** on the card. This single click makes Zipchat the default responder for new widget conversations, wires escalations into your Agent Workspace, and lets the bot resume after a human closes a messaging ticket. Re-click it any time you change the Conversations credentials. #### Step 12 — Complete the escalation tool Edit the escalation tool and fill `ZENDESK_APP_ID`, `ZENDESK_KEY_ID`, `ZENDESK_KEY_SECRET`. #### Step 13 — 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 human hands the conversation to Agent Workspace and leaves an unassigned messaging ticket with a summary note. *** ### Multiple stores on one Zendesk account If you run several stores (Zendesk **brands**) in a single Zendesk account, connect **one Zipchat chat per store** — they share almost everything: | Setting | Per store? | | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Subdomain, bot email, API token | **Same** on every store (the account subdomain — never a brand subdomain) | | 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 | | Email webhook + triggers | One **webhook per store** (each store has its own Bearer token) and add a **Brand Is → (your brand)** condition to both of that store's triggers | | Escalation tool | Install on every store, same credential values | **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 credentials (Parts 1 & 3, skipping Step 9 after the first store). 3. On any store's Zendesk card, 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 **Edit settings → 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 Click **Disconnect** on the Zendesk card. This removes the credentials from Zipchat but leaves your Zendesk configuration in place — remove the triggers, webhook, Conversations integration, and (optionally) the bot user manually. With multiple stores, disconnect each store separately; the shared Zendesk-side objects only need removing once, after the last store is disconnected. *** ### Troubleshooting | Issue | Fix | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | No reply to new tickets | Check Trigger 1 fires on creation and assigns the ticket to Zipchat Bot | | Bot replies twice on new tickets | Add the **Ticket Is → Updated** condition to Trigger 2 | | Bot ignores customer replies | Re-check all four Trigger 2 conditions | | Bot stopped replying after a human took the ticket | Intentional — the bot only handles tickets assigned to it | | Raw HTML in widget replies | Register (or re-register) the Switchboard — Step 11 | | Webhook returns 401 | Bearer token mismatch — copy it again from the Zipchat card | | 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: 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= ``` 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.