Event catalog - Yotel Developer Docs

Every event envelope has this top-level shape:

{
  "event_id": "1f2e...-uuid",
  "event_type": "call.ended",
  "timestamp": 1744934400,
  "data": { ... }
}

Below, each event’s data block is documented.

Call lifecycle

`call.started`

Fires when the dialer originates a call (pre-answer).

{
  "call_id": "c-123",
  "campaign_id": "camp-567",
  "lead_id": "l-890",
  "to_number": "9876543210",
  "dial_time": "2026-04-18T14:37:02.419Z"
}

`call.answered`

Fires on CHANNEL_ANSWER — the callee picked up.

{
  "call_id": "c-123",
  "campaign_id": "camp-567",
  "answer_time": "2026-04-18T14:37:08.102Z",
  "ring_duration_s": 5
}

`call.ended`

Fires on CHANNEL_HANGUP, for every call, once the call and lead rows have been finalised — so a GET /v1/calls/{id} issued the moment you receive the event already returns the same durations and disposition.

{
  "call_id": "c-123",
  "fs_uuid": "8f3c1e2a-...",
  "campaign_id": "camp-567",
  "lead_id": "l-890",
  "salesforce_lead_id": "00Q5g00000ABCDE",
  "direction": "outbound",
  "dial_mode": "progressive",
  "status": "completed",
  "hangup_cause": "NORMAL_CLEARING",
  "dial_time": "2026-04-18T14:37:02Z",
  "answer_time": "2026-04-18T14:37:08Z",
  "end_time": "2026-04-18T14:39:02Z",
  "ring_duration_s": 6,
  "talk_duration_s": 114,
  "total_duration_s": 120,
  "disposition": "interested",
  "disposition_source": "ai",
  "recording": {
    "available": false,
    "url": null
  }
}

Field	Notes
`salesforce_lead_id`	The call’s own Salesforce id if one was attached, else the lead’s, else the `sf_lead_id` the lead was imported with. `null` when the lead has no Salesforce record.
`dial_mode`	`preview`, `progressive`, `power`, or `predictive` — the mode this call was placed in, which may differ from the campaign’s current setting.
`status`	`completed` or `failed`.
`disposition_source`	`agent`, `ai`, or `null` — who set the disposition.
Timestamps	ISO-8601 UTC, second precision. `answer_time` is `null` on an unanswered call.

call.ended carries no phone number and no lead name. Join on lead_id (or salesforce_lead_id) against your own record if you need the contact details — this keeps the event safe to log and safe to deliver for tenants under PII-strict handling.

recording.available is usually false at hangup — the upload to storage has not finished yet. call.recording_ready follows 30–120 s later with the same recording.url, which is stable and safe to persist: it re-signs storage on every fetch instead of handing you a URL that expires.

`call.disposition_set`

Fires when a call’s behavioural outcome is recorded — Interested, Site Visit, Do Not Call. call.ended carries the mechanical outcome (answered, busy, no answer); this carries what the call was actually worth, and it is usually the event a CRM wants. It fires twice in two different situations, and previous_disposition tells them apart:

When	`previous_disposition`
The first time a disposition is set on the call	`null`
A later correction changes it — a supervisor fixing an agent’s mistake, or a second pass by the AI	the value being replaced

Re-saving the same value is not a transition and publishes nothing, so a double-clicked Save or a retried AI verb will not produce a duplicate.

{
  "call_id": "c-123",
  "campaign_id": "camp-567",
  "lead_id": "l-890",
  "salesforce_lead_id": "00Q5g00000ABCDE",
  "disposition": "interested",
  "previous_disposition": null,
  "source": "ai",
  "occurred_at": "2026-08-26T14:39:02Z"
}

Field	Notes
`disposition`	The tenant’s own disposition code, verbatim. Yotel does not normalise it.
`previous_disposition`	Populated only on a change. `null` on the first set — that is the signal, not an omission.
`source`	`agent`, `ai`, or `null` when the writer did not say.
`occurred_at`	ISO-8601 UTC, second precision — the same spelling as `call.ended`’s timestamps.

call.disposition_set carries no phone number, no lead name, and no agent notes. Join on lead_id (or salesforce_lead_id) against your own record if you need contact details. Notes are excluded deliberately: free text an agent typed is the one field here where a number can arrive without any field being named phone.

Whether this event reaches you at all is governed by event routing as well as your subscription’s own event filter.

`call.recording_ready`

Fires when the recording is uploaded and available for playback — typically 30–120 s after call.ended.

{
  "call_id": "c-123",
  "gcp_path": "recordings/2026/08/25/c-123.wav",
  "recording_url": "https://api.yotel.in/api/v1/calls/c-123/recording/audio",
  "signed_url": "https://storage.googleapis.com/yotel-recordings/...",
  "recording": {
    "available": true,
    "url": "https://api.yotel.in/api/v1/recordings/c-123/audio?t=3f9ab21c..."
  },
  "is_test": false,
  "stereo": true,
  "format": "audio/wav"
}

recording.url is a non-expiring, HMAC-tokenised public link — it never rotates or expires and needs no API key, so it’s the field to persist in external systems: a Salesforce Call_Detail__c.Recording_File__c, a CRM attachment, a webhook subscriber’s own database. The legacy top-level recording_url is the tenant-scoped, API-key-gated audio proxy (also stable, but requires your API credentials on every fetch — use it from server-side code that already holds them). signed_url is a direct GCS link that expires after 1 hour; use it only for an immediate fetch, never for storage — persist recording.url or recording_url instead.

`call.transcript_ready`

Fires when Gemini transcription completes (typically +30–60s after recording upload).

{
  "call_id": "c-123",
  "transcript_url": "https://storage.googleapis.com/yotel-transcripts/...",
  "language": "ta-IN",
  "duration_s": 114
}

Lead lifecycle

`lead.completed`

Fires when a lead reaches a terminal state (completed, failed, dnd, or no_answer after exhausted retries).

{
  "lead_id": "l-890",
  "campaign_id": "camp-567",
  "status": "completed",
  "attempts": 2
}

Campaign lifecycle

`campaign.started`

{ "campaign_id": "camp-567" }

`campaign.paused`

Fires on BOTH manual and auto-pause. Distinguish via data.source:

`source`	Meaning
`"manual"`	Operator paused via dashboard or `/predictive/pause` endpoint. `user_id` + `reason` included.
`"abandon_rate_exceeded"`	D11 in-memory controller tripped the 60s sustained-breach threshold.
`"safety_sweep"`	D13 Celery sweep’s DB-based fallback tripped the threshold. Runner was probably crashed.

{
  "campaign_id": "camp-567",
  "source": "manual",
  "reason": "Carrier complaint — investigate",
  "user_id": "user-42"
}

`campaign.resumed`

Symmetric to paused. source is "manual" in all current paths (auto-resume from safety-sweep doesn’t exist — humans re-enable).

{
  "campaign_id": "camp-567",
  "source": "manual",
  "reason": "Abandon rate back under 1%",
  "user_id": "user-42"
}

`campaign.completed`

reason is "stopped" when an operator or an API call stopped it, and "leads_finished" when it stopped by itself because all its leads were finished. previous_status is running or paused.

{
  "campaign_id": "camp-567",
  "previous_status": "running",
  "reason": "leads_finished"
}

This is not a final event. A stopped campaign can be restarted, which fires campaign.reopened. If you close a record on campaign.completed, subscribe to campaign.reopened too.

`campaign.reopened`

Fires when a stopped campaign is restarted (completed → running) — the usual reason being leads imported after the stop. A campaign that stopped by itself (reason: "leads_finished") restarts by itself when new leads arrive, and fires this too. Emitted alongside campaign.started, never instead of it, so subscribing to this is only necessary if you treated campaign.completed as final. completed_at is the timestamp the campaign carried before the restart cleared it, or null if it never had one.

{
  "campaign_id": "camp-567",
  "dial_mode": "progressive",
  "completed_at": "2026-09-06T15:25:19Z"
}

Agent lifecycle

`agent.logged_in`

{
  "agent_id": "ag-7",
  "extension": "1042",
  "user_id": "user-42"
}

`agent.logged_out`

{ "agent_id": "ag-7" }

v2 events (coming)

These will land in v1.1 / v2:

Event	Purpose
`campaign.created`	CRM sync — register the campaign on your side
`lead.added`	Post-create hook for just-added leads
`agent.state_changed`	Fine-grained agent state stream (noisy — may be opt-in)
`supervisor.session_started`	Barge / whisper / monitor start

​Call lifecycle

​call.started

​call.answered

​call.ended

​call.disposition_set

​call.recording_ready

​call.transcript_ready

​Lead lifecycle

​lead.completed

​Campaign lifecycle

​campaign.started

​campaign.paused

​campaign.resumed

​campaign.completed

​campaign.reopened

​Agent lifecycle

​agent.logged_in

​agent.logged_out

​v2 events (coming)

Call lifecycle

`call.started`

`call.answered`

`call.ended`

`call.disposition_set`

`call.recording_ready`

`call.transcript_ready`

Lead lifecycle

`lead.completed`

Campaign lifecycle

`campaign.started`

`campaign.paused`

`campaign.resumed`

`campaign.completed`

`campaign.reopened`

Agent lifecycle

`agent.logged_in`

`agent.logged_out`

v2 events (coming)