Zendesk troubleshooting

Documentation Index

Fetch the complete documentation index at: https://docs.open.cx/llms.txt

Use this file to discover all available pages before exploring further.

Before debugging, have this ready:

• Your Zendesk subdomain and the admin email used for the API token.
• A specific session ID (from Inbox) or Zendesk ticket ID where the problem shows.
• The webhook URL shown in Settings → Integrations → Zendesk.

​

Common scenarios

Jump to the symptom that matches what you’re seeing.

​

”Failed to verify credentials” on save

Likely cause: wrong subdomain format, expired token, or API access disabled. Fix: use just the subdomain part (acme, not acme.zendesk.com). Regenerate the token in Zendesk Admin Center. Confirm Token access is toggled on.

​

”Failed to verify credentials” on Sunshine Messaging save

Likely cause: wrong key type (Integration key, not App key), or wrong App ID. Fix: confirm the Key ID starts with app_. If it doesn’t, delete the key and create a new one from the Conversations API section of Admin Center — not from inside a specific integration. Re-copy the App ID from the top of that same page.

​

Handoff runs but no ticket appears in Zendesk

Likely cause: contact has no email, or the Zendesk user behind the API token lacks permission to create users and tickets. Fix: confirm the OpenCX contact has an email. Confirm the token’s Zendesk user is an admin or an agent with full access.

​

Agent public replies don’t reach the contact

Likely cause: webhook missing, trigger misconfigured, or wrong event subscription. Fix: in Zendesk Admin Center → Triggers, confirm the condition is Ticket is Updated with a public comment present, and the action posts to the OpenCX webhook URL. Retry the failed delivery from the webhook’s activity log.

​

Internal notes reaching the contact

Likely cause: trigger payload uses the wrong comment variable. Fix: update the trigger to use {{ticket.latest_public_comment}} specifically, not {{ticket.latest_comment}}.

​

Duplicate tickets for the same conversation

Likely cause: handoff fires multiple times before the first ticket’s external_id links to the session. Fix: none on your side — dedup is automatic once the link exists. If you see this consistently, open a support request with two example session IDs.

​

AI fields show blank on the ticket

Likely cause: mapping disabled or description too vague. Fix: check Settings → Ticketing → Zendesk AI Fields. Enable the mapping. Tighten the description with concrete examples.

​

Help Center articles not appearing in AI answers

Likely cause: initial sync still running, or articles are internal. Fix: open Data Sources, wait for sync to complete. Check article visibility in Zendesk — published + no segment restriction is required for public answers.

​

Webhook returns 4xx in Zendesk’s activity log

Likely cause: webhook URL is stale. Fix: copy the current URL from Settings → Integrations → Zendesk and update the webhook endpoint in Zendesk.

​

Webhook returns 5xx in Zendesk’s activity log

Likely cause: payload missing ticket_id or external_id. Fix: update the trigger’s JSON body to include {{ticket.id}} and {{ticket.external_id}}. See the Ticketing API setup reference payload.

​

Handoff creates a ticket but agent replies do nothing

Work through this checklist:

1. Open the ticket in Zendesk. Confirm it has tag opencx and an external_id set.
2. In Zendesk Admin Center → Webhooks, open your OpenCX webhook. Check Activity — recent calls should return 2xx. A 4xx means the webhook URL is stale (re-copy from OpenCX). A 5xx means OpenCX couldn’t match the ticket to a session.
3. Confirm the trigger in Admin Center → Triggers is active.
4. Confirm the reply was posted as Public reply, not Internal note.
5. Confirm the original contact channel is still reachable (email address valid, WhatsApp/SMS number still subscribed).

​

Assist Mode doesn’t post suggestions

If you’re already running Assist and suggestions aren’t appearing, check in order:

• The ticket wasn’t created by OpenCX — Assist runs on rep-opened tickets only.
• The ticket’s topic isn’t on the no-assist list (look for that tag).
• The AI produced an answer — look for opencx_skipped_not_helpful_answer, which means the AI judged its own answer incomplete and stayed quiet.
• The ticket is in a status where suggestions apply (open / pending).

​

Messaging (Sunshine) issues

​

Handoff on WhatsApp creates a ticket instead of a chat

Likely cause: Sunshine credentials missing or inactive. Fix: confirm the Messaging tab in Settings → Integrations → Zendesk shows Active. Re-enter credentials if needed.

​

Rep reply in Agent Workspace doesn’t reach WhatsApp

Likely cause: webhook not registered or wrong event subscription. Fix: re-register the Sunshine webhook subscribed to conversation:message. See Sunshine Conversations setup.

​

Second chat session from the same end user never reaches Agent Workspace

Likely cause: multi-conversations not enabled on the Sunshine app. Fix: turn on multi-conversations in Admin Center → Channels → Messaging and social → Messaging → Manage settings → Multi-conversations for every Web/iOS/Android channel OpenCX answers on. Full walkthrough in the Sunshine setup — see Turn on multi-conversations for the Sunshine app. Note this change is irreversible.

​

Sunshine conversation never appears as a Zendesk ticket

Likely cause: working as designed — Sunshine conversations only surface as tickets after handoff to a human, unless AI agent tickets is turned on. Fix: if you want to see AI-only conversations as tickets in the Agent Workspace before escalation, turn on AI agent tickets in Admin Center → Channels → Messaging and social → Messaging → Manage settings → AI agent conversations as tickets in Agent Workspace. These tickets are read-only until handoff. Full reference: Understanding AI agent tickets for AI agent–only conversations.

​

AI doesn’t take the conversation back after a ticket is solved or closed

Likely cause: one of two routing-config gaps — either the Solved→Closed transition hasn’t fired yet, or the account’s Conversation control setting isn’t Release control so handback follows the wrong chain. Fix #1 — Set the account-wide Sunshine Conversation control to Release control. This is almost always the actual fix. Conversation control is an account-wide Sunshine Conversations switchboard setting — not a per-bot setting. It lives on the Messaging setup page, not inside the OpenCX marketplace bot entry. In Zendesk Admin Center, go to Channels → Messaging and social → Messaging, open your messaging configuration (https://<your-subdomain>.zendesk.com/admin/channels/messaging_and_social/messaging/setup), expand the Conversation control section, select Release control, and save. Why this matters: with the default Pass control, when an agent closes a ticket Sunshine passControl’s the conversation to whatever nextSwitchboardIntegrationId is wired on the Agent Workspace integration — typically Zendesk’s own zd-answerBot, not OpenCX. With Release control, Sunshine clears the active integration on close, and the customer’s next message gets re-assigned via the per-channel defaultResponder (which is OpenCX once configured per setup step 7). References:

• Zendesk’s About Sunshine Conversations in Zendesk Suite — section “Configuring conversational control”.
• Zendesk’s Setting an advanced AI agent as the default responder for a messaging channel — search the article for “Release control”.

Fix #2 — Make sure OpenCX is the per-channel default responder. Even with Release control, the post-handback routing only lands on OpenCX if the channel itself has OpenCX as its default responder. In Admin Center → AI → AI agents → AI agents → Marketplace bots → OpenCX, under Channels, click Options → Assign default for every channel you want AI on (or use Set as default for all channels to cover the lot). Reference: Managing third-party bots in Admin Center. Fix #3 — Shorten the Solved→Closed window so handback fires quickly, not in 4 days. Sunshine only hands control back on the Closed transition, not on Solved. By default Zendesk waits 4 days. Until then, any return message sticks with Agent Workspace.

• Quick option: edit the built-in automation Close ticket 4 days after status is set to solved in Admin Center → Objects and rules → Business rules → Automations and drop the timeframe (down to 1 hour).
• Immediate option: add a Zendesk trigger that closes any ticket whose status changes to Solved, so handback fires the instant an agent solves.

Reference: Managing conversation handoff and handback — section “Modifying the time between the solved and closed states”. Verify after the changes: solve and close a test ticket, send a follow-up message from the same end user, and confirm the next inbound webhook arrives with activeSwitchboardIntegration.name = opencx (visible in the Zendesk webhook activity log or the OpenCX session timeline). If activeSwitchboardIntegration.name is still zd-answerBot or zd-agentWorkspace, fix #1 hasn’t been applied.

​

Duplicate contact in Zendesk for the same WhatsApp number

Likely cause: user merge skipped because the Zendesk API credentials are missing from the Messaging integration. Fix: paste the same credentials you use for Ticketing into the Zendesk API credentials panel under the Messaging setup.

​

Limits & timing

---

​

Related Documentation