Vobiz Calling for HubSpot

The browser is the A leg. The widget sends the SIP INVITE itself; the backend answers <Dial><Number> to reach the customer.

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

The intuitive design — the backend dials the customer over the REST API, then bridges the agent in with <Dial><User> — cannot work. Routing into a registered WebRTC endpoint is blocked platform-side: Vobiz builds a gateway URI it cannot itself parse and drops its own INVITE. 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.

HubSpot creates the call engagement itself, from the SDK messages the widget sends (cti.outgoingCall, cti.incomingCall, cti.callCompleted), using the agent's own session. The backend never writes to the CRM, which is why the app needs no CRM scopes.

Requires Node 18+, a Vobiz account with a number and balance, a HubSpot account with developer tools, and cloudflared (or ngrok) for a public HTTPS URL.

The one-time setup is in docs/SETUP_GUIDE.md. Per session:

npm install
npx webpack                                     # build the widget bundle
npm start                                       # backend on :8092
cloudflared tunnel --url http://localhost:8092  # public HTTPS

Put the tunnel URL in PUBLIC_BASE, restart, then verify before touching the UI:

curl -s "$PUBLIC_BASE/health"
curl -s "$PUBLIC_BASE/hubspot/status"                              # "connected": true
curl -sL -o /dev/null -w '%{http_code}\n' "$PUBLIC_BASE/widget"    # 200
curl -s -X POST "$PUBLIC_BASE/answer" \
  -d "From=sip:x@registrar.vobiz.ai&To=91XXXXXXXXXX&RouteType=sip"

The last one must return <Response> containing <Dial …><Number>. Anything else — a tunnel error page, an ngrok interstitial — and every call dies silently.

If the tunnel hostname changed, four things go stale together: PUBLIC_BASE, the Vobiz answer_url, permittedUrls.iframe, and the HubSpot widget URL.

Copy backend/.env.example to backend/.env. Everything is set there.

Behaviours worth knowing before changing anything:

• <Record> is a self-closing sibling before <Dial>, never nested inside it. The nested form is rejected and the caller hears a bogus "Busy".
• action and redirect="false" are both required on <Dial>. Without them Vobiz re-fetches the answer URL when <Dial> ends and re-executes the document, so one call dials the customer over and over.
• callerId is mandatory on the inbound branch. Omit it and Vobiz derives it from the A leg — the caller's number, which the account does not own — so B-leg creation is refused silently and the browser never rings.
• A Hangup notification is not a request for instructions. Returning <Dial> hands Vobiz a fresh call leg after the call has already ended.
• Ignore the Endpoint API's sip_registered. It reads "false" even when registration genuinely succeeded. Gate on JsSIP's registered event instead.

Three JsSIP settings are not optional, and each fails in a way that points nowhere near the cause:

The backend log is the honest account. The field that matters is DialBLegUUID: present means the call connected, empty means no B leg was ever created, whatever the UI showed.

See docs/TROUBLESHOOTING.md for symptom-driven debugging.

• The backend is single-account. It binds to one Vobiz account through .env, and every agent who signs in shares one SIP endpoint. Two agents on one install register as the same endpoint and race for calls. Real multi-agent use needs an endpoint per agent and an identity store.
• agentId is self-asserted. It selects a label, not an identity.
• Quick tunnels are the most common cause of "it stopped working." Use a stable hostname for anything beyond a demo.

Full guide: https://www.vobiz.ai/docs/integrations/hubspot

MIT