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

# Zendesk Telephony

> Connect Zendesk Talk and OpenCX phone agents in both directions — inbound calls forwarded from Zendesk Talk into OpenCX, and outbound transfers from OpenCX into Zendesk via SIP-IN.

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](https://support.zendesk.com/hc/en-us/articles/8397091234586) 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](/channels/phone) if you haven't done that yet.
* The Zendesk integration connected — see the [Zendesk overview](/integrations/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.

### Troubleshooting

<AccordionGroup>
  <Accordion title="`zendesk_ticket_id` never lands on the OpenCX session">
    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).
  </Accordion>

  <Accordion title="`opencx-messaging-ticket-link` webhook doesn't appear in Zendesk">
    The provisioner is best-effort — a transient Zendesk API outage at settings-save time will be logged but won't fail the save. Re-save the Zendesk connection in the OpenCX dashboard to retry.
  </Accordion>
</AccordionGroup>

## 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](https://support.zendesk.com/hc/en-us/articles/8397091234586), 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](https://support.zendesk.com/hc/en-us/articles/8397091234586) 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](https://support.zendesk.com/hc/en-us/articles/8397091234586). 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

<AccordionGroup>
  <Accordion title="Transfer connects but Zendesk shows the wrong caller ID">
    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.
  </Accordion>

  <Accordion title="Transfer fails to connect">
    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.
  </Accordion>
</AccordionGroup>

## Next steps

* [AI Phone Support in the Zendesk Agent Workspace](/integrations/zendesk/channels/phone) — for the messaging-style handoff (Sunshine Conversations) instead of a SIP transfer.
* [Phone channel setup](/channels/phone) — to provision the OpenCX DID that receives forwarded calls.
* [Zendesk overview](/integrations/zendesk/overview) — for ticketing-side configuration.