Troubleshooting

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

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.

​

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