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 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
Admin Center → People → Team → Team members → Create.
Name it something recognisable, e.g. Zipchat Bot.
Role: Agent (a Light Agent won't work).
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
Admin Center → Apps and integrations → APIs → API configuration.
Enable Allow API token access.
API tokens tab → Add API token — copy it immediately (it's shown only once).
Step 3 — Connect in Zipchat
In Zipchat, open the Channels page and click Start setup on the Zendesk card.
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.
Save. The card now shows the values you'll need for the paths below.
Step 4 — Install the escalation tool
Open the Custom tools page and install "Zendesk: escalate to human".
Fill in
ZENDESK_SUBDOMAIN,ZENDESK_BOT_EMAIL,ZENDESK_API_TOKEN.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
Admin Center → Apps and integrations → Webhooks → Create webhook.
Connection: Trigger or automation.
Name: Zipchat events. Method: POST, format: JSON.
Endpoint URL: the Webhook URL from the Zipchat Zendesk card.
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
Admin Center → Apps and integrations → APIs → Conversations API → Create API key.
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.
Admin Center → Apps and integrations → Conversations integrations → Create integration.
Name it e.g. Zipchat widget.
Webhook endpoint: the Conversations webhook URL from the Zipchat Zendesk card.
Subscribe to conversation:message and conversation:create.
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:
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:
Each brand needs its own Web Widget (Admin Center → Channels → Messaging → Add channel → Web Widget — Zendesk allows one widget per brand).
Connect every store in Zipchat with the same credentials (Parts 1 & 3, skipping Step 9 after the first store).
On any store's Zendesk card, click List brand widgets. You'll see each brand's widget with its ID.
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
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
Last updated