Skip to main content

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.

Sunshine Conversations is Zendesk’s real-time messaging layer. Use this path for every channel except email — the web chat widget, SMS, WhatsApp, Messenger, Instagram, and phone handoffs. Conversations land in the Zendesk as live chats your reps pick up with full context attached.
Sunshine Conversations is included with the Zendesk Suite plan. If you’re on Support Professional, use the Ticketing API path for email handoff and contact Zendesk to upgrade for real-time channels.

​
Before you start

Open Admin Center → Apps and integrations → APIs → Conversations API. If the section is missing, Sunshine isn’t provisioned on your account — contact Zendesk.
You’ll create an App key in the Conversations API section and note your. Agent roles don’t have access.
Required to save integration settings in Settings → Integrations.

​
Setup

1

Create a Sunshine App key

In Zendesk, open Admin Center → Apps and integrations → APIs → Conversations API.
  1. Click Create API key.
  2. Label it OpenCX.
  3. Copy the Key ID and Secret — Zendesk only shows the Secret once.
  4. Note the App ID displayed at the top of the page.
Generate an App key, not an Integration key. The Key ID starts with app_ for an App key. Integration keys are scoped to a single Sunshine integration and will fail authentication against OpenCX. If your Key ID doesn’t start with app_, delete it and create a new key from the Conversations API section (not from inside a specific integration).
Lose the Secret? Delete the key and generate a new one. Zendesk does not let you retrieve the Secret after the dialog closes.
2

Turn on multi-conversations for the Sunshine app

OpenCX creates a fresh Sunshine conversation for every chat session. Sunshine’s default personal conversation mode caps each end user at one open conversation, so the second POST /v2/apps/{appId}/conversations for the same user fails and the session never reaches the Agent Workspace. Turn multi-conversations on once, in Zendesk, before you wire up OpenCX.
  1. In Admin Center, go to Channels → Messaging and social → Messaging.
  2. Click Manage settings at the top of the page.
  3. Under Web Widget and Mobile SDKs, expand Multi-conversations and click Set up multi-conversations.
  4. Click Turn on multi-conversations for your account and select every Web Widget, iOS SDK, and Android SDK channel OpenCX will answer on.
  5. Save settings.
See Allowing multiple conversations for your end users for the full Zendesk walkthrough.
This change is irreversible. Once enabled, end users keep access to their conversations list forever — there’s no toggle back to the single-conversation experience. You can later remove the New conversation button from a channel, but the list itself stays. Read Zendesk’s considerations before flipping the switch.
Pick every Web/iOS/Android channel. Turning multi-conversations on for one channel updates the underlying Sunshine app for all Web/iOS/Android channels — channels you leave unselected just lose the New conversation button. Selecting all of them keeps the end-user experience consistent and avoids surprises when you add the next channel. Social channels (WhatsApp, Messenger, Instagram) don’t support multi-conversations and aren’t affected by this setting.
Prefer to flip it without leaving your terminal? Same effect via the Conversations API:
curl -X PATCH "https://api.smooch.io/v2/apps/{APP_ID}" \
  -u "{KEY_ID}:{SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"settings": {"multiConvoEnabled": true}}'
Same irreversibility caveat applies. Confirm with GET /v2/apps/{APP_ID} — settings.multiConvoEnabled should come back true.
3

Open Zendesk Messaging in OpenCX

In OpenCX, go to Settings → Integrations, find Zendesk, and click Zendesk Messaging.
4

Enter your Sunshine credentials

FieldValue
SubdomainThe acme part of acme.zendesk.com. Same subdomain used for Ticketing.
App IDThe Sunshine from the Conversations API page.
Key IDThe ID from the App key you just created — starts with app_.
SecretThe secret you copied.
Integration IDThe ID of the OpenCX Conversations integration in Zendesk (see warning below). Find it under Admin Center → Apps and integrations → Integrations → Conversations integrations.
The Conversations integration MUST be named exactly opencx (lowercase). This name is how OpenCX’s switchboard wiring identifies which integration owns each conversation, and it’s also how the AI agent shows up in Zendesk’s AI Agents Marketplace (next step). Any other spelling — OpenCX, open-cx, opencx-prod, etc. — and routing will silently break.If you’ve already created the integration with a different name, delete it from Conversations integrations and recreate it with the exact name opencx, then copy the new Integration ID here.
Click Verify & Save.
5

Provide a Zendesk API token for user merge

Sunshine uses a separate identity model from Zendesk’s support API. To prevent the same person from showing up as two separate , OpenCX merges Sunshine messaging contacts with matching Zendesk support users.In the Zendesk API credentials panel on the same page, reuse the credentials from the Ticketing API setup. The merge endpoint uses the same token. If you skipped Ticketing, generate a token for this purpose alone — user search is free on every Zendesk plan, and no webhook is needed.
What OpenCX writes on every Sunshine conversation — metadata.opencx_org_id, metadata.opencx_contact_id, and metadata.opencx_session_id. Your reps don’t see these fields directly, but they’re reachable via the Conversations API for debugging and analytics. The session ID is the trace key back to the exact OpenCX conversation.
6

Copy your messaging webhook URL

After saving, OpenCX displays a Messaging Webhook URL. Keep it handy — you’ll paste it into Zendesk next.
7

Register the webhook in Sunshine

In Zendesk’s Conversations API admin, open the Integrations / Webhooks panel for your app and add a new webhook.
FieldValue
Target URLPaste the OpenCX messaging webhook URL.
Triggersconversation:message (required). conversation:read optional, for read receipts.
SecretLeave blank — OpenCX validates by signed URL.
Save the webhook.
8

Pick the channels OpenCX should answer on

Saving credentials only wires up the integration — Zendesk still needs to be told which channels the OpenCX AI agent should actually respond on. This is done from Zendesk’s AI Agents admin (not from OpenCX).
  1. In your Zendesk Admin Center, go to AI → AI agents → AI agents, then click the Marketplace bots tab. (Direct admin URLs are subdomain-scoped, so we can’t link them — see Zendesk’s Managing third-party bots in Admin Center for the canonical walkthrough.)
  2. Find the OpenCX entry in the list of marketplace bots and open it.
  3. Under Channels, pick every channel you want the AI agent to handle — specific WhatsApp numbers, the Web Widget, Facebook Messenger pages, Instagram accounts, SMS numbers, etc. To make OpenCX the first responder for every messaging channel instead, use the entry’s Options → Assign default menu — see Setting an advanced AI agent as the default responder.
  4. Save.
Only channels enabled here are routed to OpenCX. Anything you leave off keeps Zendesk’s default routing (usually straight to the Agent Workspace).
Roll out gradually with a test channel. Don’t flip every production WhatsApp number and your live Web Widget over to the AI agent on day one. Add a single low-stakes channel first — for example a dedicated test WhatsApp number, a sandbox Messenger page, or a staging copy of your Web Widget — and enable only that one in the Marketplace. Run real conversations through it for a few days, watch the Inbox and your handoff rate, then expand to the rest of your channels once you’re happy.
9

Set Conversation control to Release control

The previous step makes OpenCX the first responder. This step makes sure OpenCX takes back the conversation after a human agent solves the ticket — otherwise repeat customers stay routed to Zendesk’s Agent Workspace or zd-answerBot instead of the AI.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.
  1. In Zendesk Admin Center, go to Channels → Messaging and social → Messaging, then open your messaging configuration. (The direct URL is subdomain-scoped: https://<your-subdomain>.zendesk.com/admin/channels/messaging_and_social/messaging/setup.)
  2. Expand the Conversation control section.
  3. Select Release control.
  4. Save.
Release control is required for the per-channel default responder to take effect on handback. With the default Pass control, when an agent solves+closes a ticket, Sunshine passControl’s the conversation to whatever nextSwitchboardIntegrationId is wired on the Agent Workspace integration — usually Zendesk’s own zd-answerBot. With Release control, Sunshine clears the active integration on close, and the customer’s next message gets re-assigned via the per-channel defaultResponder you set in the previous step (= OpenCX). This is the difference between “AI takes back” and “answer bot intercepts.”Sources:
10

Shorten the Solved→Closed window (recommended)

Sunshine only hands control back to OpenCX when a Zendesk ticket transitions from Solved to Closed — not on Solved alone. By default Zendesk waits 4 days between the two. Until close fires, any customer who returns inside that window stays routed to the Agent Workspace, not the AI.To make handback near-instant, do one of:
  • Edit the built-in automation: in Admin Center → Objects and rules → Business rules → Automations, open Close ticket 4 days after status is set to solved and drop the timeframe to ~1 hour (or whatever close-window your team needs for re-opens).
  • Add a close-on-solve trigger: create a trigger that closes any ticket whose status changes to Solved. Handback then fires the instant an agent solves.
Reference: Managing conversation handoff and handback — section “Modifying the time between the solved and closed states”.
Skipping this step doesn’t break the integration — it just means returning customers within the close window land on the Agent Workspace instead of the AI. If your reps and customers are fine with re-engaging via the live agent for a few days post-solve, the default 4-day automation is acceptable.
11

Verify end to end

Run a full handoff + handback cycle on a channel you enabled.
  1. Handoff: send a test message, request a human, confirm the conversation appears in the Zendesk Agent Workspace as a live chat. Reply from Agent Workspace and confirm it lands back on the original channel within a couple of seconds.
  2. Solve and close: solve the ticket from Agent Workspace, then close it (manually, or wait for your trigger / shortened automation from the previous step to fire).
  3. Handback: from the same end user, send a fresh message on the same channel. Confirm the AI responds — not the live agent and not Zendesk’s zd-answerBot.
To pinpoint a routing failure on step 3, inspect the inbound webhook payload in Admin Center → Apps and integrations → Conversations API → Webhooks → Activity. The activeSwitchboardIntegration.name field should be opencx. If it’s zd-answerBot, your Conversation control is still on Pass control — re-check the previous step (set on the Messaging setup page, not the bot entry). If it’s zd-agentWorkspace, the prior ticket hasn’t transitioned from Solved to Closed yet — re-check the Solved→Closed window step.
If any step fails, jump to Troubleshooting.

​
Sunshine channels handle off as live chats, not tickets

For channels routed through Sunshine — WhatsApp, Messenger, Instagram, web chat, SMS, and phone — handoff does not create a Zendesk ticket. The conversation appears in the Agent Workspace as a live chat. Ticket-based behavior (AI Fields auto-fill, tag application, agent-reply sync) described on the Ticketing API page applies to email only.
Conversations may only show up as Zendesk tickets after escalation to a human agent. While OpenCX is handling the conversation autonomously, Zendesk hides it from default ticket views — only when the AI agent hands off does a regular, editable ticket surface in the Agent Workspace.To see AI-only conversations as tickets in the Agent Workspace before they’re escalated, enable AI agent tickets in Zendesk: Admin Center → Channels → Messaging and social → Messaging → Manage settings → AI agent conversations as tickets in Agent Workspace. These tickets are read-only until handoff, but give your reps full visibility into ongoing AI conversations.Full reference: Understanding AI agent tickets for AI agent–only conversations.

​
Rotating Sunshine credentials

Create a new App key in Zendesk, paste it into OpenCX, then delete the old key. The is unaffected by App key rotation.

​
Disconnecting

Click Disconnect on the Zendesk Messaging card in Settings → Integrations. Then delete the webhook in the Conversations API admin. Active conversations finish out on their current channel; no data is deleted from Zendesk.

Channels

Per-channel implementation details for Widget, WhatsApp, SMS, Phone, and Email.

Ticketing API

The companion path for email handoff.

Troubleshooting

Agent Workspace not receiving messages, duplicate users.