Skip to main content
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

1

Install the SDK

Install from the repository:
pip install git+https://github.com/Devpro-Software/vatel-py-sdk.git
2

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")
3

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="...").
4

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())
5

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)

TypeDescription
session_startedCall started; data.id is session ID
session_endedCall ended
response_audioAgent TTS chunk; data.audio base64, data.turn_id
response_textAgent text for the turn
input_audio_transcriptYour speech (STT)
speech_started / speech_stoppedVAD events
interruptionYou interrupted the agent
tool_callServer 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