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 as HTTP Basic auth (username `yotel`, password = this token; max 84 bytes)
`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`. See the advisory.
`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"`

When this agent is the ceiling

Three separate numbers can bound how many calls run at once: your channel allocation (what your account was sold), a campaign’s max_concurrent, and this agent’s max_concurrent. The lowest one wins. When you create or update an agent whose max_concurrent is below your channel allocation, the response carries an advisory:

{
  "id": "va_abc123",
  "max_concurrent": 3,
  "advisory": "max_concurrent=3 is below this tenant's 5 allocated channels; this agent, not your channels, will be the ceiling for every campaign and flow pointed at it."
}

The request still succeeds — a lower cap is a legitimate choice, because your voice pipeline may have a lower limit than the carrier does. The advisory exists because the alternative is silence: an agent capped below the channels looks identical to a healthy one on every screen, and raising the channel allocation then changes nothing. advisory is null when the cap is at or above the allocation, and when the account has no allocation at all (there is no number to be below). Treat it as informational: it is not an error code, and it may describe other configuration notes in future.

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. Returns 409 while anything still depends on it:

an in-progress AI session;
a draft, running, or paused campaign bound to it, a draft or published flow whose AI node points at it, or the tenant default — the detail names each one so you can re-point or archive them first (completed campaigns and archived flows do not block);
any past AI session at all — call history references the agent, so it cannot be deleted; archive it instead to retire it while keeping the history.

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
`advisory`	string \| null	A non-fatal note about the configuration you just wrote — see below. `null` when there is nothing to say.
`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 — an active session, a live campaign / flow / tenant default, or call history still references the agent (`VoiceAgentInUse`); the `detail` says which
`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

When this agent is the ceiling

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

​When this agent is the ceiling

​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

When this agent is the ceiling

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