JavaScript/TypeScript SDK - Burki Voice AI Docs

The Burki JavaScript SDK is written in TypeScript and provides full type definitions for all models and methods. It works seamlessly in Node.js and browser environments.

Installation

npm install @burki.dev/sdk

Or with yarn:

yarn add @burki.dev/sdk

Requirements: Node.js 18+ or modern browser

Quick Start

import { BurkiClient } from '@burki.dev/sdk';

// Initialize the client
const client = new BurkiClient({ apiKey: 'your-api-key' });

// List all assistants
const assistants = await client.assistants.list();
for (const assistant of assistants) {
  console.log(`${assistant.id}: ${assistant.name}`);
}

// Create a new assistant
const assistant = await client.assistants.create({
  name: 'Support Bot',
  description: 'Customer support assistant',
  llmSettings: {
    model: 'gpt-4o-mini',
    temperature: 0.7,
    systemPrompt: 'You are a helpful customer support agent.'
  },
  ttsSettings: {
    provider: 'elevenlabs',
    voiceId: 'rachel'
  }
});

Configuration

Basic Configuration

const client = new BurkiClient({ apiKey: 'your-api-key' });

Custom Base URL

const client = new BurkiClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://custom.burki.dev'
});

Timeout Settings

const client = new BurkiClient({
  apiKey: 'your-api-key',
  timeout: 60000 // 60 seconds in milliseconds
});

Using Environment Variables

const client = new BurkiClient({ 
  apiKey: process.env.BURKI_API_KEY! 
});

Resources

The JavaScript SDK provides the most comprehensive assistant management API.

List Assistants

// Basic list
const assistants = await client.assistants.list();

// With options
const activeAssistants = await client.assistants.list({
  activeOnly: true,
  includeStats: true,
  limit: 50
});

Get an Assistant

// By ID
const assistant = await client.assistants.get(123);

// By phone number
const assistant = await client.assistants.getByPhone('+14155551234');

Create an Assistant

const assistant = await client.assistants.create({
  name: 'My Bot',
  description: 'A helpful assistant',
  llmSettings: { 
    model: 'gpt-4o-mini',
    temperature: 0.7,
    systemPrompt: 'You are helpful.'
  },
  ttsSettings: {
    provider: 'elevenlabs',
    voiceId: 'rachel'
  }
});

Update an Assistant

const updated = await client.assistants.update(123, { 
  name: 'Updated Bot',
  description: 'Updated description'
});

Quick Status Update

// Activate
await client.assistants.updateStatus(123, true);

// Deactivate
await client.assistants.updateStatus(123, false);

Delete an Assistant

await client.assistants.delete(123);

Additional Methods

// Get assistant count
const count = await client.assistants.getCount(true); // Active only

// Export assistants
const csvBlob = await client.assistants.export({ format: 'csv' });

// Get cloned voices
const voices = await client.assistants.getClonedVoices({ 
  provider: 'elevenlabs' 
});

// Get available LLM providers
const providers = await client.assistants.getProviders();

// Get organization info
const orgInfo = await client.assistants.getOrganizationInfo();

Comprehensive call management with analytics and data export.

Initiate an Outbound Call

const response = await client.calls.initiate({
  fromPhoneNumber: '+14155559999',
  toPhoneNumber: '+14155551234',
  welcomeMessage: 'Hello! This is a follow-up call.',
  agenda: 'Discuss the recent proposal'
});

List Calls

const calls = await client.calls.list({
  status: 'completed',
  dateFrom: '2026-01-01',
  limit: 50
});

Get Call Details

// By ID
const call = await client.calls.get(123);

// By SID
const call = await client.calls.getBySid('CA123...');

Update Call Metadata

await client.calls.updateMetadata(123, { 
  customField: 'value',
  priority: 'high'
});

Get Transcripts

// By call ID
const transcripts = await client.calls.getTranscripts(123);

// By SID
const transcripts = await client.calls.getTranscriptsBySid('CA123...');

// Export transcripts
const txtBlob = await client.calls.exportTranscripts(123, { format: 'txt' });

Get Recordings

const recordings = await client.calls.getRecordings(123);

// Get direct recording URL
const url = client.calls.getRecordingUrl(123, 456);

Get Call Metrics

const metrics = await client.calls.getMetrics(123);
console.log(`Duration: ${metrics.duration}s`);
console.log(`Avg latency: ${metrics.avgLatency}ms`);

Get Chat Messages

// Get the LLM conversation
const messages = await client.calls.getMessages(123);

Get Webhook Logs

const logs = await client.calls.getWebhookLogs(123);

Terminate a Call

await client.calls.terminate('CA123...');

Analytics & Stats

// Get analytics (1d, 7d, 30d, 90d)
const analytics = await client.calls.getAnalytics('7d');

// Get basic stats
const stats = await client.calls.getStats();

// Search calls
const results = await client.calls.search('customer name');

// Export calls
const csvBlob = await client.calls.export({ 
  format: 'csv', 
  status: 'completed' 
});

Full phone number lifecycle management including webhooks.

List Phone Numbers

const numbers = await client.phoneNumbers.list();

Search Available Numbers

const available = await client.phoneNumbers.search({
  provider: 'twilio',
  countryCode: 'US',
  areaCode: '415'
});

Purchase a Number

const result = await client.phoneNumbers.purchase({
  phoneNumber: '+14155551234',
  provider: 'twilio',
  friendlyName: 'Support Line'
});

Release a Number

await client.phoneNumbers.release('+14155551234');

Assign/Unassign

// Assign to assistant
await client.phoneNumbers.assign(123, { assistantId: 456 });

// Unassign
await client.phoneNumbers.unassign(123);

Get Available Countries

const countries = await client.phoneNumbers.getCountries('telnyx');

Diagnose Connection (Telnyx)

const diagnosis = await client.phoneNumbers.diagnose('+14155551234');

Webhook Management

// Get webhooks
const webhooks = await client.phoneNumbers.getWebhooks('+14155551234');

// Update webhooks
await client.phoneNumbers.updateWebhooks({
  phoneNumber: '+14155551234',
  voiceWebhookUrl: 'https://example.com/voice',
  statusCallbackUrl: 'https://example.com/status'
});

Verified Caller IDs

// Sync verified caller IDs
await client.phoneNumbers.syncVerifiedCallerIds();

// Add a verified caller ID
await client.phoneNumbers.addVerifiedCallerId({
  phoneNumber: '+14155551234',
  friendlyName: 'My Phone'
});

Upload and manage knowledge base documents.

Upload a Document (Browser)

const file = new File(['content'], 'knowledge.pdf', { 
  type: 'application/pdf' 
});
const document = await client.documents.upload(123, file, 'knowledge.pdf');

Upload from URL

const document = await client.documents.uploadFromUrl({
  assistantId: 123,
  url: 'https://example.com/document.pdf'
});

List Documents

const documents = await client.documents.list(123);
for (const doc of documents) {
  console.log(`${doc.filename}: ${doc.status}`);
}

Check Processing Status

const status = await client.documents.getStatus(456);
console.log(`Status: ${status.processingStatus}`);
console.log(`Chunks: ${status.chunkCount}`);

Reprocess a Document

await client.documents.reprocess(456);

Delete a Document

await client.documents.delete(456);

Create, manage, and assign custom tools.

List Tools

const tools = await client.tools.list();

Get a Tool

const tool = await client.tools.get(123);

Create an HTTP Tool

const tool = await client.tools.create({
  name: 'check_inventory',
  toolType: 'http',
  description: 'Check product inventory',
  httpConfig: {
    method: 'GET',
    url: 'https://api.example.com/inventory',
    headers: {
      'Authorization': 'Bearer {{API_KEY}}'
    }
  }
});

Update a Tool

await client.tools.update(123, { 
  description: 'Updated description' 
});

Delete a Tool

await client.tools.delete(123);

Assign/Unassign Tools

// Assign tool to assistant
await client.tools.assign(123, 456);

// Unassign tool from assistant
await client.tools.unassign(123, 456);

Discover AWS Lambda Functions

const lambdas = await client.tools.discoverLambda('us-east-1');
for (const fn of lambdas) {
  console.log(`${fn.functionName} (${fn.runtime})`);
}

Complete SMS management with queue support.

Send an SMS

const response = await client.sms.send({
  fromPhoneNumber: '+14155559999',
  toPhoneNumber: '+14155551234',
  message: 'Hello from Burki!',
  queue: true // Use rate-limited queue
});

Get Message Status

const status = await client.sms.getStatus('msg_123');

Cancel a Queued Message

await client.sms.cancel('msg_123');

Get Queue Statistics

const stats = await client.sms.getQueueStats();
console.log(`Pending: ${stats.pending}`);
console.log(`Sent: ${stats.sent}`);

Conversation Management

// List conversations
const conversations = await client.sms.listConversations({
  assistantId: 123,
  status: 'active'
});

// Get a conversation
const conversation = await client.sms.getConversation('conv_123');

// Get messages in a conversation
const messages = await client.sms.getMessages('conv_123');

// Get related conversations (unified voice + SMS)
const related = await client.sms.getRelatedConversations('conv_123');

// Delete/archive a conversation
await client.sms.deleteConversation('conv_123');

// Export a conversation
const txtBlob = await client.sms.exportConversation('conv_123', { 
  format: 'txt' 
});

Full campaign lifecycle management.

List Campaigns

const campaigns = await client.campaigns.list({ status: 'running' });

Get a Campaign

const campaign = await client.campaigns.get(123);

Create a Campaign

const campaign = await client.campaigns.create({
  name: 'Outreach Campaign',
  assistantId: 123,
  contacts: [
    { 
      phoneNumber: '+14155551234', 
      name: 'John',
      variables: { company: 'Acme' }
    },
    { 
      phoneNumber: '+14155555678', 
      name: 'Jane' 
    }
  ],
  settings: {
    maxConcurrentCalls: 5,
    callsPerMinute: 10
  }
});

Update a Campaign

await client.campaigns.update(123, { name: 'Updated Campaign' });

Delete a Campaign

await client.campaigns.delete(123);

Campaign Control

// Start
await client.campaigns.start(123);

// Pause
await client.campaigns.pause(123);

// Resume
await client.campaigns.resume(123);

// Cancel
await client.campaigns.cancel(123);

Get Progress

const progress = await client.campaigns.getProgress(123);
console.log(`Completed: ${progress.completedContacts}/${progress.totalContacts}`);
console.log(`Success rate: ${progress.successRate}%`);

Contact Management

// Get contacts
const contacts = await client.campaigns.getContacts(123, { 
  status: 'pending' 
});

// Add contacts
await client.campaigns.addContacts(123, [
  { phoneNumber: '+14155559999', name: 'New Contact' }
]);

Real-time Streaming

The JavaScript SDK uses async iterators for WebSocket streaming.

Live Transcript Streaming

const stream = client.realtime.liveTranscript('CA123...');
await stream.connect();

for await (const event of stream) {
  switch (event.type) {
    case 'transcript':
      console.log(`[${event.speaker}]: ${event.content}`);
      break;
    case 'call_status':
      console.log(`Call status: ${event.status}`);
      if (event.status === 'completed') {
        stream.disconnect();
      }
      break;
    case 'error':
      console.error(`Error: ${event.message}`);
      break;
  }
}

Campaign Progress Streaming

const stream = client.realtime.campaignProgress(123);
await stream.connect();

for await (const event of stream) {
  switch (event.type) {
    case 'progress':
      console.log(`Progress: ${event.completedContacts}/${event.totalContacts}`);
      break;
    case 'contact_completed':
      console.log(`Completed call to ${event.phoneNumber}`);
      break;
    case 'campaign_completed':
      console.log(`Campaign finished! Success rate: ${event.successRate}%`);
      stream.disconnect();
      break;
  }
}

Connection Management

const stream = client.realtime.liveTranscript('CA123...');

// Connect
await stream.connect();

// Send ping to keep connection alive
stream.sendPing();

// Request current status
stream.requestStatus();

// Disconnect when done
stream.disconnect();

TypeScript Support

The SDK provides full type definitions for all models and methods:

import type {
  Assistant,
  AssistantCreateParams,
  AssistantUpdateParams,
  Call,
  CallListParams,
  Campaign,
  CampaignCreateParams,
  PhoneNumber,
  PhoneNumberSearchParams,
  Tool,
  ToolCreateParams,
  Document,
  TranscriptEvent,
  CallStatusEvent,
  CampaignProgressEvent
} from '@burki.dev/sdk';

// Use types for better IDE support
const createParams: AssistantCreateParams = {
  name: 'My Bot',
  llmSettings: { model: 'gpt-4o-mini' }
};

const assistant: Assistant = await client.assistants.create(createParams);

Error Handling

The SDK provides typed exceptions for different error scenarios:

import {
  BurkiClient,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
  WebSocketError
} from '@burki.dev/sdk';

const client = new BurkiClient({ apiKey: 'your-api-key' });

try {
  const assistant = await client.assistants.get(999);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Assistant not found');
  } else if (error instanceof ValidationError) {
    console.error(`Validation error: ${error.message}`);
    console.error(`Field errors: ${JSON.stringify(error.errors)}`);
  } else if (error instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${error.retryAfter} seconds`);
  } else if (error instanceof ServerError) {
    console.error('Server error occurred');
  } else if (error instanceof WebSocketError) {
    console.error('WebSocket connection error');
  }
}

Exception Types

Exception	Description
`AuthenticationError`	Invalid or missing API key
`NotFoundError`	Resource not found (404)
`ValidationError`	Invalid request parameters (400)
`RateLimitError`	Too many requests (429)
`ServerError`	Internal server error (5xx)
`WebSocketError`	WebSocket connection error

Complete Example

Here’s a complete example demonstrating the SDK’s capabilities:

import { BurkiClient, NotFoundError } from '@burki.dev/sdk';

async function main() {
  const client = new BurkiClient({ 
    apiKey: process.env.BURKI_API_KEY! 
  });

  // 1. Create an assistant
  const assistant = await client.assistants.create({
    name: 'Sales Assistant',
    description: 'Outbound sales assistant',
    llmSettings: {
      model: 'gpt-4o-mini',
      temperature: 0.8,
      systemPrompt: `You are a friendly sales representative for Acme Inc.
        Your goal is to schedule product demos with interested prospects.
        Be personable, handle objections gracefully, and focus on value.`
    },
    ttsSettings: {
      provider: 'elevenlabs',
      voiceId: 'adam'
    }
  });
  console.log(`Created assistant: ${assistant.name}`);

  // 2. Purchase and assign a phone number
  const available = await client.phoneNumbers.search({
    provider: 'twilio',
    countryCode: 'US',
    areaCode: '415'
  });

  if (available.length > 0) {
    const purchased = await client.phoneNumbers.purchase({
      phoneNumber: available[0].phoneNumber,
      provider: 'twilio',
      friendlyName: 'Sales Line'
    });
    
    await client.phoneNumbers.assign(purchased.id, { 
      assistantId: assistant.id 
    });
    console.log(`Assigned ${purchased.phoneNumber} to assistant`);
  }

  // 3. Upload product documentation
  const doc = await client.documents.uploadFromUrl({
    assistantId: assistant.id,
    url: 'https://acme.com/product-guide.pdf'
  });
  console.log(`Uploaded document: ${doc.filename}`);

  // 4. Create an outbound campaign
  const campaign = await client.campaigns.create({
    name: 'Q1 Outreach',
    assistantId: assistant.id,
    contacts: [
      { phoneNumber: '+14155551234', name: 'John Smith', variables: { company: 'TechCorp' }},
      { phoneNumber: '+14155555678', name: 'Jane Doe', variables: { company: 'StartupXYZ' }},
    ],
    settings: {
      maxConcurrentCalls: 2,
      callsPerMinute: 5
    }
  });
  console.log(`Created campaign: ${campaign.name}`);

  // 5. Start campaign and monitor progress
  await client.campaigns.start(campaign.id);
  console.log('Campaign started!');

  const stream = client.realtime.campaignProgress(campaign.id);
  await stream.connect();

  for await (const event of stream) {
    if (event.type === 'progress') {
      console.log(`Progress: ${event.completedContacts}/${event.totalContacts}`);
    } else if (event.type === 'contact_completed') {
      console.log(`Completed: ${event.phoneNumber} - ${event.outcome}`);
    } else if (event.type === 'campaign_completed') {
      console.log(`\nCampaign finished!`);
      console.log(`Success rate: ${event.successRate}%`);
      console.log(`Total calls: ${event.totalContacts}`);
      stream.disconnect();
      break;
    }
  }

  // 6. Export results
  const exportData = await client.calls.export({
    format: 'csv',
    assistantId: assistant.id
  });
  console.log('Exported call data');
}

main().catch(console.error);

Next Steps

Python SDK

Check out the Python SDK

Go SDK

Idiomatic Go SDK with channels

Real-time Streaming

Deep dive into WebSocket streaming

API Reference

Complete REST API documentation

​Installation

​Quick Start

​Configuration

​Basic Configuration

​Custom Base URL

​Timeout Settings

​Using Environment Variables

​Resources

​List Assistants

​Get an Assistant

​Create an Assistant

​Update an Assistant

​Quick Status Update

​Delete an Assistant

​Additional Methods

​Initiate an Outbound Call

​List Calls

​Get Call Details

​Update Call Metadata

​Get Transcripts

​Get Recordings

​Get Call Metrics

​Get Chat Messages

​Get Webhook Logs

​Terminate a Call

​Analytics & Stats

​List Phone Numbers

​Search Available Numbers

​Purchase a Number

​Release a Number

​Assign/Unassign

​Get Available Countries

​Diagnose Connection (Telnyx)

​Webhook Management

​Verified Caller IDs

​Upload a Document (Browser)

​Upload from URL

​List Documents

​Check Processing Status

​Reprocess a Document

​Delete a Document

​List Tools

​Get a Tool

​Create an HTTP Tool

​Update a Tool

​Delete a Tool

​Assign/Unassign Tools

​Discover AWS Lambda Functions

​Send an SMS

​Get Message Status

​Cancel a Queued Message

​Get Queue Statistics

​Conversation Management

​List Campaigns

​Get a Campaign

​Create a Campaign

​Update a Campaign

​Delete a Campaign

​Campaign Control

​Get Progress

​Contact Management

​Real-time Streaming

​Live Transcript Streaming

​Campaign Progress Streaming

​Connection Management

​TypeScript Support

​Error Handling

​Exception Types

​Complete Example

​Next Steps

Python SDK

Go SDK

Real-time Streaming

API Reference

Installation

Quick Start

Configuration

Basic Configuration

Custom Base URL

Timeout Settings

Using Environment Variables

Resources

List Assistants

Get an Assistant

Create an Assistant

Update an Assistant

Quick Status Update

Delete an Assistant

Additional Methods

Initiate an Outbound Call

List Calls

Get Call Details

Update Call Metadata

Get Transcripts

Get Recordings

Get Call Metrics

Get Chat Messages

Get Webhook Logs

Terminate a Call

Analytics & Stats

List Phone Numbers

Search Available Numbers

Purchase a Number

Release a Number

Assign/Unassign

Get Available Countries

Diagnose Connection (Telnyx)

Webhook Management

Verified Caller IDs

Upload a Document (Browser)

Upload from URL

List Documents

Check Processing Status

Reprocess a Document

Delete a Document

List Tools

Get a Tool

Create an HTTP Tool

Update a Tool

Delete a Tool

Assign/Unassign Tools

Discover AWS Lambda Functions

Send an SMS

Get Message Status

Cancel a Queued Message

Get Queue Statistics

Conversation Management

List Campaigns

Get a Campaign

Create a Campaign

Update a Campaign

Delete a Campaign

Campaign Control

Get Progress

Contact Management

Real-time Streaming

Live Transcript Streaming

Campaign Progress Streaming

Connection Management

TypeScript Support

Error Handling

Exception Types

Complete Example

Next Steps