Vobiz Zoho PhoneBridge integration

Vobiz runs as a Zoho PhoneBridge telephony provider. A Zoho user clicks a phone number, the call is placed on Vobiz from their browser, and the call log lands on the Zoho record with its recording.

Early access. Vobiz hosts this integration for you on request: email support@vobiz.ai and we set it up with your Zoho administrator. Prefer to run it yourself? Self-host the open-source backend, vobiz-ai/Vobiz-Zoho-Calling. One-click install from Zoho Marketplace comes once Zoho approves the Vobiz Telephony listing.

There is no widget to install in Zoho. Zoho draws the whole calling interface: its own call bar and its own call pop-ups. Each agent keeps one Vobiz softphone tab open in the browser, and that tab carries the audio.

What you get

Feature	What happens
Click-to-dial	A Zoho user clicks a number in Zoho and the call is placed from their browser.
Live call states	Zoho’s call bar shows the call as ringing, answered and ended.
Call logging	Outbound calls (clicked in Zoho or typed into the softphone) and inbound calls are logged in Zoho with start time, duration and direction, against the Zoho user who handled them.
Recordings	Outbound calls are recorded by default and inbound recording is optional. The call log links to the recording.
Inbound ringing	Calls to your Vobiz numbers ring every signed-in agent of that account, with Accept / Decline and voicemail after 20 seconds.
Caller ID choice	Agents pick a caller ID from their Vobiz account’s numbers.
Many agents	Each Zoho user is mapped to an agent, with click-to-dial registered per user.
Two sign-in modes	Vobiz account (Auth ID + Auth Token, set up automatically) or SIP direct (an endpoint you already have).
Failed dials reported	When a click cannot become a call, Zoho is told why.

The backend uses Zoho’s PhoneBridge API only, with no code specific to one Zoho app, so calls appear wherever Zoho shows PhoneBridge telephony in your organization.

How it works

Sequence diagram of a Zoho click-to-dial call across four lanes: Zoho, the Vobiz backend, the agent's browser and the customer. Zoho posts tonumber to the backend, the backend hands the number to the agent's softphone over the call-events stream, the browser sends the SIP INVITE and Vobiz dials the customer, audio flows both ways, and the backend reports callnotify ringing, answered and ended back to Zoho.

Zoho calls your backend when a user clicks a number.
The backend passes the number to that agent’s open softphone tab.
The browser places the call to Vobiz, and Vobiz asks your backend’s /answer URL what to do. The backend dials the customer with the agent’s caller ID.
Your backend reports ringing, answered and ended back to Zoho. The final state carries the duration and the recording link.
Inbound calls reach the same /answer URL. The backend rings the agents signed in to the Vobiz account that owns the dialled number.
Zoho is always reached in your organization’s own Zoho datacentre, worked out when you connect.

Ways to get started

	Hosted by Vobiz (recommended)	Self-hosted
Who runs the backend	Vobiz	You, on your own server
How to start	Email support@vobiz.ai	Follow Self-host it
What you need	A Vobiz account, a Zoho administrator, and your agents’ browsers	The same, plus a server with a public HTTPS URL
Updates and uptime	Handled by Vobiz	Handled by you

One-click install is coming. Once Zoho approves the Vobiz Telephony listing in Zoho Marketplace, you will be able to install it from Zoho’s own Marketplace page and connect to the Vobiz-hosted backend with no setup call. Until then, use one of the two options above.

Hosted by Vobiz: how setup works

Request access

Email support@vobiz.ai with your Vobiz Auth ID, your Zoho organization’s datacentre (for example India or US), and the agents who will take calls: each one’s name and Zoho login email.

Connect your Zoho organization

On a short setup call, your Zoho administrator installs Vobiz Telephony from Marketplace → Telephony and approves the connection to Vobiz. Vobiz then activates click-to-dial for each of your agents.

Agents sign in

Each agent receives a personal sign-in link. They open it, sign in with your Vobiz account (Auth ID and Auth Token) or SIP direct, allow the microphone, and keep the tab open. A green dot and Ready mean they can make and take calls.

Everything after that, from making calls to logging, recordings and inbound calls, works as described in Sign-in modes and Using it.

Prerequisites

Vobiz account

The Auth ID and Auth Token from Vobiz Console → API credentials, at least one active voice-enabled number, and balance. Every call is billed.

Zoho organization

A Zoho CRM edition that supports telephony (PhoneBridge) integrations, and an administrator who can install a provider from Marketplace → Telephony.

Your server (self-hosted only)

Node.js 20.12 or later, a public HTTPS URL such as https://calling.example.com, and a persistent disk. There are no npm dependencies.

Agents

A current Chrome, Edge or Firefox, with microphone access allowed for your backend’s URL.

To self-host, you also need the Vobiz Telephony listing enabled for your Zoho organization and the PhoneBridge OAuth client (client ID and client secret) for it. Vobiz provides both during early access.

A client you register yourself at the Zoho API console does not work. Zoho grants PhoneBridge scopes only to the provider’s own client. The redirect URI you use must be registered on that client exactly, character for character.

Self-host it

These steps are for running the backend on your own server. If Vobiz hosts it for you, skip to Sign-in modes.

Request access

Email support@vobiz.ai with your Vobiz Auth ID, your Zoho organization’s datacentre (for example India or US) and your backend’s redirect URI, https://calling.example.com/oauth/zoho/callback. You receive the PhoneBridge client ID and secret.

Get the code and configure it

git clone https://github.com/vobiz-ai/Vobiz-Zoho-Calling.git
cd Vobiz-Zoho-Calling/backend
cp .env.example .env
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"     # APP_SECRET
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"  # TOKEN_ENCRYPTION_KEY
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"     # ADMIN_TOKEN

Fill in PUBLIC_BASE_URL, APP_SECRET, TOKEN_ENCRYPTION_KEY, ADMIN_TOKEN, DATA_DIR, ZOHO_PB_CLIENT_ID, ZOHO_PB_CLIENT_SECRET and ZOHO_PB_REDIRECT_URI. No Vobiz credential goes in .env. See Configuration.

List your agents

Create agents.json (in DATA_DIR, or copy agents.example.json). One entry per agent, keyed by an agent ID you choose:

{
  "priya": { "displayName": "Priya", "email": "priya@example.com" },
  "arjun": { "displayName": "Arjun", "zohoUser": "600001" }
}

Each agent needs email (matched to the Zoho user’s email) or zohoUser (the Zoho PhoneBridge user ID). No SIP login, password or number.

Run it on a public HTTPS URL

npm start                                # listens on PORT, default 8092
curl https://calling.example.com/health  # → ok

Put it behind your load balancer or reverse proxy so PUBLIC_BASE_URL reaches it. Run exactly one instance.

Install Vobiz Telephony in Zoho

As a Zoho administrator, open Marketplace → Telephony, choose Vobiz Telephony and install it for your organization.

Connect your Zoho organization

Open https://calling.example.com/admin/login and enter your ADMIN_TOKEN. In the same browser, open https://calling.example.com/zoho/phonebridge/connect and approve the request in Zoho. The response shows your orgId, for example org_1a2b3c4d5e6f7a8b.

curl -X POST https://calling.example.com/zoho/phonebridge/register \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"orgId":"org_1a2b3c4d5e6f7a8b"}'

This activates Vobiz as your organization’s phone system, pairs your Zoho users with the agents in agents.json, and registers click-to-dial for each pair. The response lists any unmatchedAgents and unmatchedZohoUsers. Run it again whenever you change agents.json.

Send agents their sign-in links

curl https://calling.example.com/admin/agent-links -H "Authorization: Bearer $ADMIN_TOKEN"

Send each agent their own link privately. It works like a password.

Agents sign in

Each agent opens their link, signs in to Vobiz, allows the microphone, and keeps the tab open. A green dot and Ready mean they can make and take calls.

Each Zoho organization you connect is kept separately. A Zoho organization is not tied to one Vobiz account: each call uses the Vobiz account or SIP endpoint that agent signed in with. Opening the sign-in link starts a 12-hour agent session in that browser. The softphone then shows Sign in to Vobiz with two tabs.

Vobiz account (recommended)

The agent enters the Auth ID (MA_XXXXXXXX) and Auth Token and clicks Sign in. The backend then:

Checks the pair with Vobiz.
Finds or creates one application in that account named Vobiz-Zoho-PhoneBridge, with answer URL https://calling.example.com/answer and hangup URL https://calling.example.com/hangup. It never changes any other application.
Finds or creates one SIP endpoint for the agent (alias zoho-<agentId>), sets a fresh random SIP password, and attaches it to that application. If the agent already has a softphone tab open, the current password is kept instead (see More than one tab).
Starts the softphone with that SIP login and asks for the microphone straight away. If it is blocked, the softphone says Microphone blocked — calls will have no audio.

The Caller ID dropdown lists the account’s active, voice-enabled numbers. The backend refuses a caller ID that is not on the account.

Your Auth Token never leaves the server and is never stored on disk. The SIP password is never written to disk either: the backend keeps it in memory while the agent’s session lasts, so a second tab can join it.

Enable inbound calls

Choose a number in the Caller ID dropdown and click Enable inbound calls on this number. This attaches the number to the Vobiz-Zoho-PhoneBridge application, so calls to it ring your agents.

This moves the number off the application that answered it before. The softphone asks first and names that application (by name, or by ID if it has none). Numbers already routed to this integration show · inbound on.

SIP direct

For an endpoint you already have. The agent enters the endpoint’s SIP username, SIP password and a Caller ID in E.164 format (+91XXXXXXXXXX). The SIP password stays in the browser. Before using it, point the endpoint and the number at an application whose answer URL is your backend’s /answer:

Create an application with answer URL https://calling.example.com/answer (POST) and hangup URL https://calling.example.com/hangup (POST). API: Create an application.
Attach the endpoint to that application. API: Update an endpoint with application.
For inbound calls, attach the number to the same application. API: Attach a number.

SIP direct has no caller ID dropdown, no Enable inbound calls, no recording links in Zoho, no billed duration from Vobiz and no webhook signature checks. Inbound calls to the caller ID number ring that agent.

Using it

Outbound calls

Click a phone number in Zoho. The agent’s softphone dials it and Zoho’s call bar follows the call. If the agent’s softphone tab is closed, or they have not signed in to Vobiz there, no call is placed and Zoho is told the call failed with AGENT_OFFLINE. Agents can also type a number in the softphone and click Call. Those calls are logged in Zoho too, against the agent’s Zoho user.

More than one tab

An agent can open the softphone in a second tab. Signing in there while another tab is open keeps the same SIP password, so the first tab stays connected. Zoho click-to-dial goes to one tab only, the one opened most recently; the other tabs show where the call went.

Inbound calls

A call to a number that rings this integration rings every agent signed in to the Vobiz account that owns it. The softphone shows Accept and Decline; Enter accepts and Escape declines. If nobody answers in 20 seconds, the caller can leave a voicemail of up to 2 minutes. If no agent of that account is signed in, the caller hears that no one is available.

Call logging and recordings

Each call is logged in Zoho with its direction, numbers, start time, duration (billed duration from Vobiz when available) and Zoho user. For outbound calls that is the user who clicked, or the agent’s own Zoho user for a typed number. For inbound calls it is the agent who answered. Zoho’s ringing pop-up appears for the first ringing agent mapped to a connected Zoho organization, and an inbound call nobody answers is logged as missed against that agent. An unanswered call is logged with duration 0, or as missed with ZOHO_PB_SEND_MISSED_STATE=true. The log is written when the recording is ready, or 90 seconds after the call ends if none arrives. Outbound calls are recorded unless OUTBOUND_RECORD=false. Inbound calls are recorded with INBOUND_RECORD=true, and voicemail is always recorded. The call log links to a signed recording URL on your backend that expires after 30 days by default. It carries no Vobiz credentials and cannot be altered to fetch another recording.

Configuration

Variable	Required	Default	Meaning
`PUBLIC_BASE_URL`	Yes	none	Public HTTPS URL of the backend, no trailing slash.
`PORT`	No	`8092`	Port the backend listens on.
`APP_SECRET`	Yes	none	At least 32 random characters. Signs sessions, links and URLs.
`TOKEN_ENCRYPTION_KEY`	Yes	none	32 bytes, hex or base64. Encrypts stored Zoho tokens. Losing it means reconnecting every organization.
`ADMIN_TOKEN`	Yes	none	Protects the admin routes.
`ZOHO_PB_CLIENT_ID`	Yes	none	PhoneBridge OAuth client ID.
`ZOHO_PB_CLIENT_SECRET`	Yes	none	PhoneBridge OAuth client secret.
`ZOHO_PB_REDIRECT_URI`	Yes	none	`<PUBLIC_BASE_URL>/oauth/zoho/callback`, registered on the client exactly.
`DATA_DIR`	Recommended	`backend/` folder	Where connected organizations, endpoint IDs and `agents.json` are kept. Use a persistent disk.
`AGENTS_FILE`	No	`DATA_DIR/agents.json`	Explicit path to `agents.json`.
`ALLOWED_ORIGINS`	No	empty	Browser origins allowed cross-origin. The bundled softphone needs none.
`REQUIRE_VOBIZ_SIGNATURE`	No	off	`true` refuses Vobiz webhooks whose signature does not verify.
`OUTBOUND_RECORD`	No	on	`false` stops recording outbound calls.
`INBOUND_RECORD`	No	off	`true` records inbound calls.
`ZOHO_PB_SEND_MISSED_STATE`	No	off	`true` logs unanswered calls as missed.
`ZOHO_PB_RECORDING_GRACE_MS`	No	`90000`	How long to wait for a recording before logging the call without one.
`RECORDING_URL_TTL_DAYS`	No	`30`	Lifetime of recording links in Zoho.
`RECORDING_URL_SECRET`	No	derived from `APP_SECRET`	Separate key for recording links.
`ZOHO_PB_DEBUG`	No	off	Enables an admin-only diagnostics route. Leave off.

Running in production

Serve the backend over HTTPS only, and run exactly one instance.
To share a host with other services, put the backend under a path prefix such as https://integrations.example.com/zoho, have your proxy strip /zoho, and set PUBLIC_BASE_URL to the full prefixed URL. Sign-in cookies are then limited to /zoho. If your registered redirect URI is <host>/oauth/zoho/callback at the root, route that one path to the backend unchanged.
Keep DATA_DIR on a persistent disk, and keep secrets in your host’s secret manager.
Set REQUIRE_VOBIZ_SIGNATURE=true once your logs show signature ok on real calls.
Rate-limit /zoho/phonebridge/clicktodial, /agent-session and /agent/vobiz-session at your proxy.
GET /zoho/phonebridge/status (admin) shows connected organizations, signed-in accounts and calls in progress. POST /zoho/phonebridge/disconnect with {"orgId":"…"} removes an organization and revokes its Zoho token.

Troubleshooting

Zoho shows an invalid redirect URI error

ZOHO_PB_REDIRECT_URI must be <PUBLIC_BASE_URL>/oauth/zoho/callback and must be registered on the PhoneBridge client exactly. Ask Vobiz support to check the registered value.

Zoho shows an invalid client error when connecting

The client is registered in one Zoho datacentre only. Open /zoho/phonebridge/connect?dc=in, replacing in with your datacentre (us, eu, au and so on).

Zoho redirected to a different host after approval

Open /zoho/phonebridge/complete on your backend and paste the full URL Zoho redirected to, within a minute. Then fix the redirect URI.

Vobiz Telephony is not installed for this Zoho organization. Install it from Marketplace → Telephony and register again.

Use the zohoUsers list in the response to correct email or zohoUser in agents.json, then register again.

Clicking a number fails with AGENT_OFFLINE

The agent’s softphone tab is closed, they have not signed in to Vobiz there, or the backend restarted. Open the softphone, sign in, wait for Ready, and keep the tab open.

Clicking a number fails with NO_CALLER_ID

The Vobiz account has no active, voice-enabled number. Add one and sign in again.

The softphone says Not signed in

The 12-hour agent session expired. Open your sign-in link again, or ask your admin for a new one.

Vobiz did not accept those credentials

Copy the Auth ID and Auth Token again from Vobiz Console → API credentials.

Registration failed in the softphone

The SIP password changed: the agent signed in again with no other tab open, or the backend restarted. Reload the tab and sign in again. A second tab opened while one is still open does not change the password.

Clicking a number dials in the wrong tab

Click-to-dial goes to the agent’s most recently opened softphone tab. Use that tab, or close it so clicks go to the other one.

The softphone says Microphone blocked

The browser refused the microphone at sign-in. Allow it for your backend’s URL (the icon left of the address bar) and reload.

Inbound callers hear that no one is available

No agent of the account that owns the number is signed in, or the backend restarted. Have an agent sign in, and check the number shows · inbound on.

No audio, or the call drops as it connects

Allow the microphone for your backend’s URL permanently, so the browser does not ask during a call.

A recording link returns 503

The backend restarted and no agent of that Vobiz account has signed in since. Have any agent of the account sign in.

Operating notes

Early access. The Vobiz-hosted service is set up on request. One-click install from Zoho Marketplace comes once Zoho approves the listing.
Run one backend instance. Calls in progress, agent sessions and Auth Tokens are held in memory.
Sign in again after a restart. After the backend restarts, every agent reloads the softphone and signs in to Vobiz again. A call in progress during a restart is not logged.
Sign in again after a page reload, and keep a softphone tab open. With several tabs open, Zoho click-to-dial reaches the most recently opened one.
Inbound rings everyone on the account. Zoho’s ringing pop-up appears for one agent, and the call log goes to the agent who answered.
Agent sessions last 12 hours. A backend restart ends all of them together.

Next steps

Source code and full README: vobiz-ai/Vobiz-Zoho-Calling
Zoho’s PhoneBridge V3 reference
The same calling in other CRMs: Zendesk, HubSpot, Pipedrive, Freshdesk, ServiceNow
Reference: <Dial>, SIP endpoints, CDRs
Help: Contact support

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

CRM & Helpdesk

Workflow Automation

Migrations

Vobiz Zoho PhoneBridge integration

What you get

How it works

Ways to get started

Hosted by Vobiz: how setup works

Prerequisites

Vobiz account

Zoho organization

Your server (self-hosted only)

Agents

Self-host it

Vobiz account (recommended)

Enable inbound calls

SIP direct

Using it

Outbound calls

More than one tab

Inbound calls

Call logging and recordings

Configuration

Running in production

Troubleshooting

Operating notes

Next steps

​What you get

​How it works

​Ways to get started

​Hosted by Vobiz: how setup works

​Prerequisites

Vobiz account

Zoho organization

Your server (self-hosted only)

Agents

​Self-host it

​Sign-in modes

​Vobiz account (recommended)

​Enable inbound calls

​SIP direct

​Using it

​Outbound calls

​More than one tab

​Inbound calls

​Call logging and recordings

​Configuration

​Running in production

​Troubleshooting

​Operating notes

​Next steps

What you get

How it works

Ways to get started

Hosted by Vobiz: how setup works

Prerequisites

Self-host it

Sign-in modes

Vobiz account (recommended)

Enable inbound calls

SIP direct

Using it

Outbound calls

More than one tab

Inbound calls

Call logging and recordings

Configuration

Running in production

Troubleshooting

Operating notes

Next steps