Sessions API

A session represents a single voice conversation. Start a session via REST, then connect via WebSocket for real-time audio streaming.

Start a Session

BASH

curl -X POST https://ultravoice.us.inc/api/v1/voice/sessions/start \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "AGENT_ID",
    "user_id": "end-user-123",
    "system_prompt": "Optional override of agent system prompt",
    "welcome_message": "Hello! How can I help?",
    "dynamic_variables": {
      "customer_name": "Alice",
      "account_id": "ACC-789"
    }
  }'

JSON

{
  "session_id": "f7e8d9c0-b1c2-4d3e-a5f6-789012345678",
  "agent_id": "a1b2c3d4-...",
  "status": "ready",
  "websocket_url": "wss://ultravoice.us.inc/api/v1/voice/ws/f7e8d9c0-..."
}

Start Session Parameters

"agent_id" (string, required) — Agent to use for this session
"user_id" (string, required) — End-user identifier for logging and analytics
"system_prompt" (string, optional) — Override agent's default system prompt
"welcome_message" (string, optional) — Override agent's welcome message
"dynamic_variables" (object, optional) — Key-value pairs injected into prompt template

End a Session

BASH

curl -X POST https://ultravoice.us.inc/api/v1/voice/sessions/{session_id}/end \
  -H "Content-Type: application/json"

Sessions also auto-end when the WebSocket disconnects or after the max_turns limit is reached.

Active Sessions

BASH

curl https://ultravoice.us.inc/api/v1/sessions/active \
  -H "Authorization: Bearer $TOKEN"

Session Lifecycle

created — Session initialized, WebSocket not yet connected
active — WebSocket connected, audio streaming in progress
ended — Session completed normally or by explicit end call
error — Session terminated due to an error