AI session events - Yotel Developer Docs

When a call hands off to a voice agent, Yotel publishes a stream of webhook events that mirror the AI’s lifecycle: started, ended, transferred, escalated, and conference changes. The four pre-existing call.* events (started, answered, ended, recording_ready) still fire — call.recording_ready gains a stereo flag when the call was AI-driven. This page is the reference for AI-call subscribers. For the global event catalogue and delivery mechanics see Webhooks overview and Event catalog.

AI events ride the same delivery infrastructure as every other event — same envelope, same signature scheme, same retry schedule. Adding ai_session.* is a pure additive change; existing handlers keep working.

Common envelope

{
  "id": "evt_01HW8...",
  "type": "ai_session.transferred",
  "created_at": "2026-05-01T14:37:08.102Z",
  "tenant_id": "<uuid>",
  "data": { /* event-specific payload */ }
}

Headers:

X-Yotel-Signature: t=<unix_ts>,v0=<hex_hmac_sha256>
X-Yotel-Event-Id: evt_01HW8...
X-Yotel-Event-Type: ai_session.transferred

X-Yotel-Signature follows the Stripe shape: HMAC_SHA256(secret, f"{t}.{raw_body}"). A 5-min freshness window prevents replay. See Signature verification for verifier code.

Subscribing

Webhook subscriptions are managed from the dashboard, not the public API. Pick AI-session events with the wildcard ai_session.* to opt into the full stream:

curl -X POST https://api.yotel.in/api/v1/webhooks \
  -H "Authorization: Bearer $YOTEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-host.example.com/webhooks/yotel",
    "event_types": ["ai_session.*", "call.recording_ready"]
  }'

Save the signing_secret from the response — it’s shown once.

Per-event reference

`call.started`

Pre-answer originate event. Fires for every call, AI or human. For AI campaigns, voice_agent_id is the resolved UUID.

{
  "call_id": "<uuid>",
  "direction": "outbound",
  "from": "+91...",
  "to": "+91...",
  "campaign_id": "<uuid|null>",
  "voice_agent_id": "<uuid|null>",
  "started_at": "2026-05-01T14:37:02.419Z"
}

`call.answered`

Fires on CHANNEL_ANSWER. answered_by_amd is Yotel’s AMD classification — "machine" calls still get connected to the AI; your AI service can decide whether to leave a message or hang up.

{
  "call_id": "<uuid>",
  "answer_time": "2026-05-01T14:37:08.102Z",
  "answered_by_amd": "human"
}

`call.ended`

Fires on CHANNEL_HANGUP. disposition is null if the AI never called set_disposition. For full AI lifecycle context see ai_session.ended (fires alongside this one for AI calls).

{
  "call_id": "<uuid>",
  "end_time": "2026-05-01T14:39:02.102Z",
  "hangup_cause": "NORMAL_CLEARING",
  "total_duration_s": 120,
  "talk_duration_s": 114,
  "disposition": "interested"
}

`call.recording_ready`

Fires when the WAV upload to GCS completes (typically +2-5s after hangup). stereo: true for AI calls (left=caller, right=AI); false for human-only calls.

{
  "call_id": "<uuid>",
  "recording_url": "https://api.yotel.in/api/v1/calls/<id>/recording",
  "signed_url": "https://storage.googleapis.com/.../<id>.wav?...",
  "duration_s": 47,
  "stereo": true,
  "format": "audio/wav"
}

The signed_url expires ~15 minutes after issue. For long-lived access, hit recording_url (the proxy endpoint) on demand — or pull the bytes promptly into your own storage.

`ai_session.started`

Fires when Yotel opens the audio fork to your voice agent. ws_url is the resolved URL (after override hierarchy).

{
  "call_id": "<uuid>",
  "voice_agent_id": "<uuid>",
  "external_agent_id": "tier1_v3",
  "ws_url": "wss://ai.example.com/yotel/audio-fork",
  "started_at": "2026-05-01T14:37:08.500Z"
}

`ai_session.ended`

Fires when the AI session terminates (transfer, hangup, error, or 30-min timeout). metadata carries the full audit log — every log invocation plus the final transfer/hangup metadata.

{
  "call_id": "<uuid>",
  "voice_agent_id": "<uuid>",
  "ended_at": "2026-05-01T14:39:01.999Z",
  "outcome": "transferred_agent",
  "metadata": {
    "logs": [ {"step": "intent_classified", "intent": "renewal"} ],
    "final": {"destination_type": "agent_queue", "destination": "tier1"}
  }
}

outcome is one of: transferred_agent, transferred_e164, transferred_sip_uri, hangup, error, timeout.

`ai_session.transferred`

Fires on a successful transfer verb. The AI’s leg drops; the caller is bridged to destination. ai_session.ended fires immediately after.

{
  "call_id": "<uuid>",
  "voice_agent_id": "<uuid>",
  "destination_type": "agent_queue",
  "destination": "tier1",
  "transferred_at": "2026-05-01T14:39:01.999Z",
  "metadata": { "intent": "billing", "summary": "..." }
}

`ai_session.escalated`

Fires on request_supervisor invocation and again on supervisor claim. Subscribers should dedupe on event.id if they only want the terminal claim.

{
  "call_id": "<uuid>",
  "voice_agent_id": "<uuid>",
  "reason": "Caller is angry",
  "urgency": "high",
  "supervisor_id": null,
  "escalated_at": "2026-05-01T14:38:30.000Z"
}

`supervisor_id`	Phase
`null`	Invocation — escalation enqueued, no human yet
`<uuid>`	Claim — supervisor accepted from the dashboard

`ai_session.conference_changed`

Fires on every conference state transition (conference_start, add, remove, leave) and the supervisor verbs (whisper, barge, monitor_start, monitor_stop).

{
  "call_id": "<uuid>",
  "voice_agent_id": "<uuid>",
  "conference_id": "<uuid>",
  "change": "added",
  "actor": "ai",
  "participants": [
    {"member_id": "mem-1", "role": "caller", "destination": "+9198..."},
    {"member_id": "mem-2", "role": "ai", "destination": "<voice-agent-id>"},
    {"member_id": "mem-3", "role": "agent", "destination": "ag-7"}
  ],
  "changed_at": "2026-05-01T14:38:15.420Z"
}

change is one of: started, added, removed, left, monitor_started, monitor_stopped, whisper, barge. actor is "ai", "supervisor", or "tenant_api".

Stereo recording flag

For AI-driven calls, RECORD_STEREO=true is set on the FreeSWITCH dialplan. The resulting WAV has two channels:

Left — the caller’s audio (PSTN side).
Right — the AI’s audio (synthesised TTS or pre-recorded URL payback returned over the WS).

Mono recordings are returned for human-only calls (no connect_voice_agent step). The stereo flag on call.recording_ready lets transcript/QA pipelines pick the right diarisation strategy without probing the file.

SDK signature verification

Both SDKs already ship a webhook helper — no new function for ai_session.*. The WebhookEventType union grew by 5 (and 1 field on RecordingReady); upgrade the SDK to get the new types.

Python

import yotel

event = yotel.webhook.verify_and_parse(
    raw_body,
    headers=request.headers,
    signing_secret=os.environ["YOTEL_WEBHOOK_SECRET"],
)
if event.type == "ai_session.transferred":
    ...

TypeScript

import { verifyWebhook } from "@yotel/client";

const event = verifyWebhook({
  rawBody: req.body,
  headers: req.headers,
  signingSecret: process.env.YOTEL_WEBHOOK_SECRET!,
});
if (event.type === "ai_session.transferred") {
  // event.data is fully typed
}

Retry & dead-letter

Inherited from the global delivery layer:

3 retries with backoff 200ms → 2s → 20s.
After 3 failures the delivery is marked dead_lettered.
Replay manually via POST /api/v1/webhooks/deliveries/{id}/replay.
2xx = success; 4xx (except 408/429) = no retry; 5xx + 408/429 retry.

See Retries for the full schedule.

​Common envelope

​Subscribing

​Per-event reference

​call.started

​call.answered

​call.ended

​call.recording_ready

​ai_session.started

​ai_session.ended

​ai_session.transferred

​ai_session.escalated

​ai_session.conference_changed

​Stereo recording flag

​SDK signature verification

​Retry & dead-letter

​See also

Common envelope

Subscribing

Per-event reference

`call.started`

`call.answered`

`call.ended`

`call.recording_ready`

`ai_session.started`

`ai_session.ended`

`ai_session.transferred`

`ai_session.escalated`

`ai_session.conference_changed`

Stereo recording flag

SDK signature verification

Retry & dead-letter

See also