Voice agents CRUD

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
    }
  }'

va = client.voice_agents.create(
    name="Support bot v2",
    ws_url="wss://ai.example.com/ws",
    auth_token="secret_token_123",
    max_concurrent=50,
)
print(va.id)

const va = await client.voiceAgents.create({
  name: "Support bot v2",
  ws_url: "wss://ai.example.com/ws",
  auth_token: "secret_token_123",
  max_concurrent: 50,
});
console.log(va.id);

Scope: voice_agents:write | Status: 201 Created

Request body

Field	Type	Default	Description
`name`	string	—	Display name (1–200 chars, required)
`ws_url`	string	—	WebSocket endpoint for audio streaming (must start with `ws://` or `wss://`, required)
`auth_token`	string \| null	`null`	Static token sent in the WebSocket handshake
`audio_format`	object	See below	Audio encoding config
`external_agent_id`	string \| null	`null`	Your internal ID for cross-referencing
`transfer_destination`	string \| null	`null`	Default transfer target (E.164 or SIP URI)
`max_concurrent`	integer	`10`	Max simultaneous sessions (1–10,000). Redis-enforced; exceeding returns `429`.
`token_lifetime`	string	`"30min_with_refresh"`	`"30min_with_refresh"` or `"ws_session"`
`subprotocol`	string	`"audio.drachtio.org"`	`"audio.drachtio.org"` or `"audio.jambonz.org"`
`ws_disconnect_action`	string	`"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"

agents = client.voice_agents.list()

const agents = await client.voiceAgents.list();

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"

va = client.voice_agents.get("voice_agent_id")

const va = await client.voiceAgents.get("voice_agent_id");

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}'

va = client.voice_agents.update("voice_agent_id", max_concurrent=100)

const va = await client.voiceAgents.update("voice_agent_id", {
  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"

va = client.voice_agents.archive("voice_agent_id")

const va = await client.voiceAgents.archive("voice_agent_id");

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"

client.voice_agents.delete("voice_agent_id")

await client.voiceAgents.delete("voice_agent_id");

Scope: voice_agents:write | Status: 204 No Content

Response fields

Field	Type	Description
`id`	string	Voice agent UUID
`tenant_id`	string	Owning tenant
`name`	string	Display name
`ws_url`	string	WebSocket endpoint
`auth_token`	string \| null	Static auth token
`audio_format`	object	Audio encoding config
`external_agent_id`	string \| null	Your cross-reference ID
`transfer_destination`	string \| null	Default transfer target
`max_concurrent`	integer	Concurrency limit
`status`	string	`"active"`, `"paused"`, or `"archived"`
`token_lifetime`	string	`"30min_with_refresh"` or `"ws_session"`
`subprotocol`	string	WebSocket subprotocol
`ws_disconnect_action`	string	`"hangup"` or `"transfer_to_queue"`
`created_at`	string	ISO 8601
`updated_at`	string	ISO 8601

Errors

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

Overview

Campaigns

Leads

Calls & Recordings

Agents

Voice Agents

AI Sessions

Webhook Management

API Keys

Create a voice agent

Request body

Default audio format

List voice agents

Response

Get a voice agent

Update a voice agent

Archive a voice agent

Delete a voice agent

Response fields

Errors

​Create a voice agent

​Request body

​Default audio format

​List voice agents

​Response

​Get a voice agent

​Update a voice agent

​Archive a voice agent

​Delete a voice agent

​Response fields

​Errors

Create a voice agent

Request body

Default audio format

List voice agents

Response

Get a voice agent

Update a voice agent

Archive a voice agent

Delete a voice agent

Response fields

Errors