Conversation Intelligence Webhook Events: Transcripts and AI Analysis

Conversation Intelligence events tell you when AI analysis of a call is ready. The transcript is usually ready first and is announced by transcript.ready, typically seconds to minutes before the combined analysis (summary, sentiment, topics, talk ratio, and call score) follows as a single cidata.ready event. That is production order, not delivery order: as with every event, either can reach your endpoint first, so don’t make one handler depend on the other having run. These events fire for calls processed by Conversation Intelligence. They are account-level webhooks, delivered to the endpoints you register under Account → Webhooks. See the overview. All examples show the full request body, including the envelope. Fields shown in bold are always present. A bold field nested inside an optional object is always present whenever that object is. Everything else is optional and is omitted from the payload when empty.

The callers object

Both events identify the call’s participants in a callers array. Each item carries a type plus the resolved details when available:

Field	Type	Description
`type`	string	The participant kind: `contact`, `user`, `voice_agent`, or `unknown`.
`id`	string	The participant’s id, when known.
`contact`	Contact	For `type: contact`, the resolved contact, with the same fields as the contact object on call events. Omitted when the contact no longer exists.
`user`	User	For `type: user`, the resolved user, with the same fields as the user object on call events. Omitted when the user no longer exists.

The same type and id pair identifies participants in talk_ratio.caller_ratios and topics.topics[].caller_ratios on cidata.ready.

transcript.ready

Fires as soon as the transcript of a call is ready. The event carries the call reference, the detected language, who was on the call, and transcript_url: the absolute URL of the Transcription endpoint for this call, which you call with your API credentials to fetch the text. It’s the earliest trigger for transcript-driven workflows such as QA review, coaching, or logging conversations to your CRM.

Example

{
  "event_id": "018f4c2a-7b3d-8e5f-9a1b-2c3d4e5f6071",
  "type": "transcript.ready",
  "version": "v1",
  "occurred_at": "2026-08-17T09:30:12.512Z",
  "company_id": "123456",
  "data": {
    "call_id": "143223459",
    "call_uuid": "018f9a3e-5b7c-4d21-9e8f-aa12bb34cc56",
    "language": "en",
    "recording_length": 120,
    "callers": [
      {
        "type": "contact",
        "id": "44210",
        "contact": {
          "id": "44210",
          "name": "Jane Doe",
          "company": "Acme Inc.",
          "phones": ["+12025550143"],
          "emails": ["jane.doe@example.com"]
        }
      },
      {
        "type": "user",
        "id": "7",
        "user": {
          "id": "7",
          "name": "Ada Bennett",
          "email": "ada.bennett@example.com",
          "role": "agent",
          "extension": "1007"
        }
      }
    ],
    "transcript_url": "https://api.cloudtalk.io/v1/ai/calls/143223459/transcription"
  }
}

Field	Type	Description
`call_id`	string	The call’s id in call history.
`call_uuid`	string	The same call reference carried by the call events.
`language`	string	The language the transcription detected, as a language code such as `en`. Omitted when no language could be detected.
`recording_length`	number	The recording’s length in seconds.
`callers`	object[]	The call’s participants. See the callers object.
`transcript_url`	string	Absolute URL of the Transcription endpoint for this call. Call it with your API credentials. The transcript text itself is never included in the event.

cidata.ready

Fires once per call when CloudTalk’s AI analysis is ready, combining the call summary (with AI call type, smart notes and tag ids), the overall sentiment, the topics discussed, how the talking was split between participants, and, for scored calls, the call score with its scorecard breakdown, into a single event. Use it to log AI insights to your CRM, route follow-ups, or build reporting. The complete flag tells you whether the three core analysis stages (summary, sentiment, topics) all made it in. If your account has one of those AI features switched off, the event still arrives, with that section simply absent and complete set to false. An absent section is normal, not an error.

Example

{
  "event_id": "018f4c2a-7b3d-8b91-9a1b-2c3d4e5f6072",
  "type": "cidata.ready",
  "version": "v1",
  "occurred_at": "2026-08-17T09:31:05.204Z",
  "company_id": "123456",
  "data": {
    "call_id": "143223459",
    "call_uuid": "018f9a3e-5b7c-4d21-9e8f-aa12bb34cc56",
    "language": "en",
    "complete": true,
    "callers": [
      {
        "type": "contact",
        "id": "44210",
        "contact": {
          "id": "44210",
          "name": "Jane Doe",
          "company": "Acme Inc.",
          "phones": ["+12025550143"],
          "emails": ["jane.doe@example.com"]
        }
      },
      {
        "type": "user",
        "id": "7",
        "user": {
          "id": "7",
          "name": "Ada Bennett",
          "email": "ada.bennett@example.com",
          "role": "agent",
          "extension": "1007"
        }
      }
    ],
    "summary": {
      "summary": "Jane Doe called about a duplicate charge on the August invoice; the agent confirmed the error and promised a corrected invoice within two business days.",
      "ai_call_type": "billing_inquiry",
      "smart_notes": [
        "Duplicate charge confirmed on invoice 2026-08",
        "Corrected invoice promised within 2 business days"
      ],
      "call_tag_ids": ["311", "415"]
    },
    "sentiment": {
      "overall_sentiment": "positive"
    },
    "topics": {
      "topics": [
        {
          "topic": "billing",
          "weight": 0.62,
          "caller_ratios": [
            { "type": "user", "id": "7", "ratio": 40, "talking_time": 30 },
            { "type": "contact", "id": "44210", "ratio": 60, "talking_time": 45 }
          ]
        },
        {
          "topic": "invoicing",
          "weight": 0.38,
          "caller_ratios": [
            { "type": "user", "id": "7", "ratio": 55, "talking_time": 25 },
            { "type": "contact", "id": "44210", "ratio": 45, "talking_time": 20 }
          ]
        }
      ]
    },
    "talk_ratio": {
      "recording_length": 120,
      "caller_ratios": [
        { "type": "user", "id": "7", "ratio": 46, "talking_time": 55 },
        { "type": "contact", "id": "44210", "ratio": 54, "talking_time": 65 }
      ]
    },
    "call_score": {
      "overall_call_score": 78,
      "overall_summary": "The agent resolved the billing issue and set a clear expectation, but did not confirm the customer's contact details.",
      "template_id": "3",
      "groups": [
        {
          "id": "12",
          "name": "Resolution",
          "score": 100,
          "status": "passed",
          "summary": "The duplicate charge was acknowledged and a corrective action promised.",
          "questions": [
            { "id": "31", "answer": "YES", "summary": "The agent confirmed the error." },
            { "id": "32", "answer": "YES", "summary": "A corrected invoice was promised within two business days." }
          ]
        },
        {
          "id": "13",
          "name": "Compliance",
          "score": 50,
          "status": "needs_improvement",
          "summary": "Identity was not verified before discussing the invoice.",
          "questions": [
            { "id": "41", "answer": "NO", "summary": "The agent did not confirm the account holder's details." },
            { "id": "42", "answer": 4, "summary": "Tone was courteous throughout." }
          ]
        }
      ]
    }
  }
}

Field	Type	Description
`call_id`	string	The analysed call’s id in call history.
`call_uuid`	string	The same call reference carried by the call events.
`language`	string	The language the transcription detected, as a language code such as `en`. Omitted when no language could be detected.
`complete`	boolean	`true` when the summary, sentiment, and topics stages all arrived. `false` means one or more of those three sections is absent: normal when an AI feature is disabled on your account. `talk_ratio` and `call_score` don’t affect this flag.
`truncated`	string[]	Present only when a very long AI result had to be shortened to keep the event deliverable. Names the affected fields (`summary`, `smart_notes`, `topics`, `caller_ratios`, `groups`, or `overall_summary`); a shortened text ends with the marker `…[truncated]` and a shortened list has trailing entries dropped. Fetch the full value through the API if you need it. Absent means nothing was shortened.
`callers`	object[]	The call’s participants. See the callers object.
`summary`	object	The summary stage; absent when it wasn’t produced.
`summary.summary`	string \| null	The AI-generated call summary.
`summary.ai_call_type`	string \| null	The AI-classified call type. Forwarded from CloudTalk’s AI, so treat it as an open set of values.
`summary.smart_notes`	array \| object \| null	AI-generated notes from the call. Forwarded from CloudTalk’s AI exactly as produced, so treat its inner shape as illustrative rather than fixed and read the keys you need defensively.
`summary.call_tag_ids`	string[] \| null	Ids of tags applied to the call by AI.
`sentiment`	object	The sentiment stage; absent when it wasn’t produced.
`sentiment.overall_sentiment`	string \| null	The call’s overall sentiment. Current values: `very negative`, `negative`, `neutral`, `positive`, `very positive`. New values may be added over time; handle unknown values gracefully rather than failing.
`topics`	object	The topics stage; absent when it wasn’t produced.
`topics.topics`	object[] \| null	One entry per detected topic. New fields may appear on an entry over time; tolerate them.
`topics.topics[].topic`	string	The topic label.
`topics.topics[].weight`	number	The topic’s share of the conversation.
`topics.topics[].caller_ratios`	object[]	How the talking within this topic was split between participants. Same shape as `talk_ratio.caller_ratios`.
`talk_ratio`	object	How the talking was split between the call’s participants across the whole call. Usually present; not covered by `complete`.
`talk_ratio.recording_length`	number	The analysed recording’s length in seconds.
`talk_ratio.caller_ratios`	object[]	One entry per participant.
`talk_ratio.caller_ratios[].type`	string	`contact`, `user`, `voice_agent`, or `unknown`. Same vocabulary as `callers[].type`.
`talk_ratio.caller_ratios[].id`	string	The participant’s id. Absent for `unknown`.
`talk_ratio.caller_ratios[].ratio`	number	This participant’s share of the talking, as a percentage of the recording length.
`talk_ratio.caller_ratios[].talking_time`	number	Seconds this participant spent talking.
`call_score`	object	The call’s score with its scorecard breakdown. Present only for calls scored against one of your scoring templates, which is a minority of calls; absent means the call was not scored. Not covered by `complete`.
`call_score.overall_call_score`	number \| null	The overall score, 0 to 100.
`call_score.overall_summary`	string	The scoring model’s narrative for the whole call.
`call_score.template_id`	string	The id of the scoring template used. The template’s name and question texts are not included; look them up in CloudTalk.
`call_score.groups`	object[]	The scorecard’s sections, in template order.
`call_score.groups[].id`	string	The section’s id within the template.
`call_score.groups[].name`	string	Your label for the section.
`call_score.groups[].score`	number	The section’s percentage, 0 to 100: the mean of its answered questions, where YES scores 100, NO scores 0, and a 1 to 5 point scores 20 per point. Absent for a section the model could not score.
`call_score.groups[].status`	string	The section’s scoring outcome, as labelled by the scoring model. Free text; tolerate values you haven’t seen.
`call_score.groups[].summary`	string	The model’s narrative for this section.
`call_score.groups[].questions`	object[]	The section’s answered questions, ordered by question id.
`call_score.groups[].questions[].id`	string	The question’s id within the template. The question text is not included.
`call_score.groups[].questions[].answer`	string \| number \| null	The model’s answer: a label such as `YES` or `NO` for a yes/no question, a number from 1 to 5 for a scale question, `null` when the model did not answer.
`call_score.groups[].questions[].summary`	string	The model’s justification for the answer.

The transcript is deliberately not part of cidata.ready: it’s usually ready earlier and is announced by its own transcript.ready event, so transcript-driven workflows don’t wait for the slowest analysis stage. Likewise, the verbatim transcript quotes behind each scorecard answer are not included; fetch the transcript by reference if you need them.

​The callers object

​transcript.ready

​cidata.ready

The callers object

transcript.ready

cidata.ready