> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yotel.in/llms.txt
> Use this file to discover all available pages before exploring further.

# AI sessions

> Control active AI voice sessions and manage callback tokens.

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.

<Info>
  For the full list of 25 control verbs with detailed parameters, see the
  [Control API reference](/voice-agents/control-api).
</Info>

## 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.

<CodeGroup>
  ```bash curl theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  result = client.ai_sessions.transfer(
      call_id="call_id",
      destination_type="agent",
      destination="agent_abc",
      callback_token="yt_cb_...",
  )
  ```

  ```typescript TypeScript theme={null}
  const result = await client.aiSessions.transfer("call_id", {
    destinationType: "agent",
    destination: "agent_abc",
    callbackToken: "yt_cb_...",
  });
  ```
</CodeGroup>

**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

```json theme={null}
{
  "event": "<verb>",
  ...verb-specific fields
}
```

### Response

```json theme={null}
{
  "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.

<CodeGroup>
  ```bash curl theme={null}
  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"}'
  ```

  ```python Python theme={null}
  result = client.ai_sessions.revoke_token(
      call_id="call_id",
      token="yt_cb_compromised_token",
  )
  print(result["jti"], result["revoked_until_ts"])
  ```

  ```typescript TypeScript theme={null}
  const result = await client.aiSessions.revokeToken("call_id", {
    token: "yt_cb_compromised_token",
  });
  ```
</CodeGroup>

**Scope:** `ai_sessions:control_admin`  |  **Status:** `200 OK`

### Response

```json theme={null}
{
  "ok": true,
  "jti": "token_jti_value",
  "revoked_until_ts": 1716026688
}
```

<Warning>
  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).
</Warning>

***

## 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](/voice-agents/control-api) 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 |