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