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.

OpenCX phone agents and Zendesk Talk integrate in two directions, each with its own setup. Inbound uses standard Zendesk Talk call forwarding to an OpenCX phone number. Outbound transfers ride over Zendesk’s SIP-IN line so the call lands directly inside the Agent Workspace with a recoverable ticket id. This page covers both. Pick the section that matches the leg you’re configuring.

​
Receiving inbound calls (Zendesk Talk → OpenCX)

Use this when you want the OpenCX AI phone agent to answer first — for triage, qualification, deflection, or full automation — before optionally handing the call to a human in Zendesk. Zendesk Talk does not support SIP-OUT or custom SIP headers when forwarding outbound. The only supported transport from Zendesk Talk to an external system is plain PSTN call forwarding to a regular phone number, which strips all metadata. To work around this, OpenCX subscribes a webhook to Zendesk’s ticket.created event and uses it to correlate the new phone-channel ticket back to the OpenCX phone session created when the call lands on our SIP. The matched ticket id is stamped on the OpenCX session, and the ticket’s requester is fetched to enrich the OpenCX contact with verified name, email, phone, and any configured Zendesk user/organization attributes.

​
Prerequisites

  • A phone number provisioned and verified in OpenCX. See phone setup if you haven’t done that yet.
  • The Zendesk integration connected — see the Zendesk overview. Saving the Zendesk connection auto-provisions the ticket.created event-subscription webhook against your account; no manual webhook or trigger setup is required.

​
Step 1 — Connect Zendesk in OpenCX

Open the OpenCX dashboard → Integrations → Zendesk → Connect, paste your subdomain + API token + agent email, and save. On save OpenCX upserts an event-subscription webhook named opencx-messaging-ticket-link in your Zendesk account, pointing at the OpenCX receiver and subscribed to messaging_ticket.message_added, ticket.status_changed, and ticket.created. The webhook is idempotent — re-saving the connection is safe and won’t disturb any of your other webhooks, triggers, or automations.

​
Step 2 — Forward the call to OpenCX

Configure your Zendesk Talk number (or IVR / call queue branch) to forward to your verified OpenCX phone number using Zendesk Talk’s standard forwarding flow. Nothing OpenCX-specific is required at this step — the auto-provisioned webhook carries the metadata; the call itself rides over PSTN.

​
Contact enrichment

When the webhook matches a live OpenCX session, OpenCX fetches:
  • the Zendesk ticket identified by ticket_id, and
  • the ticket requester (ticket.requester_id).
OpenCX then updates the session’s linked contact with:
  • requester name,
  • requester email,
  • requester phone,
  • Zendesk user id / external id, and
  • Zendesk user fields plus organization fields in contact custom_data (organization fields are prefixed with org_, matching the regular Zendesk chat webhook behavior).
This is intentionally driven by the ticket id, not by searching Zendesk users by phone number. Zendesk’s phone search can return fuzzy/prefix matches, which is not safe enough for identity enrichment.

​
Troubleshooting

Open the OpenCX-managed webhook in Admin Center → Apps and integrations → Webhooks → opencx-messaging-ticket-link → Activity and confirm ticket.created deliveries are firing and responding 200. If deliveries are missing entirely, re-save the Zendesk connection in the OpenCX dashboard — the provisioner runs again on each save and is safe to re-trigger. If deliveries are firing but the OpenCX session is not getting stamped, double-check that the inbound caller’s phone digits match the contact phone OpenCX recorded for the call (PSTN forwarding occasionally strips/rewrites the From number depending on your carrier configuration).

​
Transferring calls from OpenCX to Zendesk (SIP-IN)

Use this when the OpenCX AI agent has triaged the call and needs to hand it to a human agent in Zendesk Talk. The transfer rides over Zendesk SIP-IN, which means the call shows up natively inside the Agent Workspace as a Zendesk Talk call — the agent picks it up, sees the caller ID, and (when the ticket id is known) can correlate the leg back to the ticket OpenCX received the call against.

​
How it works

OpenCX initiates a SIP outbound bridge to your Zendesk SIP-IN line and attaches the original caller’s phone as the From and the originating Zendesk ticket id (when known) as X-Zendesk-Ticket-Id — Zendesk SIP-IN’s documented header for binding the inbound SIP leg to an existing voice ticket. Without it, Zendesk Talk creates a brand-new ticket for the inbound INVITE and the leg gets orphaned from the originating ticket. Every transferred leg carries:
  • X-Zendesk-Ticket-Id — the originating Zendesk ticket id, only when:
    • the active OpenCX session has a ticket id stamped on it (from the inbound flow above), and
    • the destination is a SIP URI (PSTN-only destinations don’t carry the header).
  • X-OPENCX-SESSION-ID — the OpenCX phone session id.
  • X-OPENCX-AGENT-ID — the OpenCX AI agent id.
  • X-OPENCX-TRANSFER — true.
  • X-OPENCX-CONTACT-ID — the OpenCX contact id (when resolved).
The originating caller’s phone number is preserved as the From so Zendesk Talk renders the correct caller ID inside the Agent Workspace.

​
Prerequisites

  • A configured Zendesk SIP-IN line — follow the Zendesk SIP-IN setup docs. You’ll end up with a SIP URI of the form sip:<your-line>@<subdomain>.zendesk.sip.twilio.com.
  • An OpenCX AI phone agent with at least one transfer destination configured.

​
Step 1 — Add the Zendesk SIP-IN URI as a transfer destination

In the OpenCX dashboard, open the AI phone agent’s settings and add a new Transfer destination of type SIP. Paste the SIP URI from your Zendesk SIP-IN line as the destination URI, and give it a label your AI agent will recognize (“Zendesk human agent”, “Tier 2”, etc.). The AI agent then picks this destination at runtime when the conversation logic — your prompt, knowledge, or tools — decides to hand off.

​
Step 2 — (Optional) Confirm ticket re-association on the Zendesk side

If you’ve also configured the inbound flow above, every transfer leg will carry X-Zendesk-Ticket-Id whenever the ticket id was successfully stamped on the OpenCX session. Zendesk SIP-IN reads the header natively: the inbound leg is associated with the existing voice ticket (which must have been created with via_id: 34 — Zendesk Talk’s own inbound calls always satisfy this) instead of spawning a duplicate. No Zendesk-side trigger or app is required.

​
What does not work

  • PSTN-only transfers (carrier-issued REFER to a regular phone number) won’t reach Zendesk Talk natively — Zendesk Talk only accepts inbound SIP via SIP-IN. If your transfer destination is a regular phone number rather than a SIP URI, the call will route through your carrier as a normal outbound, not through Zendesk.
  • Zendesk SIP-OUT. Zendesk Talk does not support SIP-OUT, which is why the inbound direction has to use PSTN forwarding plus the ticket.created webhook.

​
Troubleshooting

Double-check that the OpenCX session knows the caller’s phone number. SIP transfers use the original caller’s phone as the From — if the inbound leg arrived without caller ID (anonymous, blocked, or stripped by an upstream IVR), Zendesk will see the OpenCX-side From instead. There’s no workaround for an anonymous caller.
Confirm the SIP-IN URI is correct and reachable from your OpenCX SIP egress IP range — Zendesk SIP-IN requires IP allow-listing on the Zendesk side. See the Zendesk SIP-IN docs for the current allow-list values.

​
Next steps