Pipedrive integration

A browser softphone that logs every call to Pipedrive. Agents dial from the page, talk in the tab, and the call lands in the CRM as an Activity and a Call Log with duration and a signed recording link. Source code: vobiz-ai/internal-pipedrive-crm — the softphone, the embedded CTI panel, and the Node backend that answers Vobiz webhooks and syncs to Pipedrive.

Scope: inbound and outbound, with browser audio over WebRTC. Verified end to end against a live Vobiz account and a live Pipedrive sandbox — both directions connect with two-way audio and activities appear in the CRM.

What you get


Click-to-call	Dial from the panel, or from a person record
Activity + Call Log	Every call written through `POST /activities` and `POST /callLogs`
Caller lookup	Inbound numbers resolved through `/persons/find`, falling back to `/itemSearch`
In-call controls	Mute, Hold and Transfer while connected
Recordings	Playable from the panel behind an HMAC-signed, short-expiry link
Browser audio	Calls run over WebRTC in the tab — no desk phone, no desktop app

How it works

The one thing to understand first: the browser is the A leg. The page sends the SIP INVITE itself, and the backend answers <Dial><Number> to reach the customer.

browser ──SIP INVITE──▶ Vobiz ──answer_url──▶ backend /answer
                                                  │
                                           <Dial><Number> ──▶ customer

The intuitive design does not work, and is what this app used to do. Originating to the customer over the REST API and then bridging the agent in with <Dial><User> is blocked platform-side: Vobiz builds a gateway URI it cannot parse and drops its own INVITE (tr_eval_uri(): invalid uri, blocking gw). The customer answers, hears ringback, then “the agent could not be reached”.Inbound is the exception — <Dial><User> is the only way to reach a registered endpoint, and it works today.

Path	Role
`backend/server.js`	Webhooks, softphone API, CRM sync
`backend/pipedrive-oauth.js`	OAuth 2.0 — authorize, exchange, refresh, `api_domain`
`agent-phone/`	The softphone — `vobiz-sip.js` is the SIP layer (register, dial, answer, mute/hold/DTMF)
`pipedrive-app/`	The embedded CTI panel for Pipedrive
`backend/fetch-cdr.js`	CLI — pull CDRs from Vobiz and sync them

Requirements

Requirement	Detail
Vobiz account	`AUTH_ID`, `AUTH_TOKEN`, a number, and balance — console.vobiz.ai
Pipedrive sandbox	From developers.pipedrive.com
Public HTTPS URL	`cloudflared` or ngrok. Vobiz must reach `/answer`, `/dial-status` and `/recording-callback`
Runtime	Node 18+

Step 1: Prove the Vobiz account

Place a call with rtc-demo.vobiz.ai. If that fails, nothing here will work and you will debug the wrong layer for a day.

Step 2: Create the SIP endpoint

curl -X POST "https://api.vobiz.ai/api/v1/Account/$AUTH_ID/Endpoint/" \
  -H "X-Auth-ID: $AUTH_ID" -H "X-Auth-Token: $AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"pdagent","password":"<choose one>","alias":"Pipedrive Agent"}'

Vobiz rewrites the username you submit. Send pdagent and the stored username comes back as something like pdagent1187694299145202883643. Read the stored username out of the response — that is what registers, and what VOBIZ_SIP_USER must contain.

Step 3: Run the backend

cp backend/.env.example backend/.env    # fill it in
npm start                               # :8092 by default
cloudflared tunnel --url http://localhost:8092

Put the tunnel URL in TUNNEL_URL, then check the answer URL is alive before touching any UI:

curl -s -X POST "$TUNNEL_URL/answer" \
  -d "From=sip:x@registrar.vobiz.ai&To=91XXXXXXXXXX&RouteType=sip"

You must get <Response> containing <Dial …><Number>. Anything else — an ngrok interstitial, a 404 page — and every call dies.

Step 4: Point Vobiz at the backend

Create an application whose answer_url is $TUNNEL_URL/answer, bind the SIP endpoint to it, and attach a DID for inbound:

# create the application
curl -X POST ".../Account/$AUTH_ID/Application/" -d '{
  "app_name":"Pipedrive Calling","answer_url":"'"$TUNNEL_URL"'/answer",
  "answer_method":"POST","hangup_url":"'"$TUNNEL_URL"'/answer","hangup_method":"POST"}'

# bind the endpoint — the field is app_id, NOT the documented `application`,
# which is silently ignored and still returns 202 "changed"
curl -X POST ".../Account/$AUTH_ID/Endpoint/$ENDPOINT_ID/" -d '{"app_id":"'"$APP_ID"'"}'

# attach a DID for inbound. Lowercase /numbers, + encoded as %2B.
# /Number/ returns a bare 401 that reads like a credentials problem and is not.
curl -X POST ".../Account/$AUTH_ID/numbers/%2B91XXXXXXXXXX/application" \
  -d '{"application_id":"'"$APP_ID"'"}'      # 204 on success

Step 5: Connect Pipedrive over OAuth

In Developer Hub → Create public app, set the callback URL to $TUNNEL_URL/auth/pipedrive/callback — it must match PIPEDRIVE_REDIRECT_URI exactly, and only one callback URL is allowed per app. Request these scopes and nothing more. Over-scoping is a documented rejection reason:

Toggle	Setting	Used for
Deals	Read only	Activities link to `deal_id`
Activities	Full access	`POST /activities`
Contacts	Read only	`/persons/find` caller lookup
Search for all data	On	`/itemSearch` fallback lookup
Call logs	On	`POST /callLogs`

Put the Client ID and Secret in .env, visit $TUNNEL_URL/auth/pipedrive and approve. GET /auth/pipedrive/status should then report "connected": true. Open the panel. Before credentials are entered it shows NOT SIGNED IN.

The panel before sign-in.

Sign in with the Auth ID and Auth Token from the console under API credentials. The badge turns green when JsSIP has registered.

Registered. The badge reads READY and the signed-in account is shown.

Wait for Ready before dialling. The Call button stays disabled until JsSIP registers, deliberately — dialling with SIP down rings the customer into silence.

Choose a caller ID

Calling from lists the numbers on the account. Carriers require a real number here to bridge a call to a mobile or landline.

Place the call

Type a number in E.164 format or use the built-in dialpad.

The Place a call step with a destination number typed into the Number to call field and a numeric dialpad below it — Entering the destination number on the dialpad.

Once connected the panel shows the timer and the in-call controls — Mute, Hold and Transfer — with the matched Pipedrive contact underneath.

Live call view showing a red Hang up button, a Calling status line with a ten-second timer, Mute Hold and Transfer buttons, and a Pipedrive CRM contact panel below — An active call, with in-call controls and the matched CRM contact.

Inbound calls

A call to the attached DID raises an in-panel prompt. Enter accepts, Escape declines.

When the call ends

A summary confirms the duration and — the part that matters — that the call reached the CRM.

Call Finished notification card showing an Inbound call completed badge, the number, duration and finish time, and a green Synced to Pipedrive CRM Activity and Call Log confirmation — Call finished, with the CRM sync confirmed on the card itself.

Recordings are listed with their timestamp and duration, each with its own inline player.

Call recordings list showing three timestamped entries with durations, two of them expanded into inline audio players, above Activity log and Frequently asked sections — Recordings, with inline players.

Backend routes

Route	Role
`POST /answer`, `/fallback`	The XML Vobiz executes. Branches on direction
`POST /dial-status`	The `action` target of `<Dial>`
`POST /recording-callback`	Fires when the recording is downloadable
`POST /hangup-callback`, `/hangup-call`	Call teardown
`POST /start-call`, `/transfer-call`	Softphone call control
`POST /login`, `/login-sip`, `/logout`, `GET /session`	Session handling
`GET /numbers`, `/api/agent-sip`	Caller IDs and SIP identity
`GET /recordings`, `/recording-info`, `/recording-file`, `/play-recording`	Recording access
`GET /auth/pipedrive`, `/callback`, `/status`, `/disconnect`	Pipedrive OAuth
`GET /api/pipedrive/persons/lookup`	Caller lookup
`POST /sync-recent-cdrs`	Backfill CDRs into the CRM
`GET /health`	Resolved configuration

Testing

npm test                  # everything
npm run test:outbound
npm run test:inbound
npm run test:recording    # SSRF regression tests
npm run test:sync

The suite reports PASS / FAIL / SKIP and exits non-zero on failure. A fully configured run is 9 passed, 0 failed, 0 skipped.

SKIP is not a pass. It means a service is not configured, and the summary says so. Mocks are opt-in (ALLOW_MOCK=1) and label themselves — they used to be the silent fallback, which made the whole suite pass against a CRM it had never contacted.

Security

Recording playback is HMAC-signed with a short expiry and carries no credentials. It previously took a url parameter and fetched it with the account’s Vobiz credentials attached — a credential-exfiltration primitive any web page could drive. Never reintroduce a caller-supplied URL here.
The browser never holds the Vobiz Auth Token. It is POSTed once at sign-in and exchanged for an opaque session token.
CORS is an allowlist, not *.
OAuth tokens live in backend/.pipedrive-tokens.json, mode 0600, gitignored. That file holds a refresh token — a long-lived credential for the customer’s entire CRM.

Troubleshooting

The backend log is the honest account. The field that matters:

[DIAL RESULT] status=completed ring=true cause=NORMAL_CLEARING bleg=abc-123 dur=42

DialBLegUUID is the single most useful field in this stack. Present means it connected; empty means no B leg was ever created, whatever the UI showed.

Symptom	Cause
No `WEBHOOK /answer` line at all	Endpoint not bound to the application, or `TUNNEL_URL` is stale
`bleg=(none…)`	Destination unreachable, or the caller ID is not owned by this account
No CDR in Vobiz at all	`422 Session Interval Too Small` — a session-timer problem
CDR billed `0s`	SDP/ICE — check STUN candidates in the browser console
Panel stuck on Connecting…	Backend unreachable, or it crashed — check the log
Registration failed	Wrong `VOBIZ_SIP_USER` — probably the name you submitted, not the one Vobiz stored
Caller hears ringback then the fallback	`<Dial><User>` naming an endpoint that is not registered

Three client settings in agent-phone/vobiz-sip.js are not optional, and all three fail in ways that point nowhere near the cause:

Setting	Symptom without it
`session_timers: false`	`422`, surfaced as the opaque cause SIP Failure Code, and no CDR at all
`pcConfig.iceServers`	Host-only candidates, Incompatible SDP, CDR billed `0s`
Space-free `user_agent`	Vobiz interpolates it unescaped into a gateway URI; JsSIP’s default contains a space

Ignore the Endpoint API’s sip_registered. It reads "false" even when registration genuinely succeeded, on every endpoint on the account. The panel gates on JsSIP’s registered event instead.Quick tunnels are the most common cause of “it stopped working.” The hostname changes on every restart, and TUNNEL_URL, the Vobiz application’s answer_url and the Pipedrive OAuth callback all go stale together.

Next steps

Clone the app: vobiz-ai/internal-pipedrive-crm
The same softphone in other CRMs: Zendesk, HubSpot, Freshdesk
Reference: <Dial>, <Record>, SIP endpoints, CDRs

AI Voice Platforms

Official SDKs

Browser & WebRTC

Business Phone Systems

CRM & Helpdesk

Migrations

Pipedrive integration

What you get

How it works

Requirements

Step 1: Prove the Vobiz account

Step 2: Create the SIP endpoint

Step 3: Run the backend

Step 4: Point Vobiz at the backend

Step 5: Connect Pipedrive over OAuth

Choose a caller ID

Place the call

Inbound calls

When the call ends

Backend routes

Testing

Security

Troubleshooting

Next steps

​What you get

​How it works

​Requirements

​Step 1: Prove the Vobiz account

​Step 2: Create the SIP endpoint

​Step 3: Run the backend

​Step 4: Point Vobiz at the backend

​Step 5: Connect Pipedrive over OAuth

​Step 6: Sign in and call

​Choose a caller ID

​Place the call

​Inbound calls

​When the call ends

​Backend routes

​Testing

​Security

​Troubleshooting

​Next steps

What you get

How it works

Requirements

Step 1: Prove the Vobiz account

Step 2: Create the SIP endpoint

Step 3: Run the backend

Step 4: Point Vobiz at the backend

Step 5: Connect Pipedrive over OAuth

Step 6: Sign in and call

Choose a caller ID

Place the call

Inbound calls

When the call ends

Backend routes

Testing

Security

Troubleshooting

Next steps