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

The SDK is distributed from its GitHub repo (not a package registry). Clone it and install from source:

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

Quick start

Make an outbound call:

javascriptCopy
import { VobizClient } from "@vobiz/sdk";

const authId = process.env.VOBIZ_AUTH_ID;

const client = new VobizClient({
  apiKey: authId,                          // your Auth ID
  authToken: process.env.VOBIZ_AUTH_TOKEN, // your Auth Token
});

const call = await client.calls.makeCall({
  auth_id: authId,
  from: "14155551234",                      // your Vobiz number or SIP URI
  to: "+919876543210",                       // destination number
  answer_url: "https://yourserver.com/answer", // webhook returning VobizXML
  answer_method: "POST",
});

console.log("Call initiated:", call);

ℹ️ Note: Resources and client namespaces are camelCase (e.g. client.liveCalls), while request body fields are snake_case (e.g. auth_id, answer_url). All methods return a Promise.

Authentication

All API calls require your Auth ID and Auth Token, available in the Vobiz Console. Pass them when constructing the client - apiKey maps to your Auth ID and authToken to your Auth Token:

javascriptCopy
import { VobizClient } from "@vobiz/sdk";

const client = new VobizClient({
  apiKey: "YOUR_AUTH_ID",
  authToken: "YOUR_AUTH_TOKEN",
});

We recommend keeping credentials out of source by reading them from environment variables:

bashCopy
export VOBIZ_AUTH_ID=YOUR_AUTH_ID
export VOBIZ_AUTH_TOKEN=YOUR_AUTH_TOKEN

javascriptCopy
const client = new VobizClient({
  apiKey: process.env.VOBIZ_AUTH_ID,
  authToken: process.env.VOBIZ_AUTH_TOKEN,
});

Common operations

All snippets assume client and authId are initialized as shown above.

Live calls

javascriptCopy
// List in-progress calls
await client.liveCalls.listLiveCalls({ auth_id: authId });

// Fetch a single live call
await client.liveCalls.getLiveCall({ auth_id: authId, call_uuid: "CALL_UUID" });

// Hang up a live call
await client.liveCalls.hangupCall({ auth_id: authId, call_uuid: "CALL_UUID" });

In-call actions

javascriptCopy
await client.playAudio.call({ auth_id: authId, call_uuid: "CALL_UUID" });
await client.speakText.call({ auth_id: authId, call_uuid: "CALL_UUID" });
await client.dtmf.sendDtmf({ auth_id: authId, call_uuid: "CALL_UUID" });
await client.recordCalls.startRecording({ auth_id: authId, call_uuid: "CALL_UUID" });
await client.recordCalls.stopRecording({ auth_id: authId, call_uuid: "CALL_UUID" });

Call detail records (CDR)

javascriptCopy
const cdrs = await client.cdr.listCdrs({ auth_id: authId });
const match = await client.cdr.searchCdrs({ auth_id: authId });
const one = await client.cdr.getCdr({ auth_id: authId, call_id: "CALL_ID" });

Conferences

javascriptCopy
await client.conferences.listConferences({ auth_id: authId });
await client.conferenceMembers.muteMember({ auth_id: authId });
await client.conference.kickMember({ auth_id: authId });

Phone numbers and balance

javascriptCopy
await client.phoneNumbers.listNumbers({ auth_id: authId });
await client.phoneNumbers.purchaseFromInventory({ auth_id: authId });
await client.balance.getBalance({ auth_id: authId, currency: "INR" });

VobizXML

When a call is answered, Vobiz fetches your answer_url and expects VobizXML describing the call flow. The SDK bundles a vobizxml builder so you can construct it programmatically - it handles escaping and validation:

javascriptCopy
import { vobizxml } from "@vobiz/sdk";

app.post("/answer", (req, res) => {
  const r = new vobizxml.ResponseElement();

  const g = r.addGather({
    action: "https://yourserver.com/gather-result",
    inputType: "dtmf",
    numDigits: 1,
    executionTimeout: 10,
  });
  g.addSpeak("Welcome to Acme Corp. Press 1 for Sales.");

  r.addHangup();

  res.type("application/xml").send(r.toString());
});

ℹ️ Note: Gather uses inputType and executionTimeout (not timeout). The timeout attribute belongs to Dial/Number elements only.

Alternative: raw XML

You can also return hand-written VobizXML directly if you prefer:

javascriptCopy
app.post("/answer", (req, res) => {
  const xml = `
    <Response>
      <Speak voice="WOMAN" language="en-US">Thank you for calling.</Speak>
    </Response>
  `;
  res.type("application/xml").send(xml);
});

Resources

• GitHub repository
• Vobiz Console
• API documentation
• VobizXML reference