User Manual · Developer

Webhook events

CleverStack can send an event to your server at every step of a call: when it starts, rings, is answered and ends, when the call record, recording and transcript are ready, and when the outcome is saved. It also sends WhatsApp message events and AI Agent events. This page lists every event, how delivery works, and a sample body for each.

← Back to the User Manual

All names, numbers, ids and links in the examples on this page are sample values. Your events carry your own values.

Getting started

Create a webhook, learn how events reach your server, and pick the groups of events you need.

Set up a webhook

How to
  1. Open Developer › Webhooks in the console.
  2. Click Create Webhook and enter the HTTPS URL on your server that should receive events.
  3. Tick the events you want. The picker lists them in the groups below; a webhook receives only the events it is subscribed to.
  4. Save, then place a test call and check that your server answers with a 2xx status.

How delivery works

Method and body
The method set on the webhook (normally POST) with a JSON body. Any static body fields you add to the webhook are merged into every body.
Join key
call_uuid (and trace_id, same value) is identical on every event of one call. On WhatsApp, trace_id is the message id.
Duplicates
Delivery is at least once. The X-Webhook-Id header is the same on a repeat delivery: store it and drop events you have already processed.
Organisation
Every delivery carries the header X-Org-Id with your organisation id (a UUID). AI Agent events also carry it in the body as org_uuid.
Success
Any 2xx response, within 10 seconds. Do slow work after you reply.
Retries
Any other response (including 4xx), a timeout or a network error is retried: 8 attempts in total, after 1 min, 4 min, 10 min, 30 min, 1 h, 4 h and 6 h, about 12 hours in all. After the last attempt the delivery shows as failed in the webhook logs in the console.
Order
Events can arrive out of order. Sort by timestamp and join on trace_id.
Timestamps
UTC, ISO 8601 with Z, for example 2026-11-19T10:00:00.000000Z.
New fields
We may add fields. We never rename or remove one. Ignore fields you do not know.

Event groups

Every event belongs to one group. Each group has its own part of this page.

Events: CALL_INITIATEDCALL_RINGINGCALL_ANSWEREDCALL_COMPLETEDCALL_CDRCALL_RECORDINGTRANSCRIPTION_COMPLETED
What it covers: Every step of an inbound, outbound or AI agent call, its record, recording and transcript.
Events: DISPOSITION_SUBMITTED
What it covers: The outcome saved for a call by an agent, the AI or a campaign.
Events: WHATSAPP_MESSAGE_RECEIVEDWHATSAPP_MESSAGE_SENTWHATSAPP_MESSAGE_DELIVEREDWHATSAPP_MESSAGE_READWHATSAPP_MESSAGE_FAILED
What it covers: Messages a customer sends you and the delivery status of messages you send.
Events: WHATSAPP_SESSION_STARTEDWHATSAPP_SESSION_CLOSED
What it covers: The 24-hour customer service window opening and closing.
Events: WHATSAPP_TEMPLATE_CREATEDWHATSAPP_TEMPLATE_UPDATEDWHATSAPP_TEMPLATE_APPROVEDWHATSAPP_TEMPLATE_REJECTEDWHATSAPP_TEMPLATE_DELETED
What it covers: Your message templates being created, edited, approved, rejected or deleted.
Events: AI_CONVERSATION_STARTEDAI_ACTION_FAILEDAI_HANDOFFAI_CONVERSATION_COMPLETED
What it covers: Each conversation an AI agent handles, on calls and WhatsApp, from start to result.

Call events

Every step of a call, its record, recording and transcript. Inbound and outbound calls send the same events with the same fields: tell them apart by call_type and call_mode. Join the events of one call on call_uuid.

At a glance

CALL_INITIATED
When it is sent: A call is created. On inbound calls: when the first agent is rung
Outbound: Yes
Inbound: When an agent is rung
AI agent call: Outbound only
CALL_RINGING
When it is sent: The first agent's phone rings. Not sent for click-to-call
Outbound: Yes, except click-to-call
Inbound: When an agent is rung
AI agent call: Outbound only
CALL_ANSWERED
When it is sent: A party answers: the customer (on inbound, when your call flow answers) and each agent who picks up
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_COMPLETED
When it is sent: A party's leg ends: once per party
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_CDR
When it is sent: The call record, a few seconds after the call ends. Once per call
Outbound: Yes
Inbound: Yes
AI agent call: Yes
CALL_RECORDING
When it is sent: The call's recording is published, and again when it changes
Outbound: Yes
Inbound: Yes
AI agent call: Yes
TRANSCRIPTION_COMPLETED
When it is sent: The transcript and analysis are ready, seconds to a minute after the call
Outbound: With Post-call insights
Inbound: With Post-call insights
AI agent call: Yes

Event order

Events can arrive out of order, so treat these sequences as a guide, not a rule.

Inbound: the call flow answers, then an agent is rung and picks up
  1. 1. CALL_ANSWERED (customer)
  2. 2. CALL_INITIATED (agent)
  3. 3. CALL_RINGING (agent)
  4. 4. CALL_ANSWERED (agent)
  5. 5. CALL_COMPLETED (customer)
  6. 6. CALL_COMPLETED (agent)
  7. 7. CALL_CDR
Outbound click-to-call: the agent's phone is called first, then the customer
  1. 1. CALL_INITIATED (agent)
  2. 2. CALL_ANSWERED (agent)
  3. 3. CALL_ANSWERED (customer)
  4. 4. CALL_COMPLETED (customer)
  5. 5. CALL_COMPLETED (agent)
  6. 6. CALL_CDR
Inbound that never rings an agent (ends in the call flow or with an AI agent)
  1. 1. CALL_ANSWERED (customer)
  2. 2. CALL_COMPLETED (customer)
  3. 3. CALL_CDR

Call lifecycle events

CALL_INITIATED · CALL_RINGING · CALL_ANSWERED · CALL_COMPLETED

These four events share one body. Each one is about one party's leg of the call, named in participant.

event
Type: string
Meaning: The event name.
call_uuid
Type: string
Meaning: The call's id. The same on every event of one call.
trace_id
Type: string
Meaning: Same value as call_uuid.
call_mode
Type: string
Meaning: incoming on inbound; click_to_call, manual, preview, progressive or call_flow on outbound.
call_type
Type: string
Meaning: inbound for calls to your number, outbound for calls you place. Same events and fields either way.
status
Type: string
Meaning: initiated, ringing, customer_answered or agent_answered, completed.
participant
Type: string
Meaning: Whose leg the event is about: customer or agent (call on CALL_CDR).
agent_id
Type: string | null
Meaning: The agent's user id. null when no person is on the leg (call flow, AI agent).
agent_number
Type: string | null
Meaning: The agent's phone or extension on an agent's leg; null on any leg with no person on it (the customer's leg, a call flow, an AI agent). CALL_CDR carries the agent's extension.
customer_number
Type: string
Meaning: The customer's number in E.164 format.
cli_number
Type: string
Meaning: Your CleverStack number: the number dialled on inbound, the caller ID on outbound.
recording_url
Type: string | null
Meaning: Present once recording has started. The full link is on CALL_COMPLETED and on CALL_CDR.
timestamp
Type: string
Meaning: When the event happened (UTC).
metadata
Type: object
Meaning: On calls started through the click-to-call API: the metadata you sent, returned unchanged on every lifecycle event.
  • On inbound calls CALL_INITIATED and CALL_RINGING fire when the first agent is rung, not when the customer's call arrives.
  • Click-to-call does not send CALL_RINGING.
  • An inbound call that never rings an agent sends only CALL_ANSWERED and CALL_COMPLETED for the customer, then CALL_CDR.
Inbound: CALL_ANSWERED (customer)

Your call flow answers the customer. No agent is on this leg yet.

{
  "event": "CALL_ANSWERED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000001",
  "call_mode": "incoming",
  "call_type": "inbound",
  "status": "customer_answered",
  "participant": "customer",
  "agent_id": null,
  "agent_number": null,
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": null,
  "timestamp": "2026-11-19T10:00:00.000000Z"
}
Inbound: CALL_INITIATED (agent)

The first agent is rung. CALL_RINGING follows with the same body and status: "ringing".

{
  "event": "CALL_INITIATED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000001",
  "call_mode": "incoming",
  "call_type": "inbound",
  "status": "initiated",
  "participant": "agent",
  "agent_id": "101",
  "agent_number": "+919900000001",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": null,
  "timestamp": "2026-11-19T10:00:12.000000Z"
}
Inbound: CALL_ANSWERED (agent)
{
  "event": "CALL_ANSWERED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000001",
  "call_mode": "incoming",
  "call_type": "inbound",
  "status": "agent_answered",
  "participant": "agent",
  "agent_id": "101",
  "agent_number": "+919900000001",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000001_2026-11-19.wav",
  "timestamp": "2026-11-19T10:00:18.000000Z"
}
Inbound: CALL_COMPLETED (customer)

The agent's CALL_COMPLETED has the same body with participant: "agent" and the agent's number.

{
  "event": "CALL_COMPLETED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000001",
  "call_mode": "incoming",
  "call_type": "inbound",
  "status": "completed",
  "participant": "customer",
  "agent_id": "101",
  "agent_number": null,
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000001_2026-11-19.wav",
  "timestamp": "2026-11-19T10:03:20.000000Z"
}
Outbound click-to-call: CALL_INITIATED (agent)

The agent's phone is called first. The metadata you sent with the click-to-call request comes back on every lifecycle event.

{
  "event": "CALL_INITIATED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000002",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000002",
  "call_mode": "click_to_call",
  "call_type": "outbound",
  "status": "initiated",
  "participant": "agent",
  "agent_id": "101",
  "agent_number": "+919900000001",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000002_2026-11-19.wav",
  "timestamp": "2026-11-19T11:00:00.000000Z",
  "metadata": {
    "lead_id": "L-1001",
    "source": "crm"
  }
}
Outbound click-to-call: CALL_ANSWERED (customer)

Before this, the agent's own CALL_ANSWERED arrives with participant: "agent" and status: "agent_answered".

{
  "event": "CALL_ANSWERED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000002",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000002",
  "call_mode": "click_to_call",
  "call_type": "outbound",
  "status": "customer_answered",
  "participant": "customer",
  "agent_id": "101",
  "agent_number": null,
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000002_2026-11-19.wav",
  "timestamp": "2026-11-19T11:00:15.000000Z",
  "metadata": {
    "lead_id": "L-1001",
    "source": "crm"
  }
}

Call record

CALL_CDR

One per call, a few seconds after it ends. It carries the lifecycle fields above, with participant: "call", plus the fields below. Read outcome to know how the call ended.

direction
Type: string
Meaning: inbound or outbound.
lifecycle_status
Type: string
Meaning: ended.
outcome
Type: string
Meaning: How the call ended: answered, missed, abandoned, no_answer, rejected, busy, failed, cancelled or voicemail.
status
Type: string
Meaning: Stays completed for older integrations. Read outcome instead.
cdr_details.customer_name, agent_name
Type: string | null
Meaning: Names, when known.
cdr_details.call_start_time, call_answered_time, call_end_time
Type: string | null
Meaning: Call times (UTC).
cdr_details.call_duration, call_answered_duration, ring_duration, hold_duration, billable_duration, recording_seconds
Type: number | null
Meaning: Durations in seconds.
cdr_details.customer_timings
Type: object
Meaning: The customer leg's times and durations.
cdr_details.agent_totals
Type: object
Meaning: Totals across every agent leg.
cdr_details.agents[]
Type: array
Meaning: One entry per agent who was rung: who, times, durations, how their leg ended (outcome, is_connected) and hang-up codes. Each entry also carries org, user_email, extension_id, extension_uuid, agent_uuid, sip_call_id, read_codec, write_codec and call quality (mos, mos_min, jitter_ms_max, packet_loss_pct, poor_seconds, one_way_seconds); any of them is null when it was not measured or does not apply. Empty when no person was rung.
cdr_details.hangup_details
Type: object
Meaning: Telecom hang-up codes for the call, useful when a call fails.
Inbound answered call
{
  "event": "CALL_CDR",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000001",
  "call_mode": "incoming",
  "call_type": "inbound",
  "direction": "inbound",
  "status": "completed",
  "lifecycle_status": "ended",
  "outcome": "answered",
  "participant": "call",
  "agent_id": "101",
  "agent_number": "1001",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000001_2026-11-19.wav",
  "timestamp": "2026-11-19T10:03:32.000000Z",
  "cdr_details": {
    "customer_name": "Customer One",
    "agent_name": "Agent One",
    "call_start_time": "2026-11-19T10:00:00.000000Z",
    "call_answered_time": "2026-11-19T10:00:18.000000Z",
    "call_end_time": "2026-11-19T10:03:20.000000Z",
    "call_duration": 200,
    "call_answered_duration": 182,
    "ring_duration": 6,
    "hold_duration": 0,
    "billable_duration": 182,
    "recording_seconds": 182,
    "region": null,
    "customer_timings": {
      "start_time": "2026-11-19T10:00:00.000000Z",
      "answered_time": "2026-11-19T10:00:18.000000Z",
      "end_time": "2026-11-19T10:03:20.000000Z",
      "duration": 200,
      "answered_duration": 182,
      "ring_duration": 6
    },
    "agent_totals": {
      "total_duration": 188,
      "total_answered_duration": 182,
      "total_ring_duration": 6
    },
    "agents": [
      {
        "user_id": "101",
        "user_name": "Agent One",
        "agent_number": "1001",
        "call_uuid": "6b1f2c3d-0000-4000-8000-000000000001",
        "call_mode": "incoming",
        "call_type": "inbound",
        "caller_id": "+918000000001",
        "customer_number": "+919800000001",
        "outcome": "answered",
        "is_connected": true,
        "agent_start_time": "2026-11-19T10:00:12.000000Z",
        "agent_answered_time": "2026-11-19T10:00:18.000000Z",
        "agent_end_time": "2026-11-19T10:03:20.000000Z",
        "agent_duration": 188,
        "agent_answered_duration": 182,
        "agent_ring_duration": 6,
        "hangup_cause": "NORMAL_CLEARING",
        "hangup_reason": null,
        "endpoint_disposition": "ANSWER",
        "sip_hangup_disposition": "recv_bye",
        "sip_term_status": "200",
        "sip_response_code": "16",
        "destination_type": "sip",
        "transfer_type": "",
        "transfer_number": ""
      }
    ],
    "hangup_details": {
      "endpoint_disposition": "ANSWER",
      "sip_hangup_disposition": "recv_bye",
      "hangup_cause": "NORMAL_CLEARING",
      "hangup_reason": null,
      "sip_term_status": "200",
      "sip_response_code": "16"
    }
  }
}
Outbound click-to-call answered
{
  "event": "CALL_CDR",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000002",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000002",
  "call_mode": "click_to_call",
  "call_type": "outbound",
  "direction": "outbound",
  "status": "completed",
  "lifecycle_status": "ended",
  "outcome": "answered",
  "participant": "call",
  "agent_id": "101",
  "agent_number": "1001",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000002_2026-11-19.wav",
  "timestamp": "2026-11-19T11:02:27.000000Z",
  "cdr_details": {
    "customer_name": "Customer One",
    "agent_name": "Agent One",
    "call_start_time": "2026-11-19T11:00:04.000000Z",
    "call_answered_time": "2026-11-19T11:00:15.000000Z",
    "call_end_time": "2026-11-19T11:02:15.000000Z",
    "call_duration": 131,
    "call_answered_duration": 120,
    "ring_duration": 11,
    "hold_duration": 0,
    "billable_duration": 120,
    "recording_seconds": 120,
    "region": null,
    "customer_timings": {
      "start_time": "2026-11-19T11:00:04.000000Z",
      "answered_time": "2026-11-19T11:00:15.000000Z",
      "end_time": "2026-11-19T11:02:15.000000Z",
      "duration": 131,
      "answered_duration": 120,
      "ring_duration": 11
    },
    "agent_totals": {
      "total_duration": 135,
      "total_answered_duration": 131,
      "total_ring_duration": 4
    },
    "agents": [
      {
        "user_id": "101",
        "user_name": "Agent One",
        "agent_number": "1001",
        "call_uuid": "6b1f2c3d-0000-4000-8000-000000000002",
        "call_mode": "click_to_call",
        "call_type": "outbound",
        "caller_id": "+918000000001",
        "customer_number": "+919800000001",
        "outcome": "answered",
        "is_connected": true,
        "agent_start_time": "2026-11-19T11:00:00.000000Z",
        "agent_answered_time": "2026-11-19T11:00:04.000000Z",
        "agent_end_time": "2026-11-19T11:02:15.000000Z",
        "agent_duration": 135,
        "agent_answered_duration": 131,
        "agent_ring_duration": 4,
        "hangup_cause": "NORMAL_CLEARING",
        "hangup_reason": null,
        "endpoint_disposition": "ANSWER",
        "sip_hangup_disposition": "recv_bye",
        "sip_term_status": "200",
        "sip_response_code": "16",
        "destination_type": "sip",
        "transfer_type": "",
        "transfer_number": ""
      }
    ],
    "hangup_details": {
      "endpoint_disposition": "ANSWER",
      "sip_hangup_disposition": "recv_bye",
      "hangup_cause": "NORMAL_CLEARING",
      "hangup_reason": null,
      "sip_term_status": "200",
      "sip_response_code": "16"
    }
  }
}

Recording ready

CALL_RECORDING

Sent when a call's recording is published, on inbound and outbound calls. revision goes up each time the recording changes: keep the highest. recording_url is set only when state is verified (playable); otherwise it is null.

event
Type: string
Meaning: CALL_RECORDING.
contract
Type: number
Meaning: Version of this body, currently 1.
org
Type: string
Meaning: Your organisation's number in CleverStack.
call_uuid
Type: string
Meaning: The call's id (join key).
revision
Type: number
Meaning: Goes up by one with every change to this call's recording.
state
Type: string
Meaning: verified when the recording is stored and recording_url works. Any other value (for example pending or lost) means there is no playable recording and recording_url is null.
recording_url
Type: string | null
Meaning: The recording link.
recording_seconds
Type: number | null
Meaning: Length of the recording in seconds.
Recording of the outbound call published
{
  "event": "CALL_RECORDING",
  "contract": 1,
  "org": "1001",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000002",
  "revision": 1,
  "state": "verified",
  "recording_url": "https://recordings.cleverstack.in/sample/6b1f2c3d-0000-4000-8000-000000000002_2026-11-19.wav",
  "recording_seconds": 120
}

Transcript and analysis

TRANSCRIPTION_COMPLETED

Sent when the call's transcript and analysis are ready, seconds to a minute after the call. For calls handled by people it needs the Post-call insights feature on your plan.

call_uuid, trace_id
Type: string
Meaning: The call's id (join key).
transcription_id
Type: number
Meaning: Id of this transcript.
status
Type: string
Meaning: completed, completed_no_speech, failed or failed_no_recording.
language_code
Type: string
Meaning: The detected language.
summary
Type: string
Meaning: A short summary of the call.
sentiment, sentiment_confidence
Type: string, number
Meaning: Overall sentiment and how sure the model is (0 to 1).
key_points, action_items
Type: string[]
Meaning: Lists of short sentences.
ai_suggested_disposition
Type: string | null
Meaning: The outcome the AI suggests. Not the saved disposition: that comes in DISPOSITION_SUBMITTED.
disposition
Type: string | null
Meaning: Older name for ai_suggested_disposition, same value.
segments[]
Type: array
Meaning: Transcript lines: speaker, start and end time in seconds, text, confidence and sentiment.
customer_number, agent_id, call_duration
Type: —
Meaning: Call context. agent_id is null on calls handled by an AI agent.
created_at, completed_at
Type: string
Meaning: When the transcription started and finished.
Transcript of a call handled by an AI agent
{
  "event": "TRANSCRIPTION_COMPLETED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "transcription_id": 30001,
  "org": "1001",
  "status": "completed",
  "language_code": "en",
  "transcription_duration_seconds": 95,
  "error_message": null,
  "summary": "Customer booked a cleaning appointment for Friday morning.",
  "sentiment": "positive",
  "sentiment_confidence": 0.9,
  "key_points": [
    "Wants Friday morning",
    "Prefers the city centre branch"
  ],
  "action_items": [
    "Send booking confirmation"
  ],
  "ai_suggested_disposition": "appointment_booked",
  "disposition": "appointment_booked",
  "created_at": "2026-11-19T13:02:10.000000Z",
  "completed_at": "2026-11-19T13:02:20.000000Z",
  "segments": [
    {
      "id": 1,
      "speaker_tag": "SPEAKER_0",
      "speaker_label": "agent",
      "start_time": 0.4,
      "end_time": 2.6,
      "text": "Hello, how can I help you today?",
      "confidence": 0.97,
      "sentiment": "neutral",
      "sentiment_confidence": 0.8
    },
    {
      "id": 2,
      "speaker_tag": "SPEAKER_1",
      "speaker_label": "customer",
      "start_time": 3,
      "end_time": 5.8,
      "text": "I'd like to book a cleaning for Friday morning.",
      "confidence": 0.95,
      "sentiment": "positive",
      "sentiment_confidence": 0.8
    }
  ],
  "customer_number": "+919800000001",
  "agent_id": null,
  "call_duration": 95
}

Calls handled by an AI agent

An AI agent call needs no extra setup: subscribe to the call events above.

  • A call answered by an AI agent sends the same call events and fields as any other call.
  • agent_id and agent_number are null, and cdr_details.agents is empty, because no person took the call.
  • On an inbound AI call no agent is rung, so there is no CALL_INITIATED or CALL_RINGING: you receive CALL_ANSWERED and CALL_COMPLETED for the customer, then CALL_CDR.
  • TRANSCRIPTION_COMPLETED brings the transcript and the AI analysis, seconds to a minute after the call.
  • DISPOSITION_SUBMITTED with actor: "ai" brings the saved disposition, when auto-disposition is switched on.

Disposition events

The outcome saved for a call, by an agent, the AI or a campaign. Join it to the call events on call_uuid.

Saved disposition

DISPOSITION_SUBMITTED

Sent when a call's disposition is saved, changed or removed, on inbound, outbound and AI agent calls. On AI agent calls it is sent when auto-disposition is switched on.

call_uuid, trace_id, session_id
Type: string
Meaning: The call's id (join key). All three hold the same value.
disposition, sub_disposition
Type: string | null
Meaning: What was chosen.
code, label, sub_code, sub_label
Type: string | null
Meaning: The same choice as stored code and display label.
actor
Type: string
Meaning: Who saved it: agent, ai, campaign or system.
source
Type: string
Meaning: human or ai.
agent_user_id, agent_email
Type: string | null
Meaning: The agent, when a person saved it.
campaign_id
Type: number | null
Meaning: The campaign, when the call came from one.
record_id, table_code
Type: —
Meaning: The disposition record in CleverStack.
recorded_at
Type: string
Meaning: When it was saved.
deleted
Type: boolean
Meaning: true when the disposition was removed.
Saved by the AI

When an agent saves it, actor is agent, source is human, and agent_user_id and agent_email are filled.

{
  "event": "DISPOSITION_SUBMITTED",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "session_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "disposition": "Appointment booked",
  "sub_disposition": null,
  "v": 1,
  "org": "1001",
  "record_id": 40001,
  "table_code": "disposition",
  "campaign_id": null,
  "agent_user_id": null,
  "agent_email": null,
  "source": "ai",
  "actor": "ai",
  "code": "Appointment booked",
  "label": "Appointment booked",
  "sub_code": null,
  "sub_label": null,
  "recorded_at": "2026-11-19T13:02:25.000000Z",
  "deleted": false
}

WhatsApp events

Three groups in the picker: messages, the 24-hour session window, and message templates. WhatsApp events have the same flat shape as call events: event is the event name you subscribe to, trace_id joins the events of one message (it is the message id), customer_number is the customer and cli_number is your WhatsApp business number. Every key is always present.

Message events

WHATSAPP_MESSAGE_RECEIVED
A customer sends you a message
WHATSAPP_MESSAGE_SENT
Your message is accepted by WhatsApp
WHATSAPP_MESSAGE_DELIVERED
It reaches the customer's phone
WHATSAPP_MESSAGE_READ
The customer opens it
WHATSAPP_MESSAGE_FAILED
WhatsApp could not deliver it
WHATSAPP_MESSAGE_RECEIVED
{
  "event": "WHATSAPP_MESSAGE_RECEIVED",
  "message_id": "wamid.SAMPLE0001",
  "trace_id": "wamid.SAMPLE0001",
  "session_id": 5001,
  "direction": "inbound",
  "status": "received",
  "customer_number": "+919800000001",
  "cli_number": "+918000000002",
  "context_id": null,
  "message": {
    "type": "text",
    "text": {
      "body": "Hi, I want to reschedule my appointment"
    }
  },
  "metadata": {},
  "timestamp": "2026-11-19T12:00:00.000000Z"
}
WHATSAPP_MESSAGE_DELIVERED

SENT, READ and FAILED have the same body with their own event and status. context_id is the message being replied to, when there is one.

{
  "event": "WHATSAPP_MESSAGE_DELIVERED",
  "message_id": "wamid.SAMPLE0002",
  "trace_id": "wamid.SAMPLE0002",
  "session_id": 5001,
  "direction": "outbound",
  "status": "delivered",
  "customer_number": "+919800000001",
  "cli_number": "+918000000002",
  "context_id": null,
  "message": {
    "type": "template",
    "template": {
      "name": "appointment_reminder",
      "language": {
        "code": "en"
      }
    }
  },
  "metadata": {
    "campaign_id": "C-2001"
  },
  "timestamp": "2026-11-19T12:01:05.000000Z"
}

Session lifecycle events

WHATSAPP_SESSION_STARTED
The 24-hour customer service window opens
WHATSAPP_SESSION_CLOSED
The 24-hour customer service window closes
WHATSAPP_SESSION_STARTED
{
  "event": "WHATSAPP_SESSION_STARTED",
  "session_id": 5001,
  "trace_id": "5001",
  "status": "started",
  "customer_number": "+919800000001",
  "cli_number": "+918000000002",
  "timestamp": "2026-11-19T12:00:00.000000Z"
}

Template lifecycle events

WHATSAPP_TEMPLATE_CREATED
A message template is created
WHATSAPP_TEMPLATE_UPDATED
A template is edited
WHATSAPP_TEMPLATE_APPROVED
WhatsApp approves a template
WHATSAPP_TEMPLATE_REJECTED
WhatsApp rejects a template; reason says why
WHATSAPP_TEMPLATE_DELETED
A template is deleted
WHATSAPP_TEMPLATE_APPROVED
{
  "event": "WHATSAPP_TEMPLATE_APPROVED",
  "template_id": "1000000000000001",
  "trace_id": "1000000000000001",
  "template_name": "appointment_reminder",
  "language": "en",
  "status": "APPROVED",
  "category": "UTILITY",
  "reason": null,
  "timestamp": "2026-11-19T09:30:00.000000Z"
}

AI Agent events

Four events, sent for every conversation an AI agent handles, on calls and on WhatsApp. They have their own AI Agent Events group in the picker.

The four events

AI_CONVERSATION_STARTED
The AI answers the call or replies first on a chat
AI_ACTION_FAILED
A tool the AI uses fails, for example a call to your API returns an error
AI_HANDOFF
The AI transfers the customer to a person, before the person answers
AI_CONVERSATION_COMPLETED
The AI's part ends and its analysis is ready, a few seconds after; at most 60 seconds

All four carry org_uuid (your organisation id), call_uuid (join with the call events), run_id (one AI conversation) and metadata (what you sent when starting the call through click-to-call, unchanged; {} otherwise). Fields that do not apply are null, never missing.

Values
end_reason
agent_completed, caller_hung_up, transferred, timeout, error
result
success, failure, transferred, incomplete
actions[].type
webhook (your API), record, appointment, transfer
actions[].status
success, failed, skipped
analysis.status
completed, failed, pending

Sample bodies

AI_CONVERSATION_STARTED
{
  "event": "AI_CONVERSATION_STARTED",
  "version": 1,
  "org_uuid": "9b2e4c71-5d3a-4f8e-a6b0-2c7d1e9f4a35",
  "channel": "call",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "conversation_id": null,
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "run_id": "7c2a9d10-0000-4000-8000-000000000001",
  "direction": "inbound",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "ai_agent": {
    "id": 26,
    "name": "Inbound assistant",
    "revision": 10
  },
  "metadata": {},
  "timestamp": "2026-11-19T13:00:00.000000Z"
}
AI_ACTION_FAILED
{
  "event": "AI_ACTION_FAILED",
  "version": 1,
  "org_uuid": "9b2e4c71-5d3a-4f8e-a6b0-2c7d1e9f4a35",
  "channel": "call",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "conversation_id": null,
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "run_id": "7c2a9d10-0000-4000-8000-000000000001",
  "ai_agent": {
    "id": 26,
    "name": "Inbound assistant",
    "revision": 10
  },
  "action": {
    "name": "create_booking",
    "type": "webhook",
    "status": "failed",
    "http_status": 500,
    "attempts": 3,
    "error": "Webhook action failed with status 500",
    "trace_id": "7c2a9d10-0000-4000-8000-000000000001",
    "record_id": null,
    "output": null,
    "at": "2026-11-19T13:01:10.000000Z"
  },
  "metadata": {},
  "timestamp": "2026-11-19T13:01:10.000000Z"
}
AI_HANDOFF
{
  "event": "AI_HANDOFF",
  "version": 1,
  "org_uuid": "9b2e4c71-5d3a-4f8e-a6b0-2c7d1e9f4a35",
  "channel": "call",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "conversation_id": null,
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "run_id": "7c2a9d10-0000-4000-8000-000000000001",
  "customer_number": "+919800000001",
  "ai_agent": {
    "id": 26,
    "name": "Inbound assistant",
    "revision": 10
  },
  "transfer": {
    "to_type": "queue",
    "to": "Support",
    "reason": "caller asked for a person"
  },
  "collected_data": {
    "name": "Customer One"
  },
  "metadata": {},
  "timestamp": "2026-11-19T13:01:30.000000Z"
}
AI_CONVERSATION_COMPLETED
{
  "event": "AI_CONVERSATION_COMPLETED",
  "version": 1,
  "org_uuid": "9b2e4c71-5d3a-4f8e-a6b0-2c7d1e9f4a35",
  "channel": "call",
  "call_uuid": "6b1f2c3d-0000-4000-8000-000000000003",
  "conversation_id": null,
  "trace_id": "6b1f2c3d-0000-4000-8000-000000000003",
  "run_id": "7c2a9d10-0000-4000-8000-000000000001",
  "direction": "inbound",
  "customer_number": "+919800000001",
  "cli_number": "+918000000001",
  "ai_agent": {
    "id": 26,
    "name": "Inbound assistant",
    "revision": 10
  },
  "started_at": "2026-11-19T13:00:00.000000Z",
  "ended_at": "2026-11-19T13:01:35.000000Z",
  "duration_seconds": 95,
  "language": "en",
  "end_reason": "agent_completed",
  "result": "success",
  "needs_follow_up": false,
  "follow_up_reason": null,
  "transfer": null,
  "actions": [
    {
      "name": "create_booking",
      "type": "webhook",
      "status": "success",
      "http_status": 201,
      "attempts": 1,
      "error": null,
      "trace_id": "7c2a9d10-0000-4000-8000-000000000001",
      "record_id": null,
      "output": {
        "booking_id": "BK-1001"
      },
      "at": "2026-11-19T13:01:10.000000Z"
    }
  ],
  "collected_data": {
    "name": "Customer One",
    "preferred_date": "2026-11-21"
  },
  "transcript": [
    {
      "speaker": "ai",
      "text": "Hello, how can I help you today?",
      "at": "2026-11-19T13:00:01.000000Z"
    },
    {
      "speaker": "customer",
      "text": "I'd like to book a cleaning for Friday morning.",
      "at": "2026-11-19T13:00:04.000000Z"
    }
  ],
  "analysis": {
    "status": "completed",
    "summary": "Customer booked a cleaning appointment for Friday morning.",
    "sentiment": "positive",
    "key_points": [
      "Friday morning"
    ],
    "action_items": [
      "Send confirmation"
    ],
    "suggested_outcome": "appointment_booked"
  },
  "metadata": {
    "lead_id": "L-1001"
  },
  "timestamp": "2026-11-19T13:01:45.000000Z"
}

On WhatsApp

AI_CONVERSATION_COMPLETED on WhatsApp

On WhatsApp the four AI events have the same body, with channel: "whatsapp", conversation_id filled and call_uuid set to null. cli_number is your WhatsApp business number. AI_CONVERSATION_COMPLETED is sent when the AI closes the chat or the 24-hour window ends with no reply.

{
  "event": "AI_CONVERSATION_COMPLETED",
  "version": 1,
  "org_uuid": "9b2e4c71-5d3a-4f8e-a6b0-2c7d1e9f4a35",
  "channel": "whatsapp",
  "call_uuid": null,
  "conversation_id": "8d3b0e21-0000-4000-8000-000000000001",
  "trace_id": "8d3b0e21-0000-4000-8000-000000000001",
  "run_id": "7c2a9d10-0000-4000-8000-000000000002",
  "direction": "inbound",
  "customer_number": "+919800000001",
  "cli_number": "+918000000002",
  "ai_agent": {
    "id": 31,
    "name": "WhatsApp assistant",
    "revision": 4
  },
  "started_at": "2026-11-19T12:00:00.000000Z",
  "ended_at": "2026-11-19T12:04:28.000000Z",
  "duration_seconds": 268,
  "language": "en",
  "end_reason": "agent_completed",
  "result": "success",
  "needs_follow_up": false,
  "follow_up_reason": null,
  "transfer": null,
  "actions": [
    {
      "name": "reschedule_appointment",
      "type": "webhook",
      "status": "success",
      "http_status": 200,
      "attempts": 1,
      "error": null,
      "trace_id": "7c2a9d10-0000-4000-8000-000000000002",
      "record_id": null,
      "output": {
        "appointment_id": "AP-1001"
      },
      "at": "2026-11-19T12:03:55.000000Z"
    }
  ],
  "collected_data": {
    "name": "Customer One",
    "new_date": "2026-11-22"
  },
  "transcript": [
    {
      "speaker": "customer",
      "text": "Hi, I want to reschedule my appointment",
      "at": "2026-11-19T12:00:00.000000Z"
    },
    {
      "speaker": "ai",
      "text": "Sure. Which date suits you?",
      "at": "2026-11-19T12:00:03.000000Z"
    }
  ],
  "analysis": {
    "status": "completed",
    "summary": "Customer moved their appointment to 22 November.",
    "sentiment": "positive",
    "key_points": [
      "Rescheduled to 22 November"
    ],
    "action_items": [],
    "suggested_outcome": "appointment_rescheduled"
  },
  "metadata": {},
  "timestamp": "2026-11-19T12:04:35.000000Z"
}