Python SDK

Use the Vatel Python SDK to call the REST and WebSocket APIs from Python. The REST client exposes the API for your organization; the WebSocket connection is async-only for real-time sessions; you receive events and send input audio and tool results.

Session token

REST endpoint used to obtain a short-lived JWT for the WebSocket connection.

Connection

WebSocket channel, message types, and request/response flow.

Prerequisites

Python 3.9+
Organization API key from the Vatel dashboard
Agent ID (agent UUID) for the agent you want to run the call with

Walkthrough

Install the SDK

Install from the repository:

pip install git+https://github.com/Devpro-Software/vatel-py-sdk.git

Create a client

Create a Client with your organization API key. Optionally set a different host:

from vatel import Client

client = Client(api_key="your-organization-api-key")

Get a session token

Generate a short-lived token for the WebSocket. Pass the agent UUID you want to run the call with:

resp = client.session.generate_token(agent_id="agent-uuid-here")
token = resp.token

Async: resp = await client.session.generate_token_async(agent_id="...").

Connect and stream messages

Connect with the token and iterate over incoming messages. Handle events and send tool results as needed:

import asyncio
from vatel import Client
from vatel.models.ws import ToolCall

async def main():
    client = Client(api_key="your-api-key")
    token = (await client.session.generate_token_async(agent_id="agent-uuid")).token
    conn = await client.connect(token=token)

    async for msg in conn.stream_messages():
        if getattr(msg, "type", None) == "session_started":
            print("Call started:", msg.data.id)
        elif getattr(msg, "type", None) == "response_text":
            print("Agent:", msg.data.text)
        elif getattr(msg, "type", None) == "input_audio_transcript":
            print("You:", msg.data.transcript)
        elif getattr(msg, "type", None) == "response_audio":
            # Base64 PCM 16-bit 24 000 Hz mono - decode and play or process
            pass
        elif getattr(msg, "type", None) == "session_ended":
            break
        elif isinstance(msg, ToolCall):
            await conn.send_tool_call_output(msg.data.toolCallId, "your-result")

    await conn.close()
    await client.aclose()

asyncio.run(main())

Send audio

Send captured audio as base64-encoded PCM 16-bit, 24 000 Hz, mono:

await conn.send_input_audio(audio_base64="...")

REST API

The client exposes the REST API; see the API reference for all endpoints. Examples: List agents (sync and async):

agents = client.agents.list()
for agent in agents:
    print(agent.id, agent.name)
# Async: agents = await client.agents.list_async()

Session token (required for the WebSocket):

resp = client.session.generate_token(agent_id="agent-uuid-here")
token = resp.token
# Async: resp = await client.session.generate_token_async(agent_id="...")

Tool calls

When the server sends a tool_call message, run your logic and send the result back:

await conn.send_tool_call_output(tool_call_id=msg.data.toolCallId, output="result string")

Message types (server → client)

Type	Description
`session_started`	Call started; `data.id` is session ID
`session_ended`	Call ended
`response_audio`	Agent TTS chunk; `data.audio` base64, `data.turn_id`
`response_text`	Agent text for the turn
`input_audio_transcript`	Your speech (STT)
`speech_started` / `speech_stopped`	VAD events
`interruption`	You interrupted the agent
`tool_call`	Server requests a tool; reply with `send_tool_call_output`

Example app

The repo includes a full-duplex demo (mic → server, agent audio → speaker):

pip install -r examples/requirements-optional.txt
python examples/run_session.py --api-key YOUR_KEY --agent-id AGENT_UUID

Overview

Configure

Deploy

Monitor

Integrations

Session token

Connection

Prerequisites

Walkthrough

REST API

Tool calls

Message types (server → client)

Example app

Session token

Connection

​Prerequisites

​Walkthrough

​REST API

​Tool calls

​Message types (server → client)

​Example app

Prerequisites

Walkthrough

REST API

Tool calls

Message types (server → client)

Example app