Python SDK - Burki Voice AI Docs

The Burki Python SDK provides a simple, Pythonic interface to the Burki Voice AI API with support for both synchronous and asynchronous operations.

Installation

pip install burki

Requirements: Python 3.8+

Quick Start

from burki import BurkiClient

# Initialize the client
client = BurkiClient(api_key="your-api-key")

# List all assistants
assistants = client.assistants.list()
for assistant in assistants:
    print(f"{assistant.id}: {assistant.name}")

# Create a new assistant
assistant = client.assistants.create(
    name="Support Bot",
    description="Customer support assistant",
    llm_settings={
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "system_prompt": "You are a helpful customer support agent."
    },
    tts_settings={
        "provider": "elevenlabs",
        "voice_id": "rachel"
    }
)

Configuration

Basic Configuration

client = BurkiClient(api_key="your-api-key")

Custom Base URL

client = BurkiClient(
    api_key="your-api-key",
    base_url="https://custom.burki.dev"
)

Timeout Settings

client = BurkiClient(
    api_key="your-api-key",
    timeout=30.0  # seconds
)

Using Environment Variables

import os
from burki import BurkiClient

client = BurkiClient(api_key=os.environ["BURKI_API_KEY"])

Resources

List Assistants

assistants = client.assistants.list()

Get a Specific Assistant

assistant = client.assistants.get(assistant_id=123)

Create an Assistant

assistant = client.assistants.create(
    name="My Bot",
    description="A helpful assistant",
    llm_settings={
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "system_prompt": "You are helpful."
    },
    tts_settings={
        "provider": "elevenlabs",
        "voice_id": "rachel"
    }
)

Update an Assistant

assistant = client.assistants.update(
    assistant_id=123,
    name="Updated Bot",
    description="Updated description"
)

Delete an Assistant

client.assistants.delete(assistant_id=123)

Initiate an Outbound Call

response = client.calls.initiate(
    from_phone_number="+14155559999",
    to_phone_number="+14155551234",
    welcome_message="Hello! This is a follow-up call.",
    agenda="Discuss the recent proposal"
)

List Calls with Filters

calls = client.calls.list(
    status="completed",
    date_from="2026-01-01",
    limit=50
)

Get Call Details

call = client.calls.get(call_id=123)

Get Call Transcripts

transcripts = client.calls.get_transcripts(call_id=123)
for transcript in transcripts:
    print(f"{transcript.speaker}: {transcript.content}")

Get Call Recordings

recordings = client.calls.get_recordings(call_id=123)

Get Call Metrics

metrics = client.calls.get_metrics(call_id=123)
print(f"Duration: {metrics.duration}s")
print(f"Latency: {metrics.avg_latency}ms")

Terminate an Ongoing Call

client.calls.terminate(call_sid="CA123...")

Search Available Numbers

numbers = client.phone_numbers.search(
    country="US",
    area_code="415"
)

for number in numbers:
    print(f"{number.phone_number} - {number.locality}")

Purchase a Number

number = client.phone_numbers.purchase(
    phone_number="+14155551234",
    provider="twilio"
)

Assign to an Assistant

client.phone_numbers.assign(
    phone_number_id=123,
    assistant_id=456
)

Release a Number

client.phone_numbers.release(phone_number_id=123)

Upload a Document

document = client.documents.upload(
    assistant_id=123,
    file_path="knowledge.pdf"
)
print(f"Uploaded: {document.filename}")

List Documents

documents = client.documents.list(assistant_id=123)
for doc in documents:
    print(f"{doc.filename} - {doc.status}")

Check Processing Status

status = client.documents.get_status(document_id=456)
print(f"Status: {status.processing_status}")
print(f"Chunks: {status.chunk_count}")

Delete a Document

client.documents.delete(document_id=456)

List Tools

tools = client.tools.list()

Create an HTTP Tool

tool = client.tools.create(
    name="check_inventory",
    tool_type="http",
    description="Check product inventory",
    config={
        "method": "GET",
        "url": "https://api.example.com/inventory",
        "headers": {"Authorization": "Bearer {{API_KEY}}"}
    }
)

Assign Tool to Assistant

client.tools.assign(tool_id=123, assistant_id=456)

Discover AWS Lambda Functions

lambdas = client.tools.discover_lambda(region="us-east-1")
for fn in lambdas:
    print(f"{fn.function_name} - {fn.runtime}")

Send an SMS

message = client.sms.send(
    to="+14155551234",
    from_number="+14155559999",
    body="Hello from Burki!"
)
print(f"Message SID: {message.sid}")

Get Conversations

conversations = client.sms.get_conversations(assistant_id=123)
for conv in conversations:
    print(f"{conv.phone_number}: {conv.message_count} messages")

Create a Campaign

campaign = client.campaigns.create(
    name="Outreach Campaign",
    assistant_id=123,
    contacts=[
        {"phone_number": "+14155551234", "name": "John"},
        {"phone_number": "+14155555678", "name": "Jane"}
    ]
)

Start the Campaign

client.campaigns.start(campaign_id=456)

Pause the Campaign

client.campaigns.pause(campaign_id=456)

Get Campaign Progress

progress = client.campaigns.get(campaign_id=456)
print(f"Completed: {progress.completed_calls}/{progress.total_contacts}")
print(f"Success rate: {progress.success_rate}%")

Real-time Streaming

The Python SDK supports WebSocket streaming for real-time transcripts and campaign progress using async context managers.

Live Transcript Streaming

import asyncio
from burki import BurkiClient

async def stream_transcripts():
    client = BurkiClient(api_key="your-api-key")
    
    # Stream live transcripts during a call
    async with client.realtime.live_transcript(call_sid="CA123...") as stream:
        async for event in stream:
            if event.type == "transcript":
                print(f"[{event.speaker}]: {event.content}")
            elif event.type == "call_status":
                print(f"Call status: {event.status}")

asyncio.run(stream_transcripts())

Campaign Progress Streaming

import asyncio
from burki import BurkiClient

async def monitor_campaign():
    client = BurkiClient(api_key="your-api-key")
    
    # Stream campaign progress updates
    async with client.realtime.campaign_progress(campaign_id=123) as stream:
        async for update in stream:
            if update.type == "progress":
                print(f"Progress: {update.completed}/{update.total}")
            elif update.type == "contact_completed":
                print(f"Completed call to {update.phone_number}")
            elif update.type == "campaign_completed":
                print(f"Campaign finished! Success rate: {update.success_rate}%")

asyncio.run(monitor_campaign())

Async Usage

The SDK supports both synchronous and asynchronous usage. All resource methods have async counterparts with the _async suffix:

Synchronous

# Sync usage (blocking)
assistants = client.assistants.list()
assistant = client.assistants.get(assistant_id=123)

Asynchronous

import asyncio
from burki import BurkiClient

async def main():
    client = BurkiClient(api_key="your-api-key")
    
    # Async usage (non-blocking)
    assistants = await client.assistants.list_async()
    assistant = await client.assistants.get_async(assistant_id=123)
    
    # Concurrent requests
    results = await asyncio.gather(
        client.assistants.list_async(),
        client.calls.list_async(limit=10),
        client.phone_numbers.list_async()
    )

asyncio.run(main())

Error Handling

The SDK provides typed exceptions for different error scenarios:

from burki import BurkiClient
from burki.exceptions import (
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
    ServerError
)

client = BurkiClient(api_key="your-api-key")

try:
    assistant = client.assistants.get(assistant_id=999)
except AuthenticationError:
    print("Invalid API key")
except NotFoundError:
    print("Assistant not found")
except ValidationError as e:
    print(f"Validation error: {e.message}")
    print(f"Field errors: {e.errors}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ServerError:
    print("Server error occurred")

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)

Complete Example

Here’s a complete example that creates an assistant, assigns a phone number, uploads a knowledge document, and monitors incoming calls:

import asyncio
import os
from burki import BurkiClient
from burki.exceptions import NotFoundError

async def setup_voice_assistant():
    client = BurkiClient(api_key=os.environ["BURKI_API_KEY"])
    
    # 1. Create an assistant
    assistant = client.assistants.create(
        name="Customer Support",
        description="24/7 customer support assistant",
        llm_settings={
            "model": "gpt-4o-mini",
            "temperature": 0.7,
            "system_prompt": """You are a friendly customer support agent for Acme Inc.
            Help customers with their questions about products, orders, and returns.
            Be helpful, professional, and concise."""
        },
        tts_settings={
            "provider": "elevenlabs",
            "voice_id": "rachel"
        }
    )
    print(f"Created assistant: {assistant.name} (ID: {assistant.id})")
    
    # 2. Search and purchase a phone number
    numbers = client.phone_numbers.search(country="US", area_code="415")
    if numbers:
        purchased = client.phone_numbers.purchase(
            phone_number=numbers[0].phone_number,
            provider="twilio"
        )
        print(f"Purchased: {purchased.phone_number}")
        
        # Assign to assistant
        client.phone_numbers.assign(
            phone_number_id=purchased.id,
            assistant_id=assistant.id
        )
        print(f"Assigned to assistant")
    
    # 3. Upload knowledge base document
    document = client.documents.upload(
        assistant_id=assistant.id,
        file_path="company_faq.pdf"
    )
    print(f"Uploaded document: {document.filename}")
    
    # 4. Create an HTTP tool for order lookup
    tool = client.tools.create(
        name="lookup_order",
        tool_type="http",
        description="Look up customer order by order ID",
        config={
            "method": "GET",
            "url": "https://api.acme.com/orders/{{order_id}}",
            "headers": {"Authorization": "Bearer {{ACME_API_KEY}}"}
        }
    )
    client.tools.assign(tool_id=tool.id, assistant_id=assistant.id)
    print(f"Assigned tool: {tool.name}")
    
    # 5. Monitor live calls
    print("\nMonitoring for incoming calls...")
    calls = client.calls.list(assistant_id=assistant.id, status="in-progress")
    
    for call in calls:
        print(f"\nActive call: {call.call_sid}")
        async with client.realtime.live_transcript(call_sid=call.call_sid) as stream:
            async for event in stream:
                if event.type == "transcript":
                    print(f"[{event.speaker}]: {event.content}")
                elif event.type == "call_status" and event.status == "completed":
                    print("Call ended")
                    break

if __name__ == "__main__":
    asyncio.run(setup_voice_assistant())

Next Steps

JavaScript SDK

Check out the TypeScript-first JavaScript SDK

Real-time Streaming

Deep dive into WebSocket streaming

API Reference

Complete REST API documentation

RAG Documentation

Learn about knowledge base integration

​Installation

​Quick Start

​Configuration

​Basic Configuration

​Custom Base URL

​Timeout Settings

​Using Environment Variables

​Resources

​List Assistants

​Get a Specific Assistant

​Create an Assistant

​Update an Assistant

​Delete an Assistant

​Initiate an Outbound Call

​List Calls with Filters

​Get Call Details

​Get Call Transcripts

​Get Call Recordings

​Get Call Metrics

​Terminate an Ongoing Call

​Search Available Numbers

​Purchase a Number

​Assign to an Assistant

​Release a Number

​Upload a Document

​List Documents

​Check Processing Status

​Delete a Document

​List Tools

​Create an HTTP Tool

​Assign Tool to Assistant

​Discover AWS Lambda Functions

​Send an SMS

​Get Conversations

​Create a Campaign

​Start the Campaign

​Pause the Campaign

​Get Campaign Progress

​Real-time Streaming

​Live Transcript Streaming

​Campaign Progress Streaming

​Async Usage

​Synchronous

​Asynchronous

​Error Handling

​Exception Types

​Complete Example

​Next Steps

JavaScript SDK

Real-time Streaming

API Reference

RAG Documentation

Installation

Quick Start

Configuration

Basic Configuration

Custom Base URL

Timeout Settings

Using Environment Variables

Resources

List Assistants

Get a Specific Assistant

Create an Assistant

Update an Assistant

Delete an Assistant

Initiate an Outbound Call

List Calls with Filters

Get Call Details

Get Call Transcripts

Get Call Recordings

Get Call Metrics

Terminate an Ongoing Call

Search Available Numbers

Purchase a Number

Assign to an Assistant

Release a Number

Upload a Document

List Documents

Check Processing Status

Delete a Document

List Tools

Create an HTTP Tool

Assign Tool to Assistant

Discover AWS Lambda Functions

Send an SMS

Get Conversations

Create a Campaign

Start the Campaign

Pause the Campaign

Get Campaign Progress

Real-time Streaming

Live Transcript Streaming

Campaign Progress Streaming

Async Usage

Synchronous

Asynchronous

Error Handling

Exception Types

Complete Example

Next Steps