Your Customer Success Manager handles the initial integration setup using an internal wizard. This guide covers what your team needs to provide, what gets created in your Zendesk instance, and what you can do after setup.
How It Works
Cevro connects to Zendesk through Sunshine Conversations — the messaging API that powers Zendesk’s web widget.- A player opens the chat widget on your website
- The conversation is routed to Cevro via the switchboard
- Cevro’s AI handles the conversation — authenticating the player, looking up account data, and resolving their request
- If the AI can’t resolve the issue, it escalates to your human agents via the Zendesk agent workspace
- When done, the ticket is auto-solved so the player can start a fresh conversation next time
What You Need to Provide
Your Zendesk admin collects these credentials from the Zendesk Admin Center and shares them with your Cevro account team:Sunshine Conversations API
Found in Admin Center → Apps & Integrations → APIs → Conversations API:| Credential | Description |
|---|---|
| App ID | The Sunshine Conversations app identifier |
| API Key ID | Starts with app_ |
| API Secret Key | Shown only once when created — copy it immediately |
Zendesk Support API
Found in Admin Center → Apps & Integrations → APIs → Zendesk API:| Credential | Description |
|---|---|
| Subdomain | Your Zendesk URL, e.g. mycompany from mycompany.zendesk.com |
| Admin email | Email address of the Zendesk admin account used for API access |
| API Token | Generated under Admin Center → APIs → Zendesk API → API Tokens |
Brand & Widget
| Item | Where to Find It |
|---|---|
| Brand | Admin Center → Account → Brand management — the brand you want to automate |
| Widget Key | Admin Center → Channels → Messaging → Installation — the value after key= in the embed script URL |
What Gets Created in Your Zendesk
During setup, the following resources are created in your Zendesk instance:Webhook Integration
A custom integration in Sunshine Conversations that receives conversation events (new chats, messages) and routes them to Cevro.Switchboard Integration
Registers Cevro as a switchboard participant alongside your Zendesk agent workspace. This controls conversation routing — the AI handles conversations first, and escalates to human agents when needed.Custom Ticket Field
A text field called “Cevro Ticket ID” is created in Zendesk Support. This links Zendesk tickets to Cevro conversations, so your agents can cross-reference between the two systems.Zendesk Triggers
Two triggers are created to manage ticket lifecycle:-
Auto Solve Cevro Resolved Tickets — When a ticket is tagged
handled-by-cevro, it is automatically solved so the player can start a fresh conversation next time. -
Auto Close Human-Solved Escalated Tickets — When an escalated ticket (tagged
escalated-from-cevro) is solved by a human agent, it is fully closed.
If your Zendesk admin has restricted API trigger creation, you can create these triggers manually in Admin Center → Objects and Rules → Business Rules → Triggers using the tag conditions described above.
Brands & Multi-Brand Support
If you operate multiple brands in Zendesk, each brand can be independently configured:- Automated brands — Cevro handles conversations with AI
- Non-automated brands — Conversations pass through directly to your human agents
After Setup
Once your CSM completes the integration, you’ll see two tools on the Zendesk channel page in your Cevro dashboard:Widget Tester
An embedded widget that lets you send test messages through your Zendesk web widget directly from the Cevro dashboard. Use this to verify the integration is working end-to-end before going live.Switchboard Diagnostics
A health check that validates your entire Zendesk configuration:| Check | What It Validates |
|---|---|
| Zendesk Configuration | Config exists on workspace |
| Onboarding Status | Webhook processing is active |
| Configuration IDs | Integration IDs stored correctly |
| Sunshine API Credentials | Can authenticate with Sunshine Conversations |
| Switchboard | Switchboard is active and configured |
| Cevro Integration | Cevro found in switchboard with standby events |
| Chain Position | Cevro is using the correct takeover strategy |
| Brand Mapping | Brands are mapped and automated |
| Support API Credentials | Can authenticate with Zendesk Support API |
| Webhook URL | Webhook points to the correct endpoint |
Player Authentication
Cevro can automatically identify logged-in players when they start a chat, so the AI agent knows who they are without asking. There are two ways to pass player identity to Cevro:Option 1: JWT Authenticated Messaging (Recommended)
If your app uses Zendesk Authenticated Messaging, you already generate a JWT for each logged-in player. Theexternal_id in that JWT is automatically available to Cevro — no extra Zendesk configuration required.
Ensure JWT auth is enabled
Your web app should already be generating JWTs with an
external_id field for Zendesk Authenticated Messaging. This is configured in your Zendesk Admin Center under Channels → Messaging → Authentication.Tell your CSM to enable External ID auth
Your Cevro account team will configure the integration to extract the
external_id from the authenticated session. No ticket field setup is needed on your side.This is the recommended approach because it relies on your existing authentication — the player identity is cryptographically verified by Zendesk, not just passed as a form field.
Option 2: Custom Ticket Field
If your setup passes player IDs via a custom Zendesk ticket field (e.g., through a pre-chat form or conversation metadata), Cevro can extract it from there instead. Your CSM will configure which ticket field contains the player identifier and where to store it in Cevro. This requires creating a custom ticket field in Zendesk and configuring your widget or bot to populate it.Escalation to Human Agents
When the AI determines a conversation needs human attention, Cevro passes control to the Zendesk agent workspace via the switchboard. Your human agents see the conversation in their Zendesk queue with full context. The escalated ticket includes:- An internal note summarizing why the AI escalated
- The
escalated-from-cevrotag for routing and reporting - The linked Cevro Ticket ID in the custom field
Troubleshooting
| Symptom | Likely Cause | What to Do |
|---|---|---|
| Widget shows “No agents available” | Switchboard not configured or Cevro integration missing | Run Switchboard Diagnostics and check for failures |
| Conversations not reaching Cevro | Webhook URL incorrect or credentials expired | Run Switchboard Diagnostics — check webhook and credential checks |
| Tickets not auto-solving | Trigger missing or tag mismatch | Check Zendesk Admin Center → Triggers for the “Auto Solve” trigger |
| Escalated tickets not closing | Second trigger missing | Check for the “Auto Close Human-Solved Escalated Tickets” trigger |
| Non-automated brand getting AI responses | Brand incorrectly marked as automated | Check Settings → Brands in Cevro dashboard |