Skip to main content
The CallingBox TypeScript SDK wraps the same public /v1 API you see in the API Reference, but gives you a typed, async-native interface for managing numbers, creating calls, polling for results, and handling errors.

​
Install

If you’re using the published package: 
npm install callingbox
If you’re working from this monorepo locally: 
cd ts-sdk
npm install
npm run build
Then in your project, reference the local build or use npm link.

​
Authenticate

The SDK reads your API key from CALLINGBOX_API_KEY by default: 
export CALLINGBOX_API_KEY=sk_live_...
Then create a client instance: 
import { Callingbox } from "callingbox";

const client = new Callingbox();
const numbers = await client.numbers.list();
If you prefer to pass your key explicitly: 
import { Callingbox } from "callingbox";

const client = new Callingbox({ apiKey: "sk_live_..." });
const numbers = await client.numbers.list();

​
Run against a local backend

For local development, point the SDK at your local backend instead of production: 
export CALLINGBOX_BASE_URL=http://localhost:3002
export CALLINGBOX_API_KEY=sk_test_...
Or pass it directly: 
import { Callingbox } from "callingbox";

const client = new Callingbox({
  apiKey: "sk_test_...",
  baseUrl: "http://localhost:3002",
});

​
Manage phone numbers

Every outbound call needs a caller ID. The TypeScript SDK exposes the same public number APIs as the dashboard.

​
List your numbers

import { Callingbox } from "callingbox";

const client = new Callingbox();
const numbers = await client.numbers.list();
for (const number of numbers) {
  console.log(number.e164, number.status);
}

​
Search for available numbers

const available = await client.numbers.searchAvailable({
  countryCode: "US",
  areaCode: "415",
  numberType: "local",
  limit: 10,
});

for (const number of available) {
  console.log(number.phoneNumber, number.monthlyCostCents);
}

​
Purchase a number

const number = await client.numbers.purchase({
  phoneNumber: "+14155551234",
});
console.log(number.e164);

​
Create a call

Once your org has at least one active phone number, you can create outbound calls: 
import { Callingbox } from "callingbox";

const client = new Callingbox();

const call = await client.calls.create({
  to: "+15551234567",
  prompt: "Confirm dental appointment tomorrow at 2pm for Maria Lopez",
  context: { patient: "Maria Lopez", doctor: "Dr. Chen" },
  returns: { confirmed: "boolean", reschedule_to: "string" },
});

console.log(call.id, call.status);
If you do not pass a caller ID, CallingBox uses your organization’s oldest active purchased number.

​
Choose a specific caller ID

const call = await client.calls.create({
  to: "+15551234567",
  prompt: "Confirm appointment tomorrow 2pm",
  fromNumber: "+15557654321",
});
The SDK sends that to the API as from_number. The value must be an active number owned by your organization.

​
Poll for completion

Call creation is immediate, but the conversation and result extraction happen asynchronously. Poll the call until it reaches a terminal status: 
import { Callingbox, TERMINAL_STATUSES } from "callingbox";

const client = new Callingbox();

let call = await client.calls.create({
  to: "+15551234567",
  prompt: "Confirm appointment tomorrow 2pm",
  returns: { confirmed: "boolean" },
});

while (!TERMINAL_STATUSES.has(call.status)) {
  await new Promise((r) => setTimeout(r, 2000));
  call = await client.calls.get(call.id);
}

console.log(call.status);
console.log(call.result);
Terminal statuses are:
  • completed
  • no_answer
  • busy
  • canceled
  • failed

​
List and retrieve calls

// List recent calls
const calls = await client.calls.list();

// Get a single call by ID
const call = await client.calls.get("CALL_ID");
console.log(call.status);
console.log(call.result);

​
Error handling

The SDK throws typed exceptions based on the API response: 
import {
  Callingbox,
  APIError,
  AuthenticationError,
  BadRequestError,
  NotFoundError,
} from "callingbox";

const client = new Callingbox();

try {
  await client.calls.create({ to: "+15551234567" });
} catch (error) {
  if (error instanceof BadRequestError) {
    console.log(`Invalid request: ${error.message}`);
  } else if (error instanceof AuthenticationError) {
    console.log("Check your API key");
  } else if (error instanceof NotFoundError) {
    console.log("Resource not found");
  } else if (error instanceof APIError) {
    console.log(`API error: ${error.message}`);
  }
}

​
Full runnable example

For a complete example that:
  • checks whether your org already has a number
  • purchases one if needed
  • places a call
  • polls until the call finishes
  • prints the result
see the example script in the repo: You can run it with: 
export CALLINGBOX_API_KEY=sk_live_...
cd ts-sdk
npm run example -- +15551234567
If you’re running your backend locally: 
export CALLINGBOX_BASE_URL=http://localhost:3002
export CALLINGBOX_API_KEY=sk_test_...
cd ts-sdk
npm run example -- +15551234567

​
Webhooks

Manage endpoints and verify signatures with client.webhooks and the static Webhooks.constructEvent: 
import { Callingbox, Webhooks } from "callingbox";

const cb = new Callingbox({ apiKey: process.env.CALLINGBOX_API_KEY });

// Create an endpoint (signingSecret is returned once)
const endpoint = await cb.webhooks.createEndpoint({
  url: "https://your-server.com/callingbox-webhook",
  description: "Production CRM sync",
  enabledEvents: ["call.completed", "call.failed"],
});
console.log(endpoint.signingSecret); // whsec_... — store securely

// Verify an incoming webhook (raw body required, not parsed JSON!)
app.post(
  "/callingbox-webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const event = Webhooks.constructEvent(
      req.body,                                 // Buffer
      req.headers["callingbox-signature"] as string,
      process.env.CALLINGBOX_WEBHOOK_SECRET!,
    );
    // event.type, event.data.call are now trustworthy
    res.sendStatus(200);
  },
);

// Replay a failed delivery
await cb.webhooks.redeliver("9c1d9f9e-21a1-4f6d-8fce-bf4a4b8a9e3f");
See Webhooks for the full integration guide.

​
Next steps

SDK overview

Compare the Python SDK, TypeScript SDK, CLI, and raw HTTP.

API basics

See the underlying /v1 endpoints the SDK wraps.

Call object

Understand every field returned by create, list, and get.

Delivery

Polling vs webhooks for receiving results.