Zendesk integration

Vobiz Calling puts a softphone in the Zendesk top bar. Your agents sign in with their Vobiz account, call customers from the panel or from a ticket, take inbound calls in the browser, and every call is written back to Zendesk with its duration and a link to the recording. No desk phone, no desktop software, and no Zendesk Talk subscription. The integration is a Zendesk Support app plus a small Node.js backend that you host. Both are in one repository: vobiz-ai/Vobiz-Zendesk-Calling.

What you get

Click-to-call

Dial from the panel, or click Call requester in the ticket sidebar. With Talk Partner Edition, clicking any phone number in Zendesk dials it too.

Inbound in the browser

Calls to your Vobiz number ring every signed-in agent of that Vobiz account.

Screen pop

The caller is looked up in Zendesk by phone number while the call rings. Answering opens their profile.

Call logging

A private note on the open ticket, or a new ticket, with direction, numbers, duration and a recording link.

Recordings

Every call is recorded. Play recordings of calls made through the panel, or from the signed, expiring link in the ticket.

Caller-ID choice

Pick which of your Vobiz numbers to call from.

Each Zendesk agent gets their own SIP endpoint in your Vobiz account, set up automatically. Agents can also sign in directly with an existing SIP endpoint.

How it works

 Zendesk (agent's browser)                    Your backend                 Vobiz
 ┌──────────────────────────────┐  HTTPS   ┌──────────────────┐  REST   ┌─────────────────┐
 │ top bar   softphone panel    │────────▶ │ backend/         │───────▶ │ api.vobiz.ai    │
 │ sidebar   Call requester     │          │ server.js        │ ◀────── │ (webhooks:      │
 │ background click-to-dial     │          └──────────────────┘ answer, │  /answer, ...)  │
 └──────────────┬───────────────┘                               status  └────────┬────────┘
                │            SIP over WebSocket (audio)                         │
                └───────────────────────────────────────────▶ registrar.vobiz.ai ── phone network

The panel runs in the Zendesk top bar. A ticket-sidebar part tells it which ticket is open and offers Call requester. A background part relays Zendesk’s click-to-dial event.
When an agent signs in, the backend checks the Auth ID and Auth Token with Vobiz and sets up what it needs inside that Vobiz account.
The browser registers with Vobiz as a SIP endpoint and carries the call audio over WebRTC. Your microphone and speakers are the phone.
To call out, the browser starts the call. Vobiz asks your backend’s /answer URL what to do, and the backend tells Vobiz to record the call and dial the customer from your chosen number.
For inbound calls, Vobiz asks the same /answer URL, and the backend rings the signed-in agents of the Vobiz account that owns the number.
When the call ends, the panel writes the call log to Zendesk.
Recording audio is fetched from Vobiz by the backend and streamed to the agent through a signed link. Your Auth Token never reaches the browser.

Outbound call flow: the agent clicks Call, the browser starts the call, Vobiz fetches the backend's answer URL, the backend answers with Record and Dial Number, and Vobiz dials the customer and connects the call.

Prerequisites

Requirement	Detail
Vobiz account	Your Auth ID and Auth Token from the Vobiz Console → API credentials (the Auth Token is not your login password). At least one active, voice-enabled phone number, and enough balance for calls.
Zendesk	Zendesk Support with admin access. Trying the app locally with `zcli apps:server` works on any plan, including a trial. Uploading it as a private app for your team needs Suite Growth or higher, or Support Professional or higher. Zendesk Talk is not needed.
A public HTTPS URL	Vobiz must reach your backend from the internet. Use a tunnel (`cloudflared`, `ngrok`) to try it, and a stable HTTPS hostname in production.
Node.js	Version 18 or newer.
Browser	A current Chrome, Edge or Firefox with a working microphone. Allow microphone access when asked.

Every call is a real call and is charged to your Vobiz balance. An outbound call has two legs - the agent’s browser and the customer - and both are billed.

Set up

Clone and install

git clone https://github.com/vobiz-ai/Vobiz-Zendesk-Calling.git
cd Vobiz-Zendesk-Calling
npm install --prefix backend
cp backend/.env.example backend/.env

Expose port 8092 over HTTPS

In a second terminal:

npm run tunnel        # runs: cloudflared tunnel --url http://localhost:8092

Copy the https://… URL it prints.

Quick tunnels get a new hostname every time they restart. They are fine for trying the app; use a stable hostname in production.

Configure backend/.env

backend/.env holds deployment settings only. Never put a Vobiz Auth ID, Auth Token, SIP password or phone number in it - agents sign in from the panel.

backend/.env

PUBLIC_BASE=https://calling.example.com     # the HTTPS URL from the previous step
SIGNING_SECRET=                             # paste the output of: openssl rand -hex 32

All other settings are optional. See Configuration.

Start the backend and check it

npm start             # → http://localhost:8092

From outside your network, check that Vobiz can reach it:

curl -s -X POST "https://calling.example.com/answer" \
  -d "From=sip:test@registrar.vobiz.ai&To=91XXXXXXXXXX&RouteType=sip"

You should get XML back. The test caller is not signed in, so it ends with <Hangup reason="rejected"/> - that is expected. An error page or a timeout means Vobiz cannot reach your backend.

Run the Zendesk app locally

cp zcli.apps.config.json.example zcli.apps.config.json

zcli.apps.config.json

{
  "parameters": {
    "backend_url": "https://calling.example.com"
  }
}

npx @zendesk/zcli apps:server

Open https://<your-subdomain>.zendesk.com/agent/dashboard?zcli_apps=true. The Vobiz icon appears in the top bar. If the panel stays blank, allow your browser’s local network access prompt for localhost:4567.

Zendesk top bar showing the Vobiz Calling icon — The Vobiz Calling softphone in the Zendesk top bar.

Open the panel, sign in on the Vobiz account tab, wait for READY, pick a caller ID and call. The next sections explain each part.

To roll the app out to your whole team, see Deploy to production. The panel has two tabs: Vobiz account and SIP direct.

The Vobiz Calling panel open over the Zendesk agent interface, showing the status badge and step 1 Sign in to Vobiz — The panel on load, inside Zendesk.

Vobiz account (recommended)

Enter your Auth ID (MA_XXXXXXXX) and Auth Token, then click Log in. The backend checks them with Vobiz. A wrong pair is refused and nothing is created. On a successful sign-in, the backend sets up the following in your Vobiz account. You never create these by hand.

One application named Zendesk-Calling-Vobiz, with answer URL <PUBLIC_BASE>/answer (method POST). If an application with that answer URL already exists, it is reused. An application with any other answer URL is never changed.
One SIP endpoint per Zendesk agent, attached to that application. Each sign-in sets a fresh random SIP password on it. Only that browser session receives the password, and it is never written to disk.

The panel showing the Auth ID and Auth Token fields, a Logged in as line with the calling-from number, and the Choose a caller ID step — Signed in, with the caller ID chosen.

Choose a caller ID. The Calling from dropdown lists your account’s active, voice-enabled numbers. Calls go out from the number you pick, and the backend refuses any number that is not on your account. The panel remembers your last choice until the backend restarts.

The Calling from field expanded into a dropdown of Vobiz numbers, with the Call button below — Any of your active numbers can be the caller ID.

SIP direct

Use this to sign in as one existing SIP endpoint, without account-wide credentials. Enter the endpoint’s SIP username and SIP password (Console → Voice → Endpoints), and the number to call from in Calling from (+91XXXXXXXXXX), then click Connect. The password goes straight from your browser to Vobiz; the backend never receives it. Nothing is set up for you in this mode. Before you connect, point the endpoint and your number at an application whose answer URL is your backend’s /answer.

Console
API

Voice → Applications → create an application with answer URL https://calling.example.com/answer, method POST.
Voice → Endpoints → your endpoint → set its application to that one.
Phone Numbers → your number → attach it to the same application.

# 1. Create the application. Note the app_id in the response.
curl -X POST "https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/Application/" \
  -H "X-Auth-ID: MA_XXXXXXXX" -H "X-Auth-Token: $VOBIZ_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_name":"Zendesk-Calling-Vobiz","answer_url":"https://calling.example.com/answer","answer_method":"POST"}'

# 2. Attach the endpoint. Copy the app_id exactly as returned, as a string.
curl -X POST "https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/Endpoint/<endpoint_id>/" \
  -H "X-Auth-ID: MA_XXXXXXXX" -H "X-Auth-Token: $VOBIZ_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"app_id":"<app_id>"}'

# 3. Attach the number, for inbound calls (%2B is the leading +).
curl -X POST "https://api.vobiz.ai/api/v1/Account/MA_XXXXXXXX/numbers/%2B91XXXXXXXXXX/application" \
  -H "X-Auth-ID: MA_XXXXXXXX" -H "X-Auth-Token: $VOBIZ_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"application_id":"<app_id>"}'

See Create an application, Update an endpoint and Attach a number.

In SIP direct mode:

The number you type is used as the caller ID and as the inbound number that rings you. Vobiz refuses a caller ID that the endpoint’s account does not own.
The caller-ID dropdown, Enable inbound calls and the recordings list are not available. Calls are still recorded in Vobiz, but ticket notes carry no recording link.
Call logs are always written through your own Zendesk session.
Remember username and caller ID keeps those two in this browser. The password is never stored; you type it each time.

Enable inbound calls

In Vobiz account mode, under Receive calls here, click Enable inbound calls once. This attaches the selected number to the Zendesk-Calling-Vobiz application, so calls to that number ring the panel.

A number can be on only one Vobiz application. Enabling inbound moves the number off the application it is on now. Before you click, the panel shows the ID of that application. Signing in alone never moves a number.

Using it

Outbound calls

Wait for the READY badge. Call stays disabled until the panel is signed in and registered with Vobiz.
Type the number in international format (+91XXXXXXXXXX) and click Call, or press Enter. Or open a ticket and click Call requester in the Vobiz sidebar - it uses the phone number on the requester’s profile.
Allow microphone access the first time. Click Hang up to end the call.

The panel during a live call showing the Number to call field, a red Hang up button and an On a call with status line — An active call.

Inbound calls

Keep the panel signed in and READY. When a call arrives, the panel opens, plays a ring tone, shows a Zendesk notification and the caller’s number, and adds their name if a Zendesk user has that phone number. Click Accept or press Enter to answer - this also opens the caller’s Zendesk profile. Click Decline or press Escape to reject. A call rings for 30 seconds. If no agent of that account is signed in, the caller hears “Sorry, no one is available to take your call. Please try again later.” and the call ends.

Call logging

When a call ends, the panel writes it to Zendesk:

Outbound call made while a ticket is open: a private internal note on that ticket.
Outbound call with no ticket open, and every inbound call: a new ticket, type Task, status Solved, with the matched Zendesk user (if any) as the requester.

The note starts with [Vobiz Call Log] and lists the date, direction, phone number(s), duration and a Listen to Call Recording link.

A Zendesk ticket showing the Vobiz Call Log note with direction, duration, recording link and status — A call log on a ticket, as an internal note.

Who writes it depends on your backend settings:

ZENDESK_SUBDOMAIN, ZENDESK_EMAIL and ZENDESK_API_TOKEN set: the backend writes the log as that Zendesk user. If your Zendesk account has Talk Partner Edition, the backend writes a Talk voice comment (or voice ticket) instead of a plain note.
Left blank (or if the backend write fails): the panel writes the log through the signed-in agent’s own Zendesk session, so it is attributed to the agent.

An optional webhook, POST /transcription-ready, appends a transcript to a ticket as a private note. It is off unless TRANSCRIPTION_WEBHOOK_SECRET is set, and the caller must send Authorization: Bearer <that secret>.

Recordings

Every call is recorded (MP3, up to one hour per call).

In the panel: Recordings of calls made here lists up to 10 recent recordings of calls this backend handled for your Vobiz account.
In the ticket: the recording link plays once Vobiz has finished processing the file, usually within a minute. Until then it answers “The recording is still processing”. Ticket links expire after 7 days by default.

The browser audio player for a call recording — Playing a recording in the browser.

Configuration

Zendesk app settings

Set these in Admin Center → Apps and integrations → Zendesk Support apps → Vobiz Calling → Settings, or in zcli.apps.config.json when running locally.

Setting	Label	Required	Default	Meaning
`backend_url`	Backend URL	Yes	-	Public HTTPS base URL of your backend, no trailing slash. `http://localhost` is accepted for local testing only.
`registrar_url`	SIP registrar URL	No	`wss://registrar.vobiz.ai:5063/`	The Vobiz SIP-over-WebSocket address. Leave it unless Vobiz support tells you otherwise.

Backend environment variables

Set in backend/.env or the process environment.

Variable	Required	Default	Meaning
`PUBLIC_BASE`	Yes	-	Your backend’s public HTTPS URL. Vobiz calls `<PUBLIC_BASE>/answer`, `/dial-status` and `/recording-ready`. Sign-in is refused until this is an `https://` URL.
`SIGNING_SECRET`	Yes in production	random at each start	Signs recording links. If unset, a new one is made on every restart and older links stop working. Generate with `openssl rand -hex 32`.
`PORT`	No	`8092`	Port the backend listens on.
`DATA_DIR`	No	`backend/data`	Folder for the agent → SIP endpoint map (IDs and usernames only).
`VOBIZ_REGISTRAR`	No	`registrar.vobiz.ai`	Vobiz SIP registrar host.
`RECORDING_URL_TTL_SECONDS`	No	`300`	How long recording links in the panel stay valid.
`TICKET_RECORDING_LINK_TTL_SECONDS`	No	`604800` (7 days)	How long recording links written into tickets stay valid.
`ZENDESK_SUBDOMAIN`	No	-	Your Zendesk subdomain, e.g. `acme`. Set all three `ZENDESK_*` values to have the backend write call logs.
`ZENDESK_EMAIL`	No	-	Email of the Zendesk user the backend writes as.
`ZENDESK_API_TOKEN`	No	-	A Zendesk API token (Admin Center → Apps and integrations → APIs → Zendesk API).
`TRANSCRIPTION_WEBHOOK_SECRET`	No	-	Turns on `POST /transcription-ready`; callers send it as a Bearer token.
`ALLOWED_ORIGINS`	No	-	Extra browser origins allowed to call the backend, comma-separated. Zendesk’s app origins and localhost are always allowed.
`ZENDESK_MARKETPLACE_NAME`, `ZENDESK_MARKETPLACE_ORG_ID`, `ZENDESK_MARKETPLACE_APP_ID`	No	-	Identification headers on the backend’s Zendesk API requests. Only needed for a Zendesk Marketplace listing.

Deploy to production

The backend

Serve it on a stable HTTPS hostname. Quick tunnels change hostname on restart.
Run exactly one instance. Sign-ins, Auth Tokens and recent calls are kept in memory, so a second instance would not know about agents signed in to the first.
Set SIGNING_SECRET to a fixed random value so recording links survive restarts.
Put DATA_DIR on persistent storage so each agent keeps the same SIP endpoint across redeploys.
Run it under a process manager. After any restart, agents must sign in again.

If your backend sits behind an IP allowlist, see IP whitelisting. The Zendesk app

Build the package

From the repository root:

npm run package     # writes Vobiz-Zendesk-Calling.zip, no Zendesk login needed

Or, after npx @zendesk/zcli login -i, run npx @zendesk/zcli apps:validate . and npx @zendesk/zcli apps:package .. The backend is never included in the package.

Upload it as a private app

In Zendesk, go to Admin Center → Apps and integrations → Zendesk Support apps → Upload private app, and upload the zip. This needs Suite Growth or higher, or Support Professional or higher.

Fill in the settings and install

Set Backend URL to your backend’s HTTPS URL.

One installation serves every agent. Each agent gets their own SIP endpoint, keyed by their Zendesk user ID.

Security and privacy

Your Auth Token never leaves the server and is never stored on disk. It is kept in the backend’s memory only, never sent back to the browser, never logged and never written into a ticket. After sign-in the browser holds only an opaque session token, valid for 12 hours.
The SIP password reaches only the signed-in browser. WebRTC needs it to register. It is minted fresh at each sign-in, served only to that session, and never stored in the browser. In SIP direct mode it never reaches the backend at all.
On disk, the backend keeps only DATA_DIR/endpoints.json: each Auth ID and Zendesk user ID mapped to its SIP endpoint ID and username. No password, no token.
Recording links are signed and expire. They carry no credentials, are tied to one Vobiz account, and expire after 5 minutes (panel) or 7 days (tickets). The backend fetches the audio from Vobiz itself and never fetches a URL supplied by the caller.
Zendesk credentials are fixed on the server. The subdomain, email and API token come only from backend/.env.
Caller IDs are checked. In Vobiz account mode, only numbers on that account can be used. Every value placed in the call instructions is validated and escaped.
CORS is restricted to Zendesk’s app origins, localhost, and ALLOWED_ORIGINS.
Vobiz webhooks are not signature-checked. /answer, /dial-status and /recording-ready must be public. A forged request can at most add a fake entry to the in-memory call list; it cannot obtain credentials or place calls to arbitrary numbers.

Troubleshooting

The panel says “Not configured” or “Backend URL must start with https://”

An app setting is empty, or Backend URL is plain http:// and not localhost. Fill in Backend URL (your backend’s HTTPS URL), then reload.

The panel says “Cannot reach the calling backend”

The backend is down, the URL is wrong, or the browser blocked the request. Open https://<backend>/health in a browser. If you load the app from a custom origin, add it to ALLOWED_ORIGINS.

“This backend has no public https PUBLIC_BASE”

PUBLIC_BASE is empty or not https://. Set it to your public HTTPS URL and restart the backend.

“Could not find or create the Zendesk calling application” or “Could not set up a SIP endpoint”

Vobiz refused the request; the backend log has the HTTP status. Check that the account is active and the Auth Token is current, then sign in again.

“No numbers found on this account”

The account has no active, voice-enabled number. Buy or activate one in the Console, then sign in again.

The badge stays OFFLINE, or says “Registration failed”

The browser cannot register with Vobiz. Allow WebSocket traffic to registrar.vobiz.ai:5063. In SIP direct mode, check the username and password in Console → Endpoints.

Calls fail at once and nothing appears in the backend log

Vobiz cannot reach /answer. Run the curl check from Set up from outside your network. If your tunnel hostname changed, update PUBLIC_BASE and Backend URL, restart the backend and sign in again.

The customer's phone never rings

The backend log shows bleg=(none …): the destination is unreachable, or the caller ID is not a number on this Vobiz account. Check the number format (+91XXXXXXXXXX) and your caller ID. The CDR shows how the call ended.

The call connects but nobody hears anything

The microphone is blocked, or the network blocks WebRTC media. Allow the microphone for Zendesk, and try another network - STUN (stun.l.google.com:19302) must be reachable.

Inbound calls never ring the panel

The number is on another application, or no agent is signed in. Click Enable inbound calls with that number selected, and keep the panel open and READY.

Clicking a phone number in Zendesk does nothing

Zendesk’s click-to-dial event needs Talk Partner Edition. Use Call requester in the ticket sidebar, or type the number in the panel.

Outbound calls create a new ticket instead of using the open one

No ticket was open when the call started. Open the ticket first, then call - for example with Call requester. Inbound calls always create a new ticket.

A recording link says it is invalid, expired, or that the backend restarted

“Invalid or has expired”: the link is older than its time limit, or SIGNING_SECRET changed - set a fixed secret. “The calling backend restarted since this link was made”: sign in to the panel with that Vobiz account, then open the link again.

An agent keeps getting signed out

The same Zendesk agent is signed in to the panel in another tab or browser. Each new sign-in ends that agent’s older one. Use one panel at a time.

Limitations

Sign in again after the backend restarts. Auth Tokens and sessions live in memory only. Sessions also expire after 12 hours. The panel shows SIGNED OUT when this happens.
Run one backend instance. State is not shared between instances.
One panel per agent at a time. Each Zendesk agent has one SIP endpoint; signing in again elsewhere signs the older panel out.
The agent is identified by the panel. The backend binds each session to the Zendesk user ID the panel reports, but does not verify it with Zendesk. Anyone with the Vobiz Auth ID and Auth Token can sign in as any agent.
Inbound rings everyone on the account. All signed-in agents of the Vobiz account ring together. There is no queue, routing or per-number assignment.
No hold, mute, transfer or conference.
Browser only. Calls cannot be sent to an agent’s mobile or desk phone.
Every call is recorded. Recording cannot be turned off from the app, and stops after one hour. Calls are limited to four hours.
SIP direct cannot use recordings, the caller-ID dropdown or Enable inbound calls, and its ticket notes have no recording link.
Click-to-dial on any phone number needs Talk Partner Edition. On other plans, use Call requester or the panel.
The panel’s recordings list forgets on restart. It lists calls this backend handled since it last started. Ticket recording links keep working.
Private app only. It is not listed on the Zendesk Marketplace.

Next steps

Source code

The Zendesk app and the backend, with the full README.

Endpoints

How Vobiz SIP endpoints work.

Dial XML

The call instructions the backend returns.

Freshdesk

The same softphone for Freshdesk.

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

CRM & Helpdesk

Migrations

Zendesk integration

What you get

Click-to-call

Inbound in the browser

Screen pop

Call logging

Recordings

Caller-ID choice

How it works

Prerequisites

Set up

Vobiz account (recommended)

SIP direct

Enable inbound calls

Using it

Outbound calls

Inbound calls

Call logging

Recordings

Configuration

Zendesk app settings

Backend environment variables

Deploy to production

Security and privacy

Troubleshooting

Limitations

Next steps

Source code

Endpoints

Dial XML

Freshdesk

​What you get

Click-to-call

Inbound in the browser

Screen pop

Call logging

Recordings

Caller-ID choice

​How it works

​Prerequisites

​Set up

​Sign in

​Vobiz account (recommended)

​SIP direct

​Enable inbound calls

​Using it

​Outbound calls

​Inbound calls

​Call logging

​Recordings

​Configuration

​Zendesk app settings

​Backend environment variables

​Deploy to production

​Security and privacy

​Troubleshooting

​Limitations

​Next steps

Source code

Endpoints

Dial XML

Freshdesk

What you get

How it works

Prerequisites

Set up

Sign in

Vobiz account (recommended)

SIP direct

Enable inbound calls

Using it

Outbound calls

Inbound calls

Call logging

Recordings

Configuration

Zendesk app settings

Backend environment variables

Deploy to production

Security and privacy

Troubleshooting

Limitations

Next steps