AI sessions

AI sessions are created automatically when a voice agent connects to a call. The control endpoint lets your AI service (or any authorized caller) send telephony commands to an active session.

For the full list of 25 control verbs with detailed parameters, see the Control API reference.

Send a control event

Dispatches a telephony verb to an active AI session. Your AI service calls this endpoint during or after a conversation to transfer, hang up, set dispositions, manage conferences, and more.

curl -X POST https://api.yotel.in/api/v1/ai-sessions/{call_id}/control \
  -H "Authorization: Bearer yt_cb_CALLBACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "transfer",
    "destination_type": "agent",
    "destination": "agent_abc"
  }'

result = client.ai_sessions.transfer(
    call_id="call_id",
    destination_type="agent",
    destination="agent_abc",
    callback_token="yt_cb_...",
)

const result = await client.aiSessions.transfer("call_id", {
  destinationType: "agent",
  destination: "agent_abc",
  callbackToken: "yt_cb_...",
});

Status: 200 OK

Authentication

Two auth options — use whichever fits your architecture:

Auth method	Header	Scope	Blast radius
Callback token	`Bearer yt_cb_…`	Bound to one `call_id`	Single call only
Tenant API key	`Bearer yt_live_…`	`ai_sessions:control_admin`	Any call in tenant

Callback tokens are delivered in the metadata frame when the WebSocket connects. They auto-rotate at 25 minutes via a token_refresh text frame — your AI service should swap to the new token on receipt.

Request body

{
  "event": "<verb>",
  ...verb-specific fields
}

Response

{
  "ok": true,
  "call_id": "call_abc",
  "dispatched_at": "2026-05-18T10:04:48Z",
  "result": {}
}

Rate limit

10 requests per second per call_id. Exceeding returns 429.

Revoke a callback token

Immediately invalidates a per-call callback token. Use this when your AI service detects a token compromise or needs to force a session handoff.

curl -X POST https://api.yotel.in/api/v1/ai-sessions/{call_id}/revoke_token \
  -H "Authorization: Bearer yt_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"token": "yt_cb_compromised_token"}'

result = client.ai_sessions.revoke_token(
    call_id="call_id",
    token="yt_cb_compromised_token",
)
print(result["jti"], result["revoked_until_ts"])

const result = await client.aiSessions.revokeToken("call_id", {
  token: "yt_cb_compromised_token",
});

Scope: ai_sessions:control_admin | Status: 200 OK

Response

{
  "ok": true,
  "jti": "token_jti_value",
  "revoked_until_ts": 1716026688
}

Token revocation requires ai_sessions:control_admin scope — callback tokens cannot revoke themselves. The token’s embedded call_id must match the URL path call_id (tenant fence).

Control verbs reference

The control endpoint supports 25 verbs organized in three groups:

Group	Verbs
Call-state primitives	`transfer`, `hangup`, `log`, `mute`, `unmute`, `hold`, `unhold`, `send_dtmf`, `play_audio`, `set_disposition`, `recording_pause`, `recording_resume`, `get_call_state`
Conferencing & supervision	`conference_start`, `conference_add`, `conference_remove`, `conference_leave`, `request_supervisor`, `whisper`, `barge`, `monitor_start`, `monitor_stop`
Lead & context	`set_lead_field`, `set_lead_status`, `schedule_callback`

See the Control API reference for detailed parameters, idempotency behavior, and error codes for each verb.

Errors

Status	Condition
`401`	Missing or malformed auth token
`403`	Wrong `call_id` for this token, or missing scope
`404`	Call not found
`409`	AI session not active or already terminated (`AISessionTerminated`)
`429`	Rate limit exceeded (10 req/s per call_id) or max concurrent sessions reached

Overview

Campaigns

Leads

Calls & Recordings

Agents

Voice Agents

Webhook Management

API Keys

AI sessions

Send a control event

Authentication

Request body

Response

Rate limit

Revoke a callback token

Response

Control verbs reference

Errors

​Send a control event

​Authentication

​Request body

​Response

​Rate limit

​Revoke a callback token

​Response

​Control verbs reference

​Errors

Send a control event

Authentication

Request body

Response

Rate limit

Revoke a callback token

Response

Control verbs reference

Errors