vaani-sdk-webrtc 0.1.0

Official Python WebRTC SDK for Vaani Voice AI

Vaani WebRTC Python SDK

Python client for creating and managing Vaani WebRTC voice sessions, plus related calls and agents APIs.

The SDK handles Vaani API authentication, HTTP errors, timeouts, and response models. Your frontend still joins the WebRTC room with the LiveKit client SDK using credentials returned by sessions.connect().

Installation

pip install vaani-sdk-webrtc

WebRTC Flow

The programmatic WebRTC flow is:

1. Create a session with client.sessions.create(...).
2. Send session.session_url to a user, or keep session.session_token for your own UI flow.
3. Call client.sessions.connect(session.session_token) when the user is ready to join.
4. Pass creds.lk_url and creds.lk_token to the LiveKit client SDK in your browser or mobile app.
5. Optionally watch session events with client.sessions.ws_url(...).
6. Check status with client.sessions.get(...) or end the session with client.sessions.disconnect(...).

Sync Quickstart

from vaani import VaaniClient

with VaaniClient(
    api_key="your_api_key",
    base_url="https://api.vaanivoice.ai",
    timeout=30,
) as client:
    session = client.sessions.create(
        agent_id="agent-uuid-or-name",
        ui_type="widget",
        grace_period=60,
        session_ttl=1800,
        initial_message="User is asking about order #1234",
        metadata={
            "user_id": "user_123",
            "ticket_id": "T-1234",
        },
    )

    creds = client.sessions.connect(session.session_token)

print(session.session_url)
print(creds.lk_url)
print(creds.lk_token)
print(creds.room_name)

Use session.session_url when you want Vaani's embeddable/shareable session URL. Use creds.lk_url and creds.lk_token when you are building your own frontend and joining LiveKit directly.

Async Quickstart

from vaani import AsyncVaaniClient

async with AsyncVaaniClient(
    api_key="your_api_key",
    base_url="https://api.vaanivoice.ai",
    timeout=30,
) as client:
    session = await client.sessions.create(agent_id="agent-uuid-or-name")
    creds = await client.sessions.connect(session.session_token)
    status = await client.sessions.get(session.session_token)

Session Events

The SDK can build the WebSocket URL for server-side event listeners:

import asyncio
import json

import websockets
from vaani import VaaniClient

client = VaaniClient(api_key="your_api_key")

async def listen(session_token: str) -> None:
    url = client.sessions.ws_url(session_token)
    async with websockets.connect(url) as ws:
        async for message in ws:
            event = json.loads(message)
            if event["event"] == "agent_ready":
                print("Agent is ready")
            elif event["event"] == "agent_timeout":
                print(event.get("reason"))
            elif event["event"] == "session_ended":
                print(event.get("reason"))

asyncio.run(listen("session-token"))

Ending A Session

# Start the configured grace period so the user can reconnect.
client.sessions.disconnect(session.session_token)

# End immediately with no grace period.
client.sessions.disconnect(session.session_token, explicit_end=True)

Resources

Sessions

Method	Description	Returns
client.sessions.create(...)	Creates a WebRTC session and returns a token plus embeddable URL.	WebRTCSession
client.sessions.connect(token)	Exchanges the session token for LiveKit credentials and dispatches the agent for inbound sessions.	WebRTCSessionConnect
client.sessions.get(token)	Fetches current session state.	WebRTCSessionStatus
client.sessions.disconnect(token, explicit_end=False)	Marks a participant disconnect or ends the session.	WebRTCSessionStatus
client.sessions.ws_url(token)	Builds the WebSocket URL for real-time session events.	str

Calls

call = client.calls.trigger(
    agent_id="agent-uuid-or-name",
    contact_number="[phone]",
    name="Ayush",
    metadata={"ticket_id": "T-1234"},
)

call = client.calls.get(call.call_id)
transcript = client.calls.get_transcript(call.call_id)
calls = client.calls.list(agent_id="agent-uuid-or-name", page=1, page_size=50)

Agents

agents = client.agents.list()
agent = client.agents.get("agent-uuid-or-name")

Response Models

WebRTCSession

Field	Type
session_token	str
session_url	str
expires_at	datetime

WebRTCSessionConnect

Field	Type
lk_url	str
lk_token	str
room_name	str

WebRTCSessionStatus

Field	Type
status	str
expires_at	datetime
ui_type	str
room_name	str
agent_id	str
client_id	str
metadata	dict
grace_period_ends_at	`datetime

Error Handling

All SDK exceptions inherit from VaaniError.

from vaani import (
    AuthenticationError,
    ConnectionError,
    InsufficientBalanceError,
    RateLimitError,
    ServerError,
    TimeoutError,
    VaaniError,
)

try:
    session = client.sessions.create(agent_id="agent-uuid-or-name")
except AuthenticationError:
    print("Invalid API key")
except InsufficientBalanceError:
    print("Wallet balance is too low")
except RateLimitError:
    print("Too many requests")
except (TimeoutError, ConnectionError, ServerError):
    print("Vaani API is temporarily unavailable")
except VaaniError as exc:
    print(exc.message, exc.status_code)

Development

uv run --extra dev pytest -q

License

MIT