> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.voicebip.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.voicebip.com/_mcp/server.

# TypeScript / JavaScript SDK

> Install and use the @voicebip/sdk npm package.

The official Voicebip SDK for TypeScript and JavaScript, auto-generated from the OpenAPI spec via Fern. The package is not yet published to npm — this page previews what the API will look like when it ships.

## Installation (Coming Soon)

```bash
npm install @voicebip/sdk
```

## In the Meantime

Use the REST API directly with `fetch`:

```typescript
const BASE = "https://api.voicebip.com/v1";
const headers = {
  Authorization: "Bearer pk_live_xxx",
  "Content-Type": "application/json",
};

// Create an agent
const agent = await fetch(`${BASE}/agents`, {
  method: "POST",
  headers,
  body: JSON.stringify({ display_name: "Support", language: "en" }),
}).then((r) => r.json());

// Initiate a call
const call = await fetch(`${BASE}/calls`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    agent_id: agent.agent_id,
    from_number: "+2342013501000",
    to_number: "+2348031234567",
  }),
}).then((r) => r.json());

console.log("Call started:", call.call_id);
```

## Preview Usage

When `@voicebip/sdk` is published, the same flow will look like this:

## Quick Start

```typescript
import { Voicebip } from "@voicebip/sdk";

const client = new Voicebip({ apiKey: "pk_live_xxx" });

// Create an agent
const agent = await client.agents.create({
  displayName: "Customer Support",
  language: "en",
  systemPrompt: "You are a helpful customer support agent.",
});

// Provision a Nigerian number
const number = await client.numbers.provision({
  numberId: "num_xxx",
  agentId: agent.agentId,
  channels: ["voice"],
});

// Initiate an outbound call
const call = await client.calls.initiate({
  agentId: agent.agentId,
  fromNumber: number.e164,
  toNumber: "+2348031234567",
});

console.log(`Call started: ${call.callId}`);
```

## Error Handling

```typescript
import { Voicebip, VoicebipError } from "@voicebip/sdk";

try {
  await client.calls.initiate({ ... });
} catch (err) {
  if (err instanceof VoicebipError) {
    console.error(`${err.errorCode}: ${err.message}`);
    // Handle specific errors
    if (err.errorCode === "CALL_WINDOW_RESTRICTED") {
      console.log("Call outside permitted hours");
    }
  }
}
```

## Available Methods

| Module     | Method                                                             | Description        |
| ---------- | ------------------------------------------------------------------ | ------------------ |
| `agents`   | `create`, `list`, `get`, `update`, `delete`                        | Agent CRUD         |
| `numbers`  | `listAvailable`, `provision`, `get`, `release`                     | Number management  |
| `calls`    | `initiate`, `get`, `end`, `hold`, `resume`, `transfer`, `sendDtmf` | Voice calls        |
| `messages` | `send`                                                             | SMS and WhatsApp   |
| `apiKeys`  | `create`, `list`, `revoke`, `rotate`                               | API key management |
| `billing`  | `getUsage`, `getBalance`, `createCheckout`                         | Usage and payments |
| `dpa`      | `accept`, `getStatus`                                              | NDPR compliance    |
| `webhooks` | `test`                                                             | Webhook testing    |