Sunshine Conversations

Route chat, SMS, WhatsApp, phone, and social handoffs from OpenCX straight into the Zendesk Agent Workspace.

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 Agent Workspace 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

Zendesk Suite plan with Sunshine provisioned

Open Admin Center → Apps and integrations → APIs → Conversations API. If the section is missing, Sunshine isn’t provisioned on your account — contact Zendesk.

Admin access in Zendesk

You’ll create an App key in the Conversations API section and note your

App ID

. Agent roles don’t have access.

Owner or admin in OpenCX

Required to save integration settings in Settings → Integrations.

Choose authorization

Open Settings → Integrations, select Zendesk → Messaging, then choose:

• OAuth — recommended: install and authorize the OpenCX Marketplace bot. OpenCX provisions the integration webhook automatically; no Sunshine App key is stored.
• Legacy credentials: enter the Sunshine App ID, App key, secret, and integration ID. Existing installations continue to work and can switch to OAuth without deleting their legacy credentials first.

OAuth setup (recommended)

1. Choose Messaging OAuth

   In OpenCX, open Settings → Integrations → Zendesk → Messaging → OAuth, then click Continue to Zendesk.

2. Install and authorize OpenCX

   Sign in to the Zendesk account you want to connect, review the Marketplace bot authorization, and click Allow. OpenCX verifies the individual Zendesk bot installation, claims it for your OpenCX organization, creates the signed webhook, and returns you to a Connected status.

   One Zendesk Marketplace bot installation can belong to only one OpenCX organization. OpenCX rejects a second organization instead of sending the same customer events to two tenants.

3. Assign the bot to a test channel

   In Zendesk Admin Center, open AI → AI agents → AI agents → Marketplace bots → OpenCX. Select one staging Web Widget, mobile, or social channel and save. Expand to production channels only after the test matrix passes.

4. Configure conversation handback

   In Channels → Messaging and social → Messaging, set Conversation control to Release control. Make OpenCX the channel’s default responder and confirm your Solved-to-Closed timing. These routing settings apply to both OAuth and Legacy authorization.

5. Verify end to end

   Send a new message through the assigned channel, confirm an OpenCX session is created, hand off to Zendesk Agent Workspace, reply as an agent, then solve and close the conversation. A later customer message should return to OpenCX and create a new session.

Legacy App key 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. Copy your messaging webhook URL

   OpenCX shows a Messaging Webhook URL on the form right away — you don’t need to save first. Copy it now; you’ll register it in Zendesk in the next step, before you save your credentials.

5. Register the webhook in Sunshine

   In Zendesk’s Conversations API admin, open the Integrations / Webhooks panel for your app and add a new webhook.

   Field	Value
   Target URL	Paste the OpenCX messaging webhook URL.
   Triggers	Enable all triggers. OpenCX needs at minimum conversation:message (inbound messages), conversation:create (drives the connection self-test on save), and switchboard:releaseControl (returns the conversation to the AI after a human resolves it). Missing any of these breaks either setup or handback.
   Secret	Leave blank — OpenCX validates by signed URL.

   Save the webhook.

6. Enter your Sunshine credentials

   Field	Value
   Subdomain	The acme part of acme.zendesk.com. Same subdomain used for Ticketing.
   App ID	The Sunshine App ID from the Conversations API page.
   Key ID	The ID from the App key you just created — starts with app_.
   Secret	The secret you copied.
   Integration ID	The 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 Test and Save.

   Register the webhook first (previous step). Test and Save runs a live connection check — OpenCX opens a test conversation and waits for Zendesk to call your webhook back. If the webhook isn’t registered yet, the check times out with “Waited to receive a webhook callback from Zendesk, but didn’t receive any.” and nothing saves.

7. 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 Zendesk users, 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.

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:

   • Zendesk’s About Sunshine Conversations in Zendesk Suite — section “Configuring conversational control”: “Expand the Conversation control section and select your control option.”
   • Zendesk’s Setting an advanced AI agent as the default responder for a messaging channel — “The Conversation control setting must be set to Release control for per-channel responders to work.”
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.

Turn on AI agent tickets if you want ticket ids before handoff

By default, an AI-handled messaging conversation has no Zendesk ticket until it’s handed off to a human. Zendesk creates the ticket at escalation, and that’s the moment a ticket id appears in the OpenCX Inbox sidebar. A conversation the AI resolves on its own never gets a ticket — so its ticket id in OpenCX stays empty. With the default configuration that’s expected, not a bug.

If you want every conversation — including AI-resolved ones — to have a Zendesk ticket and a ticket id in OpenCX, turn on Zendesk’s AI agent tickets feature:

1. In Zendesk, go to Admin Center → Channels → Messaging and social → Messaging and click Manage settings.
2. Expand AI agent conversations as tickets in Agent Workspace and turn it on.
3. Save.

With the setting on, Zendesk creates a read-only ticket from the first message of every AI conversation (it becomes a regular, editable ticket at handoff), and OpenCX stamps its ticket id on the session automatically — your reps also get full visibility into ongoing AI conversations from the Agent Workspace.

Zendesk turned AI agent tickets on by default for all accounts on May 4, 2026 — but accounts using Zendesk’s own AI agents - Advanced add-on are exempt and may still have it off. If your AI-only conversations aren’t producing tickets, check the setting. References: Understanding AI agent tickets for AI agent–only conversations, general availability announcement, default-on schedule.

Rotating Legacy Sunshine credentials

OAuth has no App key to rotate. For a Legacy connection, create a new App key in Zendesk, paste it into OpenCX, then delete the old key. The webhook signing key is unaffected by App key rotation.

Disconnecting

To stop routing conversations to the AI, remove OpenCX from the channels in Zendesk’s AI Agents admin (un-select the channels you enabled in Pick the channels OpenCX should answer on, or clear it as the default responder). Active conversations finish out on their current channel; no data is deleted from Zendesk.

For OAuth, open Settings → Integrations → Zendesk → Messaging → OAuth, click Disconnect, and type DELETE. This revokes and removes only the OAuth connection and its provisioned webhook; Legacy App credentials remain available. Removing the Marketplace bot in Zendesk also disconnects OpenCX through Zendesk’s verified uninstall callback.

For Legacy authorization, delete the webhook in Conversations API admin to cut delivery, then remove or replace the stored App credentials through the Legacy panel.

---

Related Documentation

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.