Node.js SDK

The official Node.js SDK for the Vobiz Voice API. Make calls, manage SIP trunks, handle CDR, record calls, configure phone numbers, and more—all natively from your Node.js or TypeScript backend.

Source Code: vobiz-ai/Vobiz-Node-SDK

Installation

Clone the repository and install the dependencies locally:

Bash

git clone https://github.com/vobiz-ai/Vobiz-Node-SDK.git
cd Vobiz-Node-SDK
npm install

Authentication

All API calls require your Auth ID and Auth Token. You can find these credentials inside the Vobiz Console.

Initialize the client directly:

JavaScript

const { Client } = require('vobiz-node');

const client = new Client('YOUR_AUTH_ID', 'YOUR_AUTH_TOKEN');

Or define environment variables and pass nothing:

Bash

export VOBIZ_AUTH_ID=YOUR_AUTH_ID
export VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN

JavaScript

const client = new Client(); // Injects variables automatically

Quick Start

Making an outbound call is extremely straightforward:

JavaScript

const { Client } = require('vobiz-node');

const client = new Client(process.env.VOBIZ_AUTH_ID, process.env.VOBIZ_AUTH_TOKEN);

// Make an outbound call
client.calls.create(
  '+911171366914',                 // Source Caller ID
  '+919148227303',                 // Destination
  'https://yourserver.com/answer', // Webhook responding with VobizXML
  { hangupUrl: 'https://yourserver.com/hangup' }
).then(res => {
  console.log('Call queued with UUID:', res.requestUuid);
}).catch(console.error);

API Reference

The SDK is categorized into specialized namespaces mapped directly to the REST API submodules.

Live & Queued Calls

JavaScript

// Hang up a live call
client.calls.hangup(callUuid);

// Transfer to another leg
client.calls.transfer(callUuid, { legs: 'aleg', alegUrl: 'https://...' });

// Call injection: Play Audio & TTS
client.calls.playMusic(callUuid, ['https://example.com/audio.mp3']);
client.calls.speakText(callUuid, 'Hello from Vobiz', { voice: 'WOMAN', language: 'en-US' });

// Send DTMF Digits
client.calls.sendDigits(callUuid, '1234');

// Stream Audio (WebSocket fork)
client.calls.stream(callUuid, 'wss://your-agent.com', { audioTrack: 'inbound' });

Call Detail Records (CDR)

JavaScript

// Fetch historical call records with optional parameters
client.cdr.get({
  limit: 20,
  offset: 0,
  startTime: '2026-01-01T00:00:00Z',
  callDirection: 'outbound'
}).then(history => {
  console.log(`Fetched ${history.length} records`);
});

Conferences

JavaScript

// Get conference details and act upon them via chained members
client.conferences.get('sales-channel').then(conference => {
  conference.kickMember(memberId);
  conference.muteMember(memberId);
  conference.playAudioToMember(memberId, 'https://example.com/chime.mp3');
  conference.record({ fileFormat: 'mp3', transcriptionType: 'auto' });
});

VobizXML

The SDK is used purely for REST interactions (Outbound dials, Live mutations, Provisioning). When a call naturally answers, Vobiz expects standard VobizXML logic returned from your webhook server endpoint:

JavaScript

app.post('/answer', (req, res) => {
  const xml = `<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Speak voice="WOMAN" language="en-US">Thank you for calling.</Speak>
</Response>`;
  
  res.type('text/xml').send(xml);
});

Webhooks & Verification

It's a strict best practice to verify that your webhook events legitimately originated from Vobiz. Use the baked-in validator for maximum security:

JavaScript

const { validateSignature } = require('vobiz-node');

app.post('/webhook', (req, res) => {
  const isValid = validateSignature(
    req.url,
    req.headers['x-vobiz-signature'],
    req.body,
    process.env.VOBIZ_AUTH_TOKEN
  );

  if (!isValid) return res.status(401).send('Unauthorized payload');
  
  // Proceed with processing
});

Integrations