Freshdesk integration

Vobiz Calling for Freshdesk adds a phone to Freshdesk. Your agents make and receive real phone calls in the browser, through your Vobiz account, from a panel in the Freshdesk sidebar. They don’t need a desk phone or a desktop app, and they don’t have to leave the helpdesk. There are two parts, and you run both. The panel is a Freshdesk custom app that you upload to your own Freshdesk account. The calling backend is a small Node service that you host. Both are in the vobiz-ai/Vobiz-Freshdesk-Calling repository.

This replaces your current Freshdesk telephony. Freshdesk runs only one CTI app at a time, and Freshcaller must be turned off.

What you get

Click-to-call

An agent clicks any phone number in Freshdesk and the panel opens and dials it. Agents can also type a number.

Inbound calls in the browser

Calls to your Vobiz number ring the panel, and the panel picks them up.

Caller ID choice

Agents choose which of your Vobiz numbers their calls come from.

Call recording

Turn it on for every call, then play recent recordings in the panel.

Two ways to sign in

One backend, any account

One backend serves any number of Vobiz accounts. You don’t put any account details in its configuration.

The app does not write anything into Freshdesk. It does not create tickets, add call notes or look up contacts. See Limitations.

How it works

  Agent clicks a number in Freshdesk
              │
              ▼
   ┌─────────────────────┐   SIP over WebSocket (audio)   ┌─────────┐
   │  Panel (Freshdesk)  │ ◀────────────────────────────▶ │  Vobiz  │ ◀──▶ phone network
   └──────────┬──────────┘                                └────┬────┘
              │ HTTPS: sign-in, caller ID,                     │ HTTPS webhooks:
              │ inbound setup, recordings                      │ "what do I do with this call?"
              ▼                                                ▼
   ┌───────────────────────────────────────────────────────────────┐
   │          Your calling backend (backend/, public HTTPS)          │
   └───────────────────────────────────────────────────────────────┘

The panel is a softphone. It registers with Vobiz over SIP-over-WebSocket, and the call audio runs in the browser tab.
When an agent signs in, the backend checks the credentials with Vobiz. In that account it then sets up an application that points at the backend and a SIP endpoint for the agent.
Outbound: the panel calls Vobiz, and Vobiz asks the backend’s /answer URL what to do. By default the backend places the agent in a private conference room, then dials the customer into that room from the caller ID the agent chose.
Inbound: a call to your number reaches /answer. The backend dials every agent who is signed in to that Vobiz account, and the panel answers.
Recordings: the backend lists them and gives the panel a playback link that is signed and short-lived. Your Auth Token never reaches the browser.

Prerequisites

You need	Details
A Vobiz account	Your Auth ID and Auth Token from the Vobiz Console dashboard, under API credentials. The Auth Token is not your login password. You also need at least one active, voice-enabled phone number and a positive balance.
Freshdesk	The Growth, Pro or Enterprise plan (these plans support CTI apps), an admin login, and Freshcaller turned off.
A public HTTPS URL	Vobiz must reach the backend over `https://` with a valid certificate, for example `https://calling.example.com`. You can use a server behind a reverse proxy, or a tunnel while you test.
Node.js	Node 20 or later to run the backend. Node 24.11.1 with the Freshworks CLI (`fdk`) 10.1.9 to run the app locally and to pack it.
A browser and a microphone	A current desktop browser with WebRTC, a microphone, and a network that allows WebSocket connections to `wss://registrar.vobiz.ai:5063`.

Set it up

Clone the repository and install

git clone https://github.com/vobiz-ai/Vobiz-Freshdesk-Calling.git
cd Vobiz-Freshdesk-Calling
npm install

Configure the backend

Copy the example file, then set two values:

cp backend/.env.example backend/.env
openssl rand -hex 32        # paste the output as SIGNING_SECRET

PUBLIC_BASE=https://calling.example.com
SIGNING_SECRET=<the 64 hex characters from openssl>

backend/.env holds deployment settings only. It never contains a Vobiz Auth ID, Auth Token, phone number or endpoint. See the configuration reference for every setting.

Start the backend

npm run backend             # listens on http://127.0.0.1:8093

The startup banner shows the answer URL, the outbound mode, and whether recording is on.

Make the backend public

Point https://calling.example.com at 127.0.0.1:8093 with a reverse proxy, or use a tunnel while you test. Then check it from outside:

curl https://calling.example.com/health      # {"ok":true}

Pack the Freshdesk app

nvm install 24.11.1 && nvm use 24.11.1
npm install -g https://cdn.freshdev.io/fdk/latest-v24.tgz
npm run pack                # writes dist/vobiz-freshdesk-calling.zip

Use npm run pack, not a bare fdk pack. A bare fdk pack stops on lint errors in the bundled SIP library.

Upload it as a custom app

In Freshdesk, go to Admin → Apps and click Go to Developer Portal.
Click Create New App, choose Custom App, and select your Freshdesk account.
Upload the zip from dist/, and fill in a name (for example Vobiz Calling), a description and your support email.
Click Save and Publish, then Promote to Live.

Freshworks does not review custom apps. The app is usually available within about thirty minutes.

Install it and fill in the settings

Go to Admin → Apps → Manage Apps, filter to Custom, and click Install on the app.

Setting	Value
Calling backend URL	`https://calling.example.com`, with no trailing slash
SIP registrar URL (optional)	Leave blank. It defaults to `wss://registrar.vobiz.ai:5063/`

There is nothing to set per agent: each agent’s own Freshdesk login decides which SIP line they get. To change these later, go to Admin → Apps → Manage Apps → Custom → Vobiz Calling → Settings → Configure.

Open any agent page and click the Vobiz icon at the bottom left. If you don’t see it, do a hard refresh (Ctrl + F5). On the Vobiz account tab, enter your Auth ID and Auth Token and click Log in. When the badge turns Ready, you can make a call.

Try it before you upload. Run npm run dev (this is fdk run on http://localhost:10001) while the backend is running. The first time, enter your Freshdesk domain at http://localhost:10001/system_settings. Then set the installation parameters at http://localhost:10001/custom_configs. Use http://localhost:8093 as the backend URL, because the panel accepts plain http only for localhost. Finally, open any Freshdesk agent page with ?dev=true added to the URL. PUBLIC_BASE must still be a public HTTPS URL, because Vobiz needs to reach it.

Signing in

The panel has two tabs. Agents sign in each time they open the panel. The panel keeps no credentials, so reloading the Freshdesk tab also means signing in again.

Vobiz account (recommended)

Enter your Auth ID (MA_XXXXXXXX) and Auth Token, then click Log in. The backend checks them with Vobiz by listing the account’s phone numbers. The first time anyone signs in, the backend creates these in your Vobiz account:

What	Details
One application	Named `Freshdesk-Calling`. You can change the name with `VOBIZ_APP_NAME`. Its answer URL and hangup URL are both `https://calling.example.com/answer` (method `POST`). If an application with that answer URL already exists, the backend reuses it. It never changes an application that it did not create.
One SIP endpoint per Freshdesk agent	Alias `Freshdesk-fd<Freshdesk user ID>`, with a username that starts with `fd`. The endpoint is attached to the application above. The backend reuses this endpoint on later sign-ins.

The panel reads the logged-in Freshdesk agent and signs in as fd<their user ID>, so colleagues who share one Vobiz account each get their own line and never sign each other out. Each sign-in gives the endpoint a new random SIP password. Only that browser session receives it. Signing in again as the same Freshdesk agent (for example in a second tab) ends the previous session. Sign out. Click Sign out under the sign-in form. The panel ends any call, unregisters from Vobiz so inbound calls stop ringing that browser, and returns to Signed out. When the last agent of a Vobiz account signs out, or their session expires, the backend drops that account’s Auth Token from memory, after any outbound call still in progress has ended. Choose a caller ID. The Calling from list shows every active, voice-enabled number on the account. Your outbound calls come from the number you pick. The backend accepts only numbers on that account.

Enabling inbound calls

Click Enable inbound calls once for each number. This attaches the selected number to the Freshdesk-Calling application, so calls to it ring the panel.

Attaching the number moves it off the application it is on now. Anything that number did before, such as an IVR or another integration, stops. Before you click, the panel names that application, with its ID: “+91XXXXXXXXXX is attached to application “My IVR” (…) now; enabling moves it to this panel’s.” (only the ID if the name can’t be read), or says the number already rings this panel. Nothing moves until you click the button.

SIP direct

Use this tab to sign in with a Vobiz SIP endpoint you already have. Enter its SIP username (letters and digits, as the Console shows it), its SIP password, and a Caller ID in E.164 format (+91XXXXXXXXXX) from the same account. Then click Connect. The backend has no account credentials in this mode, so it cannot set anything up for you. Before you sign in, attach the endpoint, and the number if you want inbound calls, to an application whose answer URL is your backend’s /answer:

Create the application

In the Console, go to Voice → Applications → + Create New Application. Set the Answer URL to https://calling.example.com/answer with method POST. With the API, use Create an application with answer_url and answer_method: "POST".

Attach the endpoint

In Voice → Endpoints, edit the endpoint and set its Application. With the API, use Update an endpoint with {"app_id": "<app_id>"}.

Attach the number (for inbound)

Open the application, go to the Phone Numbers tab, and click + Attach Number. With the API, use Attach a number: POST /Account/{auth_id}/numbers/%2B<digits>/application with {"application_id": "<app_id>"}.

SIP direct does not include the caller-ID list, Enable inbound calls or the recordings list. Outbound calls always use a plain dial instead of the conference bridge. The registrar checks the password, and Vobiz refuses a caller ID that the account doesn’t own.

Using it

Making a call. Type a number in E.164 format and click Call, or click any phone number in Freshdesk. The Call button works only when you are signed in and the panel is registered. If either is missing, the hint under the button says which. Your browser asks for microphone access on the first call. Click Hang up to end the call. With the default conference bridge, your side joins a private room first and the customer is then dialled into it. The panel shows Ringing while their phone rings (you hear silence) and On a call once they answer. If the customer doesn’t answer, the backend ends your side of the call. With SIP direct or OUTBOUND_MODE=dial, the panel can’t see the customer’s leg, so it shows On a call as soon as your side connects. Taking a call. Keep a Freshdesk tab open with the panel signed in and showing Ready. When a call reaches your number, every agent signed in to that Vobiz account rings, and the first panel to pick up answers automatically. If nobody is signed in, the caller hears “Sorry, nobody is available to take your call.” Call logging. Nothing is written to Freshdesk. Vobiz keeps a call log for every call in your account, under Voice → Call Logs in the Console. Recordings. Set RECORD_CALLS=1 on the backend to record both sides of every call, inbound and outbound. Recording is off by default. Tell the people you call that you record. The panel’s Call recordings list shows the 15 most recent recordings on the Vobiz account. Click ▶ Play to listen. Each playback link stops working after 5 minutes. The recordings stay in your Vobiz account.

Configuration reference

The backend reads backend/.env when it starts. A variable that is already set in the environment takes priority over the file.

Variable	Required	Default	Meaning
`PUBLIC_BASE`	Yes	none	The public `https://` URL Vobiz uses to reach the backend, with no trailing slash. The answer URL is `PUBLIC_BASE/answer`.
`SIGNING_SECRET`	Recommended	A random value at each start	The key that signs recording playback links. If you don’t set it, links stop working whenever the backend restarts.
`PORT`	No	`8093`	The port to listen on.
`HOST`	No	`127.0.0.1`	The address to listen on. Set `0.0.0.0` in a container, or when the proxy runs on another host.
`DATA_DIR`	No	`backend/data`	Where the endpoint map (`endpoints.json`) is kept.
`OUTBOUND_MODE`	No	`conference`	`conference`: the agent waits in a private room and the customer is dialled into it. `dial`: a plain dial to the customer. SIP direct always uses `dial`.
`RECORD_CALLS`	No	off	`1`, `true` or `yes` records every call in both directions.
`INBOUND_RING_SECONDS`	No	`30`	How long an inbound call rings the agents, and in `dial` mode how long the customer’s phone rings. The value is held between 5 and 120.
`SESSION_TTL_HOURS`	No	`12`	How long a panel sign-in lasts.
`RECORDING_URL_TTL_SECONDS`	No	`300`	How long a recording playback link works.
`VOBIZ_WEBHOOK_SIGNATURE`	No	`log`	`off`, `log` or `require`. Checks the Vobiz signature on each webhook. `log` records failures and lets the request through. `require` rejects it.
`VOBIZ_APP_NAME`	No	`Freshdesk-Calling`	The name of the application that sign-in creates in each account.
`ALLOWED_ORIGINS`	No	none	Extra browser origins, separated by commas. You can write wildcards as `https://*.example.com`. Freshdesk, Freshworks and `localhost` origins are already allowed.
`VOBIZ_API_BASE`	No	`https://api.vobiz.ai`	The Vobiz API host. Change it only if Vobiz support asks you to.

Deploying to production

Serve over HTTPS on a stable hostname with a valid certificate.
Run exactly one backend instance. Sessions, signed-in accounts and active calls are held in memory.
Keep DATA_DIR on persistent storage, so agents get the same endpoint after a restart.
Set SIGNING_SECRET to a fixed random value.
Set VOBIZ_WEBHOOK_SIGNATURE=require once the log shows that signatures verify. Leave it at log if your agents only use SIP direct.
Expect agents to sign in again after a restart. Until an agent from an account signs in again, calls for that account can’t be routed.
Ship updates by running npm run pack again and uploading the new zip to the same custom app in the Developer Portal.

Security and privacy

Your Auth Token never leaves the backend and is never stored on disk. The panel sends it once, at sign-in. The backend keeps it in memory only while an agent of that account is signed in (or a call they placed is still up), drops it at sign-out or session expiry, and never logs it or returns it to the browser.
The panel stores nothing. It uses no cookies or browser storage. Everything the browser asks for, including the SIP password, requires the session token from sign-in.
The browser receives a session token, the account’s phone numbers and the ID and name of the application each number is attached to, its own endpoint’s SIP username and password, and signed playback links.
On disk, the backend keeps only a map of endpoint IDs and usernames, with file mode 0600.
Recordings are reached only through signed links that expire, made for one account. The backend fetches the audio itself, only from Vobiz media hosts.
CORS allows only Freshdesk and Freshworks origins, localhost, and anything you add in ALLOWED_ORIGINS.
Webhook signatures (X-Vobiz-Signature-V3) are checked with the Auth Token of the account the call belongs to.

Troubleshooting

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

The Calling backend URL is empty or has no https://. Fix it under Manage Apps → Custom → Vobiz Calling → Settings.

“Cannot reach the calling backend”

The backend is down, the URL is wrong, or the backend refused the page’s origin. Check curl https://calling.example.com/health. If the backend log says origin … is not allowed, add that origin to ALLOWED_ORIGINS.

“Vobiz did not accept that Auth ID and Auth Token”

Copy both again from Console → API credentials. The Auth Token is not your Console password.

“This backend has no PUBLIC_BASE” or “Could not set up this agent's phone line”

Set PUBLIC_BASE to an https:// URL and restart. If it is already set, Vobiz refused to create the application or endpoint, and the backend log shows Vobiz’s status code.

The account has no phone numbers, and Call stays disabled

The panel says “this account has no phone numbers yet”. Buy or activate a voice-enabled number, then sign in again.

“Registration failed”

With a Vobiz account, sign in again, because each sign-in sets a new password. With SIP direct, check the username and password. Also make sure your network allows wss://registrar.vobiz.ai:5063.

“Could not identify the signed-in Freshdesk agent”

Freshdesk did not return the logged-in agent to the app. Reload the Freshdesk page.

The panel signs out after you open it in another tab

Each Freshdesk agent has one session, and a new sign-in replaces the previous one. Use the panel in one tab at a time.

Outbound calls fail straight away

If the backend log says “which no signed-in agent holds”, the backend restarted or the session expired, so sign in again. If no /answer webhook appears at all, the endpoint isn’t attached to your application. Sign in again on the Vobiz account tab, or attach it yourself for SIP direct.

“The call could not be placed” or “This account has no phone number to call from”

Vobiz refused the call to the customer (check the balance, the destination and the caller ID in the backend log), or no caller ID is selected.

Inbound callers hear “nobody is available”, or ringing that never reaches the panel

Nobody is signed in to the account that owns the number, the number isn’t attached (click Enable inbound calls), or no panel is open and Ready.

Connected, but no audio

The browser blocked the microphone. Allow it for Freshdesk in the address bar, then reload.

A recording won't play

Playback links expire after 5 minutes, so refresh the list. If nobody from that account is signed in right now (for example after a backend restart), sign in again first.

Webhooks get 403

VOBIZ_WEBHOOK_SIGNATURE=require is set, and either PUBLIC_BASE doesn’t exactly match the URL Vobiz calls, or nobody has signed in with a Vobiz account. Fix PUBLIC_BASE, or set the mode to log.

Limitations

Nothing is written to Freshdesk. The app does not create tickets, add call notes, show the caller’s contact (screen pop) or attach recordings. The only link to Freshdesk data is click-to-call.
Inbound calls answer themselves. The panel doesn’t ring first, doesn’t show the caller’s number, and has no Accept or Decline buttons.
There are no hold, mute, transfer or conference controls.
Sign in again after reloading the page, after the backend restarts, and after 12 hours (SESSION_TTL_HOURS).
Run one backend instance.
With SIP direct or OUTBOUND_MODE=dial, the panel shows “On a call” while the customer’s phone is still ringing. Only the conference bridge reports when the customer answers.
SIP direct has no recordings list, no caller-ID list and no Enable inbound calls, and outbound calls always use a plain dial.
The recordings list covers the whole Vobiz account, not just your own calls.
Calls run only in the browser. Inbound calls need an open, signed-in Freshdesk tab.

Source code and support

GitHub repository

The panel, the backend, the full README and the backend route reference.

Endpoints

How SIP endpoints and applications fit together in the Console.

For questions about accounts, numbers or billing, email support@vobiz.ai.

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

CRM & Helpdesk

Migrations

Freshdesk integration

What you get

Click-to-call

Inbound calls in the browser

Caller ID choice

Call recording

Two ways to sign in

One backend, any account

How it works

Prerequisites

Set it up

Signing in

Vobiz account (recommended)

Enabling inbound calls

SIP direct

Using it

Configuration reference

Deploying to production

Security and privacy

Troubleshooting

Limitations

Source code and support

GitHub repository

Endpoints

​What you get

Click-to-call

Inbound calls in the browser

Caller ID choice

Call recording

Two ways to sign in

One backend, any account

​How it works

​Prerequisites

​Set it up

​Signing in

​Vobiz account (recommended)

​Enabling inbound calls

​SIP direct

​Using it

​Configuration reference

​Deploying to production

​Security and privacy

​Troubleshooting

​Limitations

​Source code and support

GitHub repository

Endpoints

What you get

How it works

Prerequisites

Set it up

Signing in

Vobiz account (recommended)

Enabling inbound calls

SIP direct

Using it

Configuration reference

Deploying to production

Security and privacy

Troubleshooting

Limitations

Source code and support