Skip to main content
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

Open Zendesk Messaging in OpenCX

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

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.
Click Verify & Save.
4

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.
5

Copy your messaging webhook URL

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

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.
7

Verify end to end

Send a test message on a connected messaging channel (web widget, WhatsApp sandbox, or SMS). Escalate the conversation.
  1. The conversation appears in the Zendesk Agent Workspace as a live chat.
  2. Reply from the Agent Workspace.
  3. The reply lands back on the original channel within a couple of seconds.
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.

​
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.

Assist Mode

AI-drafted internal notes on tickets your reps already own.

Troubleshooting

Agent Workspace not receiving messages, duplicate users.