Burki JavaScript/TypeScript SDK

Official JavaScript/TypeScript SDK for the Burki Voice AI Platform.

Installation

npm install @burki.dev/sdk

Quick Start

import { BurkiClient } from '@burki/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'
  }
});

Features

Assistants

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

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

// Get a specific assistant
const assistant = await client.assistants.get(123);

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

// Create an assistant
const assistant = await client.assistants.create({
  name: 'My Bot',
  llmSettings: { model: 'gpt-4o-mini' }
});

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

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

// Delete an assistant
await client.assistants.delete(123);

// 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();

Calls

// 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 with filters
const calls = await client.calls.list({
  status: 'completed',
  dateFrom: '2026-01-01',
  limit: 50
});

// Get call details
const call = await client.calls.get(123);

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

// Update call metadata
await client.calls.updateMetadata(123, { customField: 'value' });

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

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

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

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

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

// Get call metrics
const metrics = await client.calls.getMetrics(123);

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

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

// Terminate an ongoing call
await client.calls.terminate('CA123...');

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

// Get 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' });

Phone Numbers

// 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 to an assistant
await client.phoneNumbers.assign(123, { assistantId: 456 });

// Unassign from assistant
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');

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

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

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

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

Documents (RAG)

// 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);

// Check processing status
const status = await client.documents.getStatus(456);

// Reprocess a document
await client.documents.reprocess(456);

// Delete a document
await client.documents.delete(456);

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'
  }
});

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

// Delete a tool
await client.tools.delete(123);

// 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');

SMS

// 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();

// 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 (voice + SMS unified session)
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' });

Campaigns

// 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);

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

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

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

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

// Get campaign progress
const progress = await client.campaigns.getProgress(123);

// 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 (WebSocket)

// Stream live transcripts during a call
const stream = client.realtime.liveTranscript('CA123...');
await stream.connect();

for await (const event of stream) {
  if (event.type === 'transcript') {
    console.log(`[${event.speaker}]: ${event.content}`);
  } else if (event.type === 'call_status') {
    console.log(`Call status: ${event.status}`);
  }
}

stream.disconnect();

// Stream campaign progress updates
const stream = client.realtime.campaignProgress(123);
await stream.connect();

for await (const event of stream) {
  if (event.type === 'progress') {
    console.log(`Progress: ${event.completedContacts}/${event.totalContacts}`);
  } else if (event.type === 'campaign_completed') {
    console.log(`Campaign completed! Success rate: ${event.successRate}%`);
  }
}

Configuration

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
});

Error Handling

import {
  BurkiClient,
  AuthenticationError,
  NotFoundError,
  ValidationError,
  RateLimitError,
  ServerError,
  WebSocketError
} from '@burki/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}`);
  } 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');
  }
}

TypeScript Support

This SDK is written in TypeScript and provides full type definitions for all models and methods.

import type {
  Assistant,
  AssistantCreateParams,
  Call,
  CallListParams,
  Campaign,
  PhoneNumber,
  Tool,
  // ... and more
} from '@burki/sdk';

License

MIT License