Skip to main content
A voice agent is a tenant-scoped routing alias that tells Yotel where to send audio when a call is answered. It maps a name to a WebSocket URL, authentication config, audio format, and concurrency limits.
Voice agents define routing, not behavior. Your AI service receives the audio stream and decides what to do. See the Voice agents quickstart for the integration flow.

​
Create a voice agent

curl -X POST https://api.yotel.in/api/v1/voice-agents \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support bot v2",
    "ws_url": "wss://ai.example.com/ws",
    "auth_token": "secret_token_123",
    "max_concurrent": 50,
    "audio_format": {
      "encoding": "pcm_s16le",
      "sample_rate_hz": 16000,
      "channels": 1,
      "frame_ms": 20
    }
  }'
Scope: voice_agents:write  |  Status: 201 Created

​
Request body

FieldTypeDefaultDescription
namestring—Display name (1–200 chars, required)
ws_urlstring—WebSocket endpoint for audio streaming (must start with ws:// or wss://, required)
auth_tokenstring | nullnullStatic token sent in the WebSocket handshake
audio_formatobjectSee belowAudio encoding config
external_agent_idstring | nullnullYour internal ID for cross-referencing
transfer_destinationstring | nullnullDefault transfer target (E.164 or SIP URI)
max_concurrentinteger10Max simultaneous sessions (1–10,000). Redis-enforced; exceeding returns 429.
token_lifetimestring"30min_with_refresh""30min_with_refresh" or "ws_session"
subprotocolstring"audio.drachtio.org""audio.drachtio.org" or "audio.jambonz.org"
ws_disconnect_actionstring"hangup"What happens when your WS disconnects: "hangup" or "transfer_to_queue"

​
Default audio format

{
  "encoding": "pcm_s16le",
  "sample_rate_hz": 16000,
  "channels": 1,
  "frame_ms": 20
}

​
List voice agents

curl https://api.yotel.in/api/v1/voice-agents \
  -H "Authorization: Bearer yt_live_YOUR_KEY"
Scope: voice_agents:read  |  Status: 200 OK Optional query parameter: status — filter by "active", "paused", or "archived".

​
Response

{
  "items": [ /* VoiceAgentResponse objects */ ],
  "total": 3
}

​
Get a voice agent

curl https://api.yotel.in/api/v1/voice-agents/{voice_agent_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY"
Scope: voice_agents:read  |  Status: 200 OK

​
Update a voice agent

PATCH semantics — only include fields you want to change. Null or absent fields are not modified. 
curl -X PATCH https://api.yotel.in/api/v1/voice-agents/{voice_agent_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"max_concurrent": 100}'
Scope: voice_agents:write  |  Status: 200 OK

​
Archive a voice agent

Soft-deletes the voice agent by setting status: "archived". The UUID remains valid for foreign-key references (existing calls, campaigns) but new calls will not route to an archived agent. 
curl -X POST https://api.yotel.in/api/v1/voice-agents/{voice_agent_id}/archive \
  -H "Authorization: Bearer yt_live_YOUR_KEY"
Scope: voice_agents:write  |  Status: 200 OK

​
Delete a voice agent

Hard-deletes the voice agent. Fails with 409 if the agent has active sessions. 
curl -X DELETE https://api.yotel.in/api/v1/voice-agents/{voice_agent_id} \
  -H "Authorization: Bearer yt_live_YOUR_KEY"
Scope: voice_agents:write  |  Status: 204 No Content

​
Response fields

FieldTypeDescription
idstringVoice agent UUID
tenant_idstringOwning tenant
namestringDisplay name
ws_urlstringWebSocket endpoint
auth_tokenstring | nullStatic auth token
audio_formatobjectAudio encoding config
external_agent_idstring | nullYour cross-reference ID
transfer_destinationstring | nullDefault transfer target
max_concurrentintegerConcurrency limit
statusstring"active", "paused", or "archived"
token_lifetimestring"30min_with_refresh" or "ws_session"
subprotocolstringWebSocket subprotocol
ws_disconnect_actionstring"hangup" or "transfer_to_queue"
created_atstringISO 8601
updated_atstringISO 8601

​
Errors

StatusCondition
404Voice agent not found or belongs to another tenant
409Cannot delete — active sessions exist (VoiceAgentInUse)
422Validation error (e.g., invalid ws_url, max_concurrent out of range)