HubSpot + Vobiz | Softphone & Call Logging Inside HubSpot CRM

Vobiz Calling for HubSpot adds a Vobiz softphone to HubSpot’s calling panel. You run a small Node.js backend, register it with HubSpot as a calling provider, and your agents sign in with their Vobiz account. They place and take calls in the browser over WebRTC, and HubSpot logs each call on the contact’s timeline. Source code: vobiz-ai/Vobiz-HubSpot-Calling

Features

Click-to-call. Click any phone number in HubSpot, or type one into the panel.
Inbound calls with a screen pop. A call to your Vobiz number rings every signed-in agent with an Answer / Decline overlay. The first agent to answer takes it.
Call logging. HubSpot creates a call engagement on the contact’s timeline for every call, inbound and outbound.
Recordings. Every call is recorded. Agents play recent recordings in the panel.
Caller ID choice. Agents pick which of your Vobiz numbers their calls go out from.
Multi-agent. Each HubSpot user gets their own Vobiz SIP endpoint, created automatically on first sign-in.
Two sign-in modes. Your Vobiz account (Auth ID + Auth Token), or one existing SIP endpoint’s username and password.
Any Vobiz account. One backend serves any number of Vobiz accounts. Nothing account-specific is configured on the server.

How it works

 HubSpot (calling panel)                 Your backend                        Vobiz
 widget  ── sign in (HTTPS) ──────────▶  /login  ── REST API ─────────────▶  application, endpoints, numbers
 widget  ── SIP over WebSocket ──────────────────────────────────────────▶  registrar
 widget  ── call (SIP INVITE) ───────────────────────────────────────────▶  Vobiz ── answer URL ─▶ /answer
                                         /answer ── <Dial><Number> ──────▶  rings the customer
 caller  ──────────────────────────────────────────────────────────────▶  your number ─▶ /answer
                                         /answer ── <Dial><User> ────────▶  rings the agents' browsers
 widget  ── call started / ended ─▶ HubSpot logs the call on the contact

HubSpot loads the widget in its calling panel. Your backend serves it at /widget/.
An agent signs in from the widget. The backend checks the credentials with Vobiz and sets up what the account needs: an application and one SIP endpoint per agent.
The browser registers as that agent’s SIP endpoint and places outbound calls itself.
Vobiz asks your backend’s answer URL (/answer) what to do with each call. Outbound, the backend dials the customer. Inbound, it rings the browsers of the signed-in agents.
Every call is recorded, and Vobiz tells the backend when the recording is ready.
The widget tells HubSpot when a call starts and ends. HubSpot writes the call to the contact’s timeline using the agent’s own HubSpot session.

Prerequisites

You need	Details
A Vobiz account	Your Auth ID and Auth Token from the Vobiz Console → API credentials, at least one active voice-enabled number, and call balance
A HubSpot account	Admin rights to install apps, and Developer tools access (or a Developer seat on seat-based accounts) to create the app
A public HTTPS URL	For the backend, for example `https://calling.example.com`. Vobiz calls it for every call, and HubSpot loads the widget from it
Node.js	Version 20.12 or newer
A browser and microphone	A current Chrome, Edge or Firefox. Agents must allow microphone access

Setup

Clone, install and configure

git clone https://github.com/vobiz-ai/Vobiz-HubSpot-Calling.git
cd Vobiz-HubSpot-Calling
npm ci
npm run build                         # builds the widget bundle
cp backend/.env.example backend/.env

Set at least these in backend/.env. There are no Vobiz credentials in it.

PUBLIC_BASE=https://calling.example.com
SIGNING_SECRET=<a long random string, e.g. from: openssl rand -hex 32>

Run the backend and expose it

npm start                             # listens on port 8092

Put it behind your public HTTPS URL, then check it from outside your network:

curl -s https://calling.example.com/health
curl -s -X POST https://calling.example.com/answer -d "Event=Hangup"

The second command must print <Response></Response>. If Vobiz cannot fetch the answer URL, calls fail.

Get HubSpot developer access

Turn on Developer tools access for your user (Settings → Users & Teams → your user → Permissions). On seat-based accounts, assign a Developer seat instead.

Create the HubSpot app

The HubSpot CLI is installed with the project’s dev dependencies.

npx hs account auth                           # authenticate the CLI once
npm run sync-urls                             # writes PUBLIC_BASE into src/app/app-hsmeta.json
npx hs project upload --account=<portalId>
npx hs project info --account=<portalId>      # shows the App ID

Copy the app’s Client ID and Client secret (Development → Projects → your app → Auth) into backend/.env as HUBSPOT_CLIENT_ID and HUBSPOT_CLIENT_SECRET, and restart the backend.

npm run sync-urls edits src/app/app-hsmeta.json in place with your hostname. Do not commit that change. Run it and upload again whenever your hostname changes.

Add HUBSPOT_APP_ID and HUBSPOT_DEVELOPER_API_KEY to backend/.env (or export them; the shell wins). The widget URL defaults to <PUBLIC_BASE>/widget/; set WIDGET_URL only to use a different one.

npm run calling:configure

This registers Vobiz Calling as a provider, turns on inbound calling, and makes it available to your users. npm run calling:show prints the current settings.

Install the app

Open https://calling.example.com/hubspot/install and choose your HubSpot account. You land on Connected to HubSpot.

Installing a calling app needs a user with CRM permissions. In a portal where you are the only user, the install fails with “There was a problem fetching approvers”. Install into a developer test account instead (npm run test-account "Vobiz Calling Test", which uses the key npx hs account auth saved in ~/.hscli/config.yml, or create one in HubSpot).

Choose Vobiz as the calling provider

Open a contact with a phone number and click Call. At the bottom of the call popover, click Change provider and pick Vobiz Calling.

The panel opens on a Connecting badge with two sign-in tabs.

Vobiz Calling for HubSpot panel showing a Connecting badge and step 1 Sign in to Vobiz with Vobiz account and SIP direct tabs plus Auth ID and Auth Token fields — The panel on load, with the two sign-in tabs.

Vobiz account (recommended)

Enter your Auth ID (MA_XXXXXXXX) and Auth Token from the Console → API credentials. The Auth Token is not your Console login password. When you sign in, the backend checks the credentials with Vobiz and sets up your account:

An application named vobiz-hubspot-calling-integration, with its answer URL and hangup URL set to https://calling.example.com/answer (POST). If it exists, it is reused and pointed at your backend. No other application is changed.
One SIP endpoint per agent, with the alias hubspot-<agent>, linked to that application. Each HubSpot user gets their own endpoint. A fresh random SIP password is set on every sign-in and sent only to that agent’s browser.

Signing in does not move any of your numbers. Once the browser registers, the badge turns to Ready.

Panel showing a green READY badge, the signed-in Vobiz account marked ACTIVE with its caller ID, and the Choose a caller ID and Place a call steps beneath — Signed in and ready to call.

Choose a caller ID. Calling from lists your account’s active, voice-enabled numbers. Outbound calls show the number you pick. The backend refuses any number that is not on your account.

The Calling from field expanded into a dropdown listing Vobiz numbers available as outbound caller IDs — Pick the number your calls go out from.

SIP direct

Use this for agents who should not hold your account’s Auth Token. Enter an existing endpoint’s SIP username, its SIP password, and the Calling from number in E.164 format (+91XXXXXXXXXX). The password stays in the browser and never reaches the backend. First, point the endpoint and the number at an application whose answer URL is your backend:

In the Console, create an application with Answer URL and Hangup URL set to https://calling.example.com/answer, method POST.
Under Voice → Endpoints, set the endpoint’s application to it.
Under Numbers, attach the caller-ID number to the same application.

The API equivalent is Create an application, then Update an endpoint with {"app_id": "<app_id>"}, then Attach a number.

Use the endpoint’s stored username exactly as Console → Voice → Endpoints shows it, and a separate endpoint for each integration: an endpoint belongs to one application at a time.

SIP direct has no number dropdown, no Enable inbound calls and no recordings list; those need the account API. Inbound calls to the caller-ID number ring a SIP direct agent.

Enable inbound calls

Signed in with your Vobiz account, open Enable inbound calls, pick the number customers should call, and click Enable inbound calls. This attaches the number to the vobiz-hubspot-calling-integration application, so calls to it ring your signed-in agents.

A number belongs to one application at a time, so this moves the number off the application it is on now. The dropdown shows each number’s current application (now on app …), and the confirmation names the application it moved from, with its ID.

You only need to do this once per number.

Using it

Outbound. Click a phone number anywhere in HubSpot, or type a number with its country code into Number to call and click Call. The button is enabled once the badge shows Ready. During the call the panel shows a timer and Hang up.

Panel during a live call showing the Hang up button and a status line with an elapsed timer — An outbound call in progress.

Inbound. Keep HubSpot open and the panel signed in. A call to an enabled number raises the Incoming Vobiz Call overlay for every agent signed in to that Vobiz account. Answer (or Enter) picks up; Decline (or Escape) dismisses. If no agent is signed in, the caller hears “Sorry, no one is available to take your call right now” and the call ends.

Call logging. For every call, the widget tells HubSpot the call has started and, when it ends, that it is complete. HubSpot creates the call engagement itself and shows it on the contact’s activity timeline, where you can add notes and an outcome. The backend does not write to HubSpot, and the app asks only for the oauth scope. Recordings. Every call, inbound and outbound, is recorded, up to one hour per call. Call recordings in the panel lists the account’s 15 most recent recordings. Play streams the audio through a signed link that expires after 15 minutes by default.

Call recordings list showing recording entries with timestamps and Play buttons — Recent recordings with the inline player.

Calls ring for up to 30 seconds and are limited to 4 hours.

Configuration

The backend reads backend/.env.

Variable	Required	Default	Meaning
`PUBLIC_BASE`	Yes	none	Your backend’s public HTTPS URL. Becomes the answer URL in each Vobiz account
`SIGNING_SECRET`	Yes in production	random per start	Signs recording links. If unset, links stop working after every restart
`HUBSPOT_CLIENT_ID`	Yes	none	Your HubSpot app’s Client ID
`HUBSPOT_CLIENT_SECRET`	Yes	none	Your HubSpot app’s Client secret
`HUBSPOT_SCOPES`	No	`oauth`	Scopes requested at install. Matches the app; extra scopes make the install ask for CRM permissions
`HUBSPOT_REDIRECT_URI`	No	`<PUBLIC_BASE>/hubspot/callback`	OAuth redirect. Must match the app’s redirect URL
`PORT`	No	`8092`	Port the backend listens on
`RECORDING_URL_TTL_SECONDS`	No	`900`	How long a recording link stays valid
`SESSION_TTL_HOURS`	No	`12`	How long a sign-in lasts
`DATA_DIR`	No	`backend/data`	Directory for the backend’s state files (mode 0700; files 0600)
`AGENT_ENDPOINT_STORE`	No	`<DATA_DIR>/agent-endpoints.json`	File mapping each agent to their Vobiz endpoint
`ALLOWED_ORIGINS`	No	none	Extra browser origins allowed to call the backend, comma separated
`TUNNEL_URL`	No	none	Used as the public URL when `PUBLIC_BASE` is not set
`VOBIZ_API_URL`	No	`https://api.vobiz.ai`	Vobiz REST API. Leave the default
`VOBIZ_REGISTRAR`	No	`registrar.vobiz.ai`	Vobiz SIP registrar. Leave the default

npm run calling:configure reads HUBSPOT_APP_ID, HUBSPOT_DEVELOPER_API_KEY and WIDGET_URL (plus optional CALLING_APP_NAME, default Vobiz Calling) from backend/.env and your shell (the shell wins). WIDGET_URL defaults to <PUBLIC_BASE>/widget/.

Deploying to production

Use a stable HTTPS hostname. If it changes, update PUBLIC_BASE, run npm run sync-urls and npx hs project upload, re-run npm run calling:configure, and have each account sign in again.
Run exactly one backend instance. Sign-ins and calls are held in memory.
Keep DATA_DIR on persistent storage (default backend/data). The agent → endpoint map and the HubSpot OAuth tokens are saved there.
Set SIGNING_SECRET to a fixed value so recording links survive restarts.

Security

Your Auth Token never leaves the server and is never stored on disk. It is kept in the backend’s memory, never logged and never returned to the browser.
The browser gets a session token for that tab and its own endpoint’s SIP credentials. An agent can only read their own.
SIP direct passwords never reach the backend.
Recording links carry no credentials. Each is signed for one recording in one account and expires.
The backend only answers browsers from HubSpot, localhost, its own origin, and origins you add in ALLOWED_ORIGINS.
An inbound call rings only agents of the Vobiz account that owns the number.
Anyone who signs in with the Auth ID and Auth Token holds your account’s API credentials. Use SIP direct for agents who should not.

Troubleshooting

HubSpot says "Calling is offline"

The widget did not load: the bundle was not built, or the backend is unreachable. Run npm run build, restart, and check that https://calling.example.com/widget/ opens in a browser.

The calling panel is blank

Your host is not in the app’s permitted URLs. Run npm run sync-urls, then npx hs project upload.

Vobiz Calling is not in the provider list

The app is not installed in this portal, the widget is not registered, or it was registered with --not-ready. Check with npm run calling:show, re-run npm run calling:configure, and install from /hubspot/install into this portal.

"Your account doesn't have access to developer tools"

Grant your HubSpot user Developer tools access, or assign a Developer seat.

"There was a problem fetching approvers"

You are installing into a portal where you are the only user, so there is nobody to approve. Install into a developer test account.

The install asks for contacts or custom-object permissions

HUBSPOT_SCOPES is set to more than oauth. Remove it (the default is oauth), restart, and install again.

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

The status never reaches Ready

The browser could not register its SIP endpoint. With a Vobiz account, sign in again. With SIP direct, use the endpoint’s stored username from Console → Voice → Endpoints. If the agent is signed in on another browser, that sign-in replaced the password: use one browser per agent.

The customer's phone never rings

Vobiz cannot reach your answer URL, or the application points at an old hostname. curl -X POST https://calling.example.com/answer -d "Event=Hangup" must return XML. Sign in again to point the application at the current PUBLIC_BASE.

The outbound call ends straight away

The agent has no valid caller ID. Choose a number under Calling from, and check in the Console that it is active and voice-enabled.

Inbound callers hear "no one is available"

No agent of that Vobiz account is signed in to the panel, for example right after the backend restarted. Sign in.

Inbound calls do not reach the panel

The number is not attached to the integration’s application. Click Enable inbound calls for it.

The browser rings but HubSpot shows nothing

Inbound calling is off in HubSpot’s calling settings. Re-run npm run calling:configure without --no-inbound.

A recording will not play

“Sign in to the calling panel again” means the backend restarted: sign in and refresh the list. “Invalid or has expired” means the link is older than RECORDING_URL_TTL_SECONDS or SIGNING_SECRET changed: refresh the list.

Operating notes

Sign in again after the backend restarts. Sessions and Auth Tokens live in memory. Inbound callers to an account hear the “no one is available” message until one of its agents signs in.
Run one backend instance. Each instance keeps its own state.
Use one browser per agent. Signing in from a second browser disconnects the first.
Inbound calls ring every signed-in agent of the account.
Every call is recorded, up to one hour per call.
Recordings are in the panel.
A Vobiz account sign-in gives you the number list, Enable inbound calls and recordings. With SIP direct, type the password again after a page reload.
Install the app privately in your HubSpot account.

Next steps

Source code

Clone the backend and widget, and read the full README.

Other CRMs

The same softphone for Zendesk, Pipedrive and Freshdesk.

Reference: <Dial>, <Record>, SIP endpoints, Applications.

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

CRM & Helpdesk

Workflow Automation

Migrations

HubSpot + Vobiz | Softphone & Call Logging Inside HubSpot CRM

Features

How it works

Prerequisites

Setup

Vobiz account (recommended)

SIP direct

Enable inbound calls

Using it

Configuration

Deploying to production

Security

Troubleshooting

Operating notes

Next steps

Source code

Other CRMs

​Features

​How it works

​Prerequisites

​Setup

​Sign in

​Vobiz account (recommended)

​SIP direct

​Enable inbound calls

​Using it

​Configuration

​Deploying to production

​Security

​Troubleshooting

​Operating notes

​Next steps

Source code

Other CRMs

Features

How it works

Prerequisites

Setup

Sign in

Vobiz account (recommended)

SIP direct

Enable inbound calls

Using it

Configuration

Deploying to production

Security

Troubleshooting

Operating notes

Next steps