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.

Report a post-call outcome

Send what your agent learned once the call is over: why it ended, who ended it, and the fields it collected. Yotel shows it on the call and writes it into the tenant’s CRM.

curl -X POST https://api.yotel.in/api/v1/ai-sessions/{call_id}/outcome \
  -H "Authorization: Bearer yt_cb_CALLBACK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"end_reason":"booking_confirmed","end_initiated_by":"agent","collected_data":{"site_visit_date":"2026-09-05"}}'

client.ai_sessions.report_outcome(
    "call_id",
    end_reason="booking_confirmed",
    end_initiated_by="agent",
    collected_data={"site_visit_date": "2026-09-05"},
    callback_token="yt_cb_...",
)

await client.aiSessions.reportOutcome("call_id", {
  endReason: "booking_confirmed",
  endInitiatedBy: "agent",
  collectedData: { site_visit_date: "2026-09-05" },
  callbackToken: "yt_cb_...",
});

Status: 200 OK — { "ok": true, "call_id": "...", "reported_at": "..." }

Unlike control verbs, this endpoint accepts a session that has already ended, and the per-call token stays valid for 180 seconds after the audio WebSocket closes — for this endpoint only, and only for that automatic close-triggered revocation. If Yotel (or your own integration) revokes the token explicitly — e.g. because it leaked — that revocation takes effect immediately, however recently it happened; it never gets this grace. Send the report from your post-call step. Retries are safe: the latest report replaces the previous one.

Field	Type	Rule
`end_reason`	string	required, up to 64 chars
`end_initiated_by`	string	optional, up to 32 chars
`collected_data`	object	up to 50 keys — a 51st+ key is truncated, not rejected; keys are letters, digits, `_ . -`; string values up to 500 chars; phone-shaped numbers are redacted; a non-finite number (`NaN`/`Infinity`) is stored as `null`
`summary`	string	optional, up to 4000 chars
`disposition`	string	optional — one of the tenant’s disposition `code`s, as returned by the disposition list. Matched exactly first, then case- and separator-insensitively (`"Not Interested"` ≡ `not_interested`). A value Yotel cannot use never rejects the report: see `disposition_status` below.
`disposition_notes`	string	optional — free text stored with the disposition (up to 2000 chars; phone-shaped numbers are redacted).

Response: { "ok": true, "call_id": "...", "reported_at": "...", "disposition_status": "written" } — disposition_status is present only when you sent a disposition:

`disposition_status`	Meaning
`written`	Stored on the call as the tenant’s own code, marked as set by the AI. A row the tenant flagged Do Not Call also adds the number to the tenant’s DNC list. Also returned when a retry of the same report finds its own value already there.
`already_set`	The call already had a disposition (an in-call control verb, or a human agent at wrap-up). Yotel never overwrites it; the rest of the report was stored.
`unknown_code`	No disposition with that code exists for the tenant. Nothing was written; the rest of the report was stored.
`not_ai_selectable`	The code exists but the tenant has switched it off for AI agents (Settings → Dispositions). Nothing was written.

Feature-detect before you send disposition. A Yotel deployment that predates this field rejects the whole report with 422 on the unknown key. Call the disposition list at call start and include disposition only when that response carried "outcome_accepts_disposition": true. If you ever get a 422 with the fields present, resend once without them.

Two keys inside collected_data are reserved and always dropped: end_reason and end_initiated_by. Send those as the top-level fields above instead — the top-level values are what Yotel stores and forwards to your CRM, so a same-named key nested inside collected_data would otherwise duplicate them.

Unknown is not an outcome. The literal value unknown (or a blank) in end_reason or end_initiated_by is stored verbatim but is never forwarded as a result: the CRM line reads outcome=not reported by the voice agent, and end_initiated_by then falls back to who the telephony layer saw hang up (ended_by=customer (hung up) when the far end sent the BYE on a normally cleared call). If your agent cannot determine a reason, omit the detail rather than inventing one — and prefer calling your end-of-call tool when the caller says goodbye, so the reason is yours and not inferred.

List the dispositions your agent may set

Fetch the tenant’s disposition list at call start and build your agent’s vocabulary from it, so a disposition the tenant adds, renames or switches off on the dialer reaches your agent with no code change.

curl https://api.yotel.in/api/v1/ai-sessions/{call_id}/dispositions \
  -H "Authorization: Bearer yt_cb_CALLBACK_TOKEN"

vocabulary = client.ai_sessions.list_dispositions("call_id", callback_token="yt_cb_...")

const vocabulary = await client.aiSessions.listDispositions("call_id", {
  callbackToken: "yt_cb_...",
});

Status: 200 OK

{
  "dispositions": [
    { "code": "callback",            "label": "Call Back",           "is_dnc": false, "is_callback": true,  "parent_code": null },
    { "code": "scheduled_call_back", "label": "Scheduled Call Back", "is_dnc": false, "is_callback": true,  "parent_code": "callback" },
    { "code": "do_not_call",         "label": "Do not Call",         "is_dnc": true,  "is_callback": false, "parent_code": null }
  ],
  "outcome_accepts_disposition": true
}

Rows are the tenant’s dispositions marked AI may set (Settings → Dispositions), in the tenant’s own order. code is what you send back as disposition on the outcome report — a leaf’s own code, never its group’s.
parent_code names the group a leaf rolls up to (null for a group row). Tenants can hold their CRM’s exact outcome vocabulary as leaves under Yotel’s groups, so labels are theirs verbatim; ignore this key if your agent has no use for grouping.
is_dnc tells your agent which row means “do not call”. Key your do-not-call behaviour on this flag, never on a hardcoded code — tenants rename rows.
The list is served from your callback token alone; it does not depend on the call having been recorded yet, so it is safe to fetch the moment your session starts. Do not cache a failure: a 404 or 5xx means “try again on the next call”, not “this tenant has no list”.
outcome_accepts_disposition is the capability flag for the disposition field on the outcome report. It is always true on a deployment that serves this route; an older deployment answers 404.

Same authentication and rate limit as control verbs; the 180-second post-close token grace does not apply here.

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

Report a post-call outcome

List the dispositions your agent may set

Revoke a callback token

Response

Control verbs reference

Errors

​Send a control event

​Authentication

​Request body

​Response

​Rate limit

​Report a post-call outcome

​List the dispositions your agent may set

​Revoke a callback token

​Response

​Control verbs reference

​Errors

Send a control event

Authentication

Request body

Response

Rate limit

Report a post-call outcome

List the dispositions your agent may set

Revoke a callback token

Response

Control verbs reference

Errors