Python SDK Reference

Installation

pip install voicecraft-ai

Quick Setup

from voicecraft import VoiceCraftClient

# Initialize with your API key
client = VoiceCraftClient(api_key="vc_your_api_key")

# Or use environment variable VOICECRAFT_API_KEY
client = VoiceCraftClient()

# Custom base URL (for self-hosted deployments)
client = VoiceCraftClient(
    api_key="vc_your_api_key",
    base_url="https://your-instance.example.com",
)

Available Modules

The SDK is organized into modules accessible via the client instance:

Error Handling

The SDK raises typed exceptions for common error scenarios. Always wrap API calls in try/except blocks for production code:

from voicecraft import VoiceCraftClient
from voicecraft.exceptions import (
    AuthenticationError,
    RateLimitError,
    NotFoundError,
    ValidationError,
    VoiceCraftError,
)

client = VoiceCraftClient(api_key="vc_your_api_key")

try:
    agent = client.agents.get("agent_abc123")
except AuthenticationError:
    print("Invalid or expired API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except NotFoundError:
    print("Agent not found")
except ValidationError as e:
    print(f"Invalid request: {e.errors}")
except VoiceCraftError as e:
    print(f"API error {e.status_code}: {e.message}")

Agents Module

Manage voice agents with custom prompts, language settings, and voice configurations.

# List all agents
agents = client.agents.list(page=1, limit=20)

# Get a specific agent
agent = client.agents.get("agent_abc123")

# Create an agent
agent = client.agents.create(
    name="Support Agent",
    system_prompt="You are a customer support agent...",
    language="hi-IN",
    voice_id="meera-hindi",
    max_call_duration=600,
    transfer_number="+911234567890",
)

# Update an agent
agent = client.agents.update("agent_abc123", name="Updated Agent")

# Delete an agent
client.agents.delete("agent_abc123")

# Test an agent
result = client.agents.test(
    agent_id="agent_abc123",
    test_message="Hello, I need help with my order",
)

Calls Module

Initiate outbound calls, retrieve call details, and access recordings.

# Initiate a call
call = client.calls.create(
    agent_id="agent_abc123",
    to_number="+919876543210",
    from_number="+911234567890",
    metadata={"campaign": "welcome"},
)

# List recent calls
calls = client.calls.list(page=1, limit=50, status="completed")

# Get call details
call = client.calls.get("call_xyz789")

# Get call recording URL
recording = client.calls.get_recording("call_xyz789")

# Get call transcript
transcript = client.calls.get_transcript("call_xyz789")

Campaigns Module

Run bulk calling campaigns with contact lists, scheduling, and progress tracking.

# Create a campaign
campaign = client.campaigns.create(
    name="Product Launch",
    agent_id="agent_abc123",
    contacts=[
        {"phone": "+919876543210", "name": "Rahul"},
        {"phone": "+919876543211", "name": "Priya"},
    ],
    schedule_at="2025-03-01T10:00:00+05:30",
    max_concurrent_calls=5,
)

# List campaigns
campaigns = client.campaigns.list(status="active")

# Get campaign progress
progress = client.campaigns.get_progress("campaign_def456")

# Pause / resume / cancel
client.campaigns.pause("campaign_def456")
client.campaigns.resume("campaign_def456")
client.campaigns.cancel("campaign_def456")

Knowledge Base Module

Upload documents to power RAG (Retrieval-Augmented Generation) for your agents.

# Upload a document
doc = client.knowledge_base.upload(
    file_path="/path/to/product-catalog.pdf",
    name="Product Catalog 2025",
)

# List documents
docs = client.knowledge_base.list()

# Attach a document to an agent
client.knowledge_base.attach(
    document_id="doc_abc123",
    agent_id="agent_abc123",
)

# Delete a document
client.knowledge_base.delete("doc_abc123")

Phone Numbers Module

Purchase and manage DID (Direct Inward Dialing) numbers for your voice agents.

# List available numbers
available = client.phone_numbers.search(
    country="IN",
    type="local",
    area_code="080",
)

# Purchase a number
number = client.phone_numbers.purchase(
    number="+918012345678",
    agent_id="agent_abc123",
)

# List your numbers
numbers = client.phone_numbers.list()

# Release a number
client.phone_numbers.release("pn_abc123")

Analytics Module

Retrieve usage metrics, call statistics, and performance reports.

# Get usage summary
usage = client.analytics.usage(
    start_date="2025-01-01",
    end_date="2025-01-31",
)

# Get call statistics
stats = client.analytics.call_stats(
    agent_id="agent_abc123",
    period="weekly",
)

# Export report
report = client.analytics.export(
    format="csv",
    start_date="2025-01-01",
    end_date="2025-01-31",
)

WhatsApp Module

Send and manage WhatsApp messages through your voice agents.

# Send a WhatsApp message
message = client.whatsapp.send(
    to="+919876543210",
    template="order_confirmation",
    parameters={"order_id": "ORD-12345", "amount": "₹1,299"},
)

# List conversations
conversations = client.whatsapp.list_conversations(status="active")

# Get conversation messages
messages = client.whatsapp.get_messages(conversation_id="conv_abc123")

Providers Module

Configure telephony (SIP trunks) and LLM provider connections.

# List configured providers
providers = client.providers.list()

# Add a telephony provider
provider = client.providers.create(
    type="sip",
    name="My SIP Trunk",
    config={
        "host": "sip.provider.in",
        "username": "user",
        "password": "pass",
    },
)

# Test provider connectivity
result = client.providers.test("provider_abc123")

# Delete a provider
client.providers.delete("provider_abc123")