Skip to main content
The Ticketing API path wires OpenCX into Zendesk’s standard . Use it for email — the async channel where every handoff should become a trackable . Chat, SMS, WhatsApp, phone, and social belong on Sunshine Conversations instead.
Setup takes about 15 minutes. You need a Zendesk admin role on both sides — your OpenCX organization and your Zendesk account.

​
Before you start

Suite Team or higher, or Support Professional. Suite Growth and above is recommended so you can use for webhook delivery.
You need to generate an API token, create a webhook, and create a trigger. All three live in Zendesk Admin Center — agent roles cannot reach them.
Required to save integration settings in Settings → Integrations.

​
Setup

1

Generate a Zendesk API token

In Zendesk, open Admin Center → Apps and integrations → APIs → Zendesk API.
  1. Toggle Token access on.
  2. Click Add API token.
  3. Label it OpenCX (or anything recognizable).
  4. Copy the token immediately — Zendesk hides it after you close the dialog.
The token is bound to the user whose email you provide in the next step. If that user is deactivated or loses permission, the integration stops working.
2

Open Zendesk Ticketing in OpenCX

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

Enter your credentials

FieldValue
SubdomainThe acme part of acme.zendesk.com. Do not include .zendesk.com or https://.
EmailThe admin email that owns the API token.
API TokenThe token you just copied.
Default Agent IDOptional. The numeric to assign tickets to when no routing rule applies. Leave blank to create tickets unassigned.
Click Verify & Save. OpenCX hits the Zendesk API with your credentials before persisting — a wrong subdomain or token returns an error and nothing saves.
4

Copy your webhook URL

After saving, OpenCX displays a Webhook URL unique to your organization. Keep this tab open — you’ll paste it into Zendesk next.
The webhook URL is signed and secret. Anyone who has it can post events into your OpenCX session pipeline. Treat it like a password.
5

Register the webhook in Zendesk

In Zendesk, open Admin Center → Apps and integrations → Webhooks and click Create webhook → Trigger or automation.
FieldValue
NameOpenCX
Endpoint URLPaste the OpenCX webhook URL.
Request methodPOST
Request formatJSON
AuthenticationNone — the URL is already signed.
Save the webhook.
6

Create the trigger that fires the webhook

Open Admin Center → Objects and rules → Triggers and click Add trigger.Configure:
  • Conditions → Meet ALL of: Ticket | Is | Updated; Comment | Is | Present (public).
  • Actions: Notify active webhook → OpenCX.
  • JSON body — include at minimum:
{
  "ticket_id": "{{ticket.id}}",
  "comment": "{{ticket.latest_public_comment}}",
  "author_id": "{{ticket.latest_public_comment.author_id}}"
}
Use {{ticket.latest_public_comment}}, not {{ticket.latest_comment}}. The second variant includes internal notes and will leak them to the customer.
Save and activate the trigger.
7

Verify end to end

Send a test email to an address you have connected to OpenCX email handoff. Escalate the conversation. Within a few seconds:
  1. A ticket appears in Zendesk, tagged opencx.
  2. Reply publicly from Zendesk.
  3. The reply appears as an agent message on the matching session in your OpenCX Inbox.
Every OpenCX ticket is traceable back to its session. The session UUID is written to the ticket’s external_id, and the first comment includes a View session in OpenCX link that opens the full AI reasoning, tool calls, and transcript in your inbox. Filter Zendesk views by external_id or any opencx_* tag described below.
If any step fails, jump to Troubleshooting.

​
How handoff lands in Zendesk

When triggers, OpenCX does the following in Zendesk:
  1. Looks up the contact by email. If not found, creates a Zendesk user with the contact’s email and name.
  2. Creates a ticket with the session ID as , the conversation summary as the description, and the full transcript appended as the first comment.
  3. Applies tags (see Tags OpenCX applies below) so your views and triggers can filter by mode, channel, sentiment, and language.
  4. Auto-fills any custom fields you’ve mapped (see AI Fields below).
  5. Assigns to your Default Agent ID if configured; otherwise leaves unassigned for Zendesk routing to handle.
The session is linked to the ticket by external_id. If the same contact re-engages before the ticket is closed, OpenCX appends to the existing ticket instead of opening a new one.

​
Create a ticket only on handoff

By default OpenCX only creates a ticket when the AI escalates. If you want every conversation to create a ticket up front (for audit or SLA reasons), reach out to support — this flag is set per organization.

​
Rep replies sync back

When a rep posts a public reply in Zendesk, the webhook fires and OpenCX:
  1. Matches the ticket to the original session using external_id.
  2. Sends the reply to the contact on the original channel — email, SMS, WhatsApp, web widget, etc.
  3. Marks the session as having an active human agent so the AI stops auto-responding.
are ignored — your reps can take private notes in Zendesk without triggering outbound messages.
Only public comments sync. If a rep accidentally posts to the wrong ticket, the message still reaches that ticket’s linked contact. Treat Zendesk tickets as customer-visible threads.

​
AI Fields

Map Zendesk to AI-generated values so triage, routing, and reporting work on day one. Configure at Settings → Ticketing under Zendesk AI Fields.
1

Pick a Zendesk field

OpenCX loads every custom field on your Zendesk account. Pick one — dropdown () and free-text fields are supported.
2

Describe what the AI should fill

Write a short description of what the field represents. For dropdowns, OpenCX picks from existing options only. For text, OpenCX writes a short value.Example description for a Reason dropdown: “The primary reason the contact is writing. Pick the closest match from the allowed values.”
3

Enable

Toggle the mapping on. The next ticket OpenCX creates (or updates on handoff) includes the auto-filled value.
Keep descriptions short and concrete. Fields with vague descriptions (“customer feedback”) produce vague values.

​
Tags OpenCX applies

TagWhen
opencxAlways, on any ticket OpenCX creates or writes to.
opencx_autopilotThe AI was in autopilot (resolved or handed off without a rep present).
opencx_assist_modeThe AI posted an internal note on an agent-owned ticket.
opencx_handedoffThe AI escalated to a human rep.
opencx_channel_<name>The source channel — email, whatsapp, sms, web, phone.
opencx_sentiment_<value>Detected sentiment on handoff — happy, neutral, negative.
opencx_language_<code>Detected conversation language.
opencx_ticket_created_on_handoffApplied when the ticket was created at handoff (vs updated on a returning contact).
Use these tags in Zendesk views, triggers, and reports.

​
Rotating the API token

Regenerating the Zendesk API token does not affect the webhook — the webhook URL is signed with a separate key. To rotate:
  1. Create a new token in Zendesk.
  2. Paste it into Settings → Integrations → Zendesk.
  3. Delete the old token in Zendesk.

​
Disconnecting

In OpenCX, open the Zendesk integration and click Disconnect. Then in Zendesk, delete the webhook and the trigger you created. Tickets created while the integration was active remain untouched.

AI Email in Zendesk

Per-channel implementation details for email handoff.

Sunshine Conversations

The path for chat, SMS, WhatsApp, phone, and social channels.

Assist Mode

Draft internal notes on agent-owned tickets.

Troubleshooting

Webhook 4xx, trigger not firing, credentials failing.