Ticketing API

Connect Zendesk so email handoffs become tickets your reps work from the inbox they already live in.

The Ticketing API path wires OpenCX into Zendesk’s standard support API. Use it for email — the async channel where every handoff should become a trackable ticket. 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

Zendesk plan with API access

Suite Team or higher, or Support Professional. Suite Growth and above is recommended so you can use triggers for webhook delivery.

Admin access in Zendesk

OAuth requires an agent or admin who can authorize the OpenCX global OAuth client. You also need permission to create a webhook and trigger in Zendesk Admin Center. Legacy setup additionally requires permission to generate an API token.

Owner or admin in OpenCX

Required to save integration settings in Settings → Integrations.

Choose authorization

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

• OAuth — recommended: authorize OpenCX in Zendesk. No API token is stored or rotated.
• Legacy credentials: enter an admin email and API token. Existing installations continue to work and can switch to OAuth without losing their legacy fallback until it is removed.

OAuth setup (recommended)

1. Choose Ticketing OAuth

   In OpenCX, open Settings → Integrations → Zendesk → Ticketing → OAuth.

2. Enter your Zendesk subdomain

   Enter only the acme part of acme.zendesk.com, then click Continue to Zendesk. Do not include https:// or .zendesk.com.

3. Authorize OpenCX

   Sign in to the matching Zendesk account, review the requested Support API access, and click Allow. Zendesk returns you to OpenCX, which verifies the account and displays Connected.

   The Zendesk account you authorize must match the subdomain you entered. OpenCX rejects cross-account callbacks rather than attaching one customer’s OAuth grant to another customer.

4. Register the reply webhook and trigger

   Back in the OAuth panel, copy the signed Reply webhook URL and open its trigger instructions. In Zendesk, create a POST JSON webhook with no additional authentication, then create a trigger with:

   • Meet ANY: Ticket is Created; Ticket is Updated.
   • Meet ALL: Comment is Present (public).
   • Action: Notify active webhook using the OpenCX webhook.
   • JSON body:

   {
     "ticketId": "{{ticket.id}}",
     "event_type": "new_comment"
   }
   

   OAuth authenticates OpenCX’s calls to Zendesk; the trigger is still required for Zendesk to deliver public agent replies back to OpenCX.

5. Verify end to end

   Escalate a test email, confirm the Zendesk ticket has the opencx tag, then post a public agent reply. The reply should appear on the matching OpenCX session. Internal notes must remain private.

Legacy API token setup

1. Generate a Zendesk API token

   In Zendesk, open Admin Center → Apps and integrations → APIs → Zendesk API → API Tokens → Add API token.

   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

   Field	Value
   Subdomain	The acme part of acme.zendesk.com. Do not include .zendesk.com or https://.
   Email	The admin email that owns the API token.
   API Token	The token you just copied.
   Default Agent ID	Required. The numeric Zendesk user ID used as the fallback assignee when no routing rule applies. To find it: in Zendesk, open the agent’s profile page (Admin Center → People → Team members → click the agent). The ID is the number at the end of the URL — e.g. in https://your-subdomain.zendesk.com/agent/users/1234567890/tickets/requested, the Default Agent ID is 1234567890.

   Click Test & 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, follow Zendesk’s guide to creating a webhook to open Admin Center → Apps and integrations → Webhooks, then click Create webhook → Trigger or automation.

   Field	Value
   Name	OpenCX
   Endpoint URL	Paste the OpenCX webhook URL.
   Request method	POST
   Request format	JSON
   Authentication	None — the URL is already signed.

   Save the webhook.

6. Create the trigger that fires the webhook

   Follow Zendesk’s guide to creating a trigger to open Admin Center → Objects and rules → Triggers and click Create trigger.

   Configure:

   • Trigger name: OpenCX webhook (or anything recognizable).
   • Category: pick an existing category such as Notifications, or create a new one (e.g. OpenCX).
   • Conditions → Meet ANY of: Ticket → Is → Created; Ticket → Is → Updated.
   • Conditions → Meet ALL of: Comment → Is → Present (public).

   You need both Created and Updated under Meet ANY of. Is → Updated alone does not fire on ticket creation, so brand-new tickets would never reach OpenCX.

   • Actions → Notify by → Active webhook, then select OpenCX from the dropdown.
   • JSON body — paste exactly:

   {
     "ticketId": "{{ticket.id}}",
     "event_type": "new_comment"
   }
   

   Both keys are required and case-sensitive: ticketId (camelCase) and event_type set to the literal string new_comment. OpenCX rejects any other shape with 400 ticketId is required. Do not put the comment text in the body — OpenCX fetches the comment from Zendesk itself, and only ever reads the ticket’s public comments, so internal notes never leak to the customer.

   Click Create trigger and save.

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 handoff 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 external_id, 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.

With this flag on, tickets created at handoff are assigned to your Default Agent Group (if set) rather than the Default Agent ID — the individual-agent assignment in step 5 above applies only to the standard, ticket-created-early flow.

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.

Internal notes 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 custom fields to AI-generated values so triage, routing, and reporting work on day one. Configure at Settings → Ticketing under Auto fill Zendesk fields.

1. Pick a Zendesk field

   OpenCX loads every custom field on your Zendesk account. Pick one — dropdown (tagger) 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

Tag	When
opencx	Always, on any ticket OpenCX creates or writes to.
opencx_autopilot	The AI was in autopilot (resolved or handed off without a rep present).
opencx_assist_mode	The AI posted an internal note on an agent-owned ticket (Assist Mode — a discouraged fallback).
opencx_handedoff	The 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_handoff	Applied when the ticket was created at handoff (vs updated on a returning contact).

Use these tags in Zendesk views, triggers, and reports.

Rotating Legacy credentials

OAuth access is refreshed automatically and has no API token to rotate. For a Legacy connection, 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

For OAuth, open Settings → Integrations → Zendesk → Ticketing → OAuth, click Disconnect, and type DELETE. This revokes and removes only the OAuth connection; complete Legacy credentials remain available. Delete or deactivate the Zendesk trigger and webhook as well if you want public-comment delivery to stop. Tickets created while the integration was active remain untouched.

For Legacy authorization, remove or replace the saved credentials through the Legacy panel. Deactivating the Zendesk trigger and webhook stops new inbound events immediately.

---

Related Documentation

AI Email in Zendesk

Per-channel implementation details for email handoff.

Sunshine Conversations

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

Troubleshooting

Webhook 4xx, trigger not firing, credentials failing.