لوكلاء AI: ملف markdown لهذه الصفحة — /docs-content-en/calls/followup.md فهرس التوثيق — /llms.txt

مقالات التوثيق متاحة حاليًا باللغة الإنجليزية فقط.

Call follow-up

Read the AI Follow-up of completed calls: transcription, meeting overview, summary, insights, and efficiency evaluation. The methods only read data and change nothing.

Scope: call | Base URL: https://vibecode.bitrix24.com/v1 | Authorization: X-Api-Key

Follow-up list

POST /v1/calls/followups/list

Returns a list of AI Follow-ups for completed calls within the specified period. Pagination is cursor-based.

Request fields (body)

Field Type Required Description
Fieldfilter Typeobject Requiredyes DescriptionFilter conditions. Without this object the request is rejected
Fieldfilter.startDate.from Typestring Requiredyes DescriptionStart of the period, ISO 8601 — 2026-01-01T00:00:00Z
Fieldfilter.startDate.to Typestring Requiredyes DescriptionEnd of the period, ISO 8601. A value earlier than from is rejected
Fieldfilter.participantId Typeinteger Requiredno DescriptionFilter by a single participant. Available to the Bitrix24 account administrator only: a regular employee cannot filter by another participant. List of employees — GET /v1/users
Fieldselect Typestring[] Requiredno DescriptionWhich fields to return. Allowed values — in the "Select field" section
Fieldorder Typeobject Requiredno DescriptionSorting by start date: { "startDate": "asc" } or { "startDate": "desc" }. Defaults to desc
Fieldpagination Typeobject Requiredno DescriptionPage size and cursor. Rules — in the "Navigation" section
Fieldpagination.limit Typeinteger Requiredno DescriptionRecords per page. Defaults to 50, maximum 200. Selecting data-heavy fields lowers the maximum to 20
Fieldpagination.afterCursor Typeobject Requiredno DescriptionCursor of the next page. Copied as a whole from data.afterCursor of the previous response. Not passed in the first request
FieldmentionFormat Typestring Requiredno DescriptionFormat of @-mentions in text fields: bb, html or none. Defaults to bb

Select field

Without select, only call metadata is returned. All other fields must be requested explicitly. An unknown value is rejected with 422 BITRIX_ERROR, error.b24Code: "invalid_select_field", and a message that names the rejected field.

Metadata

Value What is returned
ValuecallId, callType, initiatorId, startDate, endDate, durationSeconds What is returnedBase fields. Always returned in the list
Valueuuid What is returnedCall session identifier
Valueparticipants What is returnedList of participants
Valuetracks What is returnedCall recordings with download links
Valueoutcomes What is returnedList of the AI blocks that are ready
Valuelanguage What is returnedTranscription language
Valueversion What is returnedVersion of the AI data schema
ValuecreatedAt What is returnedTime of the last AI record

AI blocks

A block is requested either as a whole or as an individual subfield using dot notation.

Block Subfields
Blocktranscription Subfieldstranscription.language, transcription.segments
Blockoverview Subfieldsoverview.topic, overview.detailedTakeaways, overview.meetingType, overview.agenda, overview.agreements, overview.actionItems, overview.meetings
Blocksummary SubfieldsRequested only as a whole
Blockinsights Subfieldsinsights.speakerEvaluationAvailable, insights.speakerAnalysis, insights.meetingStrengths, insights.meetingWeaknesses, insights.speechStyleInfluence, insights.engagementLevel, insights.areasOfResponsibility, insights.finalRecommendations
Blockevaluation Subfieldsevaluation.efficiencyValue, evaluation.calendar, evaluation.criteria

Selection rules:

  • Requesting a whole block (["overview"]) returns all of its subfields.
  • Requesting a subfield (["overview.topic"]) returns only that subfield — the rest are omitted.
  • transcription, transcription.segments, overview and insights contain a lot of data. Selecting them lowers the maximum page size to 20 records.
  1. The first request is sent without pagination.afterCursor.
  2. If hasMore in the response is true, copy the whole data.afterCursor object into pagination.afterCursor of the next request.
  3. Repeat until hasMore becomes false.

pagination.limit — defaults to 50, maximum 200. Selecting data-heavy fields lowers the maximum to 20.

jsonc 
{ "pagination": { "limit": 50, "afterCursor": { "startDate": "2026-01-12T14:30:00.000000+00:00", "id": 12330 } } }

Mention format

mentionFormat controls how @-mentions of employees look in all AI text fields — transcription.segments[].text, overview.*, insights.*, evaluation.criteria.*.thoughts.

Value Text in the response When to choose
Valuebb Text in the response[USER=7]John Smith[/USER] When to chooseRendering in an interface that supports BB code
Valuehtml Text in the response<span class="bx-call-mention" …>John Smith</span> When to chooseRendering on the web
Valuenone Text in the responseJohn Smith When to choosePassing the text to an AI model, search, export

Examples

A review of one employee's meetings for January: we take the call metadata, the topic, the agreements and the action items from the overview, plus the participant analysis and the overall score. Results are sorted newest first, and mentions arrive as plain text. This is the first request, so it has no afterCursor — the cursor for the next page arrives in the response.

curl — personal key

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/followups/list \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "startDate": { "from": "2026-01-01T00:00:00Z", "to": "2026-01-31T23:59:59Z" },
      "participantId": 42
    },
    "select": [
      "callId", "startDate", "durationSeconds", "participants", "outcomes",
      "overview.topic", "overview.agreements", "overview.actionItems",
      "insights.speakerAnalysis", "evaluation.efficiencyValue"
    ],
    "order": { "startDate": "desc" },
    "pagination": { "limit": 20 },
    "mentionFormat": "none"
  }'

curl — OAuth application

Terminal 
curl -X POST https://vibecode.bitrix24.com/v1/calls/followups/list \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "startDate": { "from": "2026-01-01T00:00:00Z", "to": "2026-01-31T23:59:59Z" },
      "participantId": 42
    },
    "select": [
      "callId", "startDate", "durationSeconds", "participants", "outcomes",
      "overview.topic", "overview.agreements", "overview.actionItems",
      "insights.speakerAnalysis", "evaluation.efficiencyValue"
    ],
    "order": { "startDate": "desc" },
    "pagination": { "limit": 20 },
    "mentionFormat": "none"
  }'

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/followups/list', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: {
      startDate: { from: '2026-01-01T00:00:00Z', to: '2026-01-31T23:59:59Z' },
      participantId: 42,
    },
    select: [
      'callId', 'startDate', 'durationSeconds', 'participants', 'outcomes',
      'overview.topic', 'overview.agreements', 'overview.actionItems',
      'insights.speakerAnalysis', 'evaluation.efficiencyValue',
    ],
    order: { startDate: 'desc' },
    pagination: { limit: 20 },
    mentionFormat: 'none',
  }),
})

const body = await res.json()

if (!body.success) {
  // Handle the error explicitly: otherwise on 403 or 422 the code fails when accessing data
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

const { data } = body

for (const call of data.items) {
  // AI blocks are not ready for every call: some of them arrive as null
  const topic = call.overview?.topic ?? 'topic not determined'
  const score = call.evaluation?.efficiencyValue ?? '—'
  console.log(call.startDate, topic, `score: ${score}`)

  for (const item of call.overview?.actionItems ?? []) {
    console.log('  action item:', item.actionItem)
  }
}

// Next page: put the cursor from the response into pagination.afterCursor of the new request
console.log(data.hasMore, data.afterCursor)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/calls/followups/list', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: {
      startDate: { from: '2026-01-01T00:00:00Z', to: '2026-01-31T23:59:59Z' },
      participantId: 42,
    },
    select: [
      'callId', 'startDate', 'durationSeconds', 'participants', 'outcomes',
      'overview.topic', 'overview.agreements', 'overview.actionItems',
      'insights.speakerAnalysis', 'evaluation.efficiencyValue',
    ],
    order: { startDate: 'desc' },
    pagination: { limit: 20 },
    mentionFormat: 'none',
  }),
})

const body = await res.json()

if (!body.success) {
  // Handle the error explicitly: otherwise on 403 or 422 the code fails when accessing data
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

const { data } = body
console.log(data.items, data.hasMore, data.afterCursor)

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata.items Typeobject[] DescriptionArray of Follow-ups. Element fields — in the table below
Fielddata.hasMore Typeboolean DescriptionWhether there are records beyond the current page
Fielddata.afterCursor Typeobject | null DescriptionCursor of the next page. null — there are no more records

Fields of an array element:

Field Type Description
Fielditems[].callId Typenumber DescriptionCall identifier. Passed to GET /v1/calls/followups/:callId
Fielditems[].callType Typenumber DescriptionCall type: 1 — instant, 2 — conference, 3 — large room
Fielditems[].initiatorId Typenumber DescriptionCall initiator. Employee profile — GET /v1/users/:id
Fielditems[].startDate Typestring DescriptionCall start, ISO 8601 in UTC
Fielditems[].endDate Typestring | null DescriptionCall end, ISO 8601 in UTC
Fielditems[].durationSeconds Typenumber DescriptionCall duration in seconds
Fielditems[].uuid Typestring DescriptionCall session identifier
Fielditems[].language Typestring DescriptionTranscription language code
Fielditems[].version Typenumber DescriptionVersion of the AI data schema
Fielditems[].participants Typeobject[] DescriptionCall participants
Fielditems[].outcomes Typestring[] DescriptionAI blocks already generated for this call
Fielditems[].createdAt Typestring DescriptionTime of the last AI record
Fielditems[].tracks Typeobject[] DescriptionCall recordings
Fielditems[].transcription Typeobject DescriptionTranscription of the conversation
Fielditems[].overview Typeobject DescriptionMeeting overview
Fielditems[].summary Typeobject DescriptionFragment-by-fragment summary
Fielditems[].evaluation Typeobject DescriptionMeeting efficiency score
Fielditems[].insights Typeobject DescriptionInsights and participant analysis

Participants — `participants[]`

Field Type Description
FielduserId Typenumber DescriptionEmployee identifier
Fieldname Typestring DescriptionEmployee name
Fieldavatar Typestring DescriptionLink to the avatar
FieldworkPosition Typestring DescriptionJob title
FieldtalkedSeconds Typenumber DescriptionHow many seconds the participant spoke. Returned without requesting the participant analysis from insights. Inside that analysis, the participant's time arrives in insights.speakerAnalysis[].duration

Call recordings — `tracks[]`

Field Type Description
FieldtrackId Typenumber DescriptionRecording identifier
Fieldtype Typestring DescriptionTrack type, for example mixed_audio
Fieldduration Typenumber DescriptionRecording duration in seconds
FieldfileName Typestring DescriptionFile name
FieldmimeType Typestring DescriptionMIME type of the file
Fieldurl Typestring DescriptionDownload link
FielddateCreate Typestring DescriptionWhen the recording was created, ISO 8601

Transcription — `transcription`

Field Type Description
Fieldlanguage Typestring DescriptionTranscript language code
Fieldsegments[] Typeobject[] DescriptionUtterances in chronological order
Fieldsegments[].userId Typenumber DescriptionWho is speaking
Fieldsegments[].userName Typestring DescriptionSpeaker name
Fieldsegments[].start Typenumber DescriptionStart of the utterance, seconds from the start of the call
Fieldsegments[].end Typenumber DescriptionEnd of the utterance, seconds from the start of the call
Fieldsegments[].text Typestring DescriptionText of the utterance

Meeting overview — `overview`

Field Type Description
Fieldtopic Typestring DescriptionMeeting topic
FielddetailedTakeaways Typestring DescriptionDetailed takeaways
FieldmeetingType Typeobject DescriptionMeeting type: typeTag — code, title — name, explanation — justification
Fieldagenda Typeobject DescriptionAgenda: explanation — wording, quote — quote from the conversation
Fieldagreements[] Typeobject[] DescriptionAgreements: agreement — wording, quote — quote
FieldactionItems[] Typeobject[] DescriptionAction items: actionItem — wording, quote — quote
Fieldmeetings[] Typeobject[] DescriptionScheduled meetings: meeting — wording, quote — quote

Summary — `summary`

Field Type Description
Fieldsegments[] Typeobject[] DescriptionFragments of the conversation
Fieldsegments[].start Typenumber DescriptionStart of the fragment, seconds
Fieldsegments[].end Typenumber DescriptionEnd of the fragment, seconds
Fieldsegments[].title Typestring DescriptionFragment title
Fieldsegments[].summary Typestring DescriptionSummary of the fragment

Insights — `insights`

Field Type Description
FieldspeakerEvaluationAvailable Typeboolean DescriptionWhether participant analysis is available on the Bitrix24 account
FieldspeakerAnalysis[] Typeobject[] DescriptionParticipant analysis, in descending order of talkPercentage
FieldspeakerAnalysis[].userId Typenumber DescriptionEmployee identifier. Profile — GET /v1/users/:id
FieldspeakerAnalysis[].detailedInsight Typestring DescriptionConclusion about the participant
FieldspeakerAnalysis[].efficiencyValue Typenumber DescriptionParticipant efficiency score, from 0 to 100
FieldspeakerAnalysis[].evaluationCriteria Typestring DescriptionThe criterion the score was based on
FieldspeakerAnalysis[].talkPercentage Typenumber DescriptionShare of the time the participant spoke, in percent
FieldspeakerAnalysis[].duration Typenumber DescriptionHow many seconds the participant spoke, as part of the participant analysis. Outside the insights block the participant's time arrives in the participants[].talkedSeconds field
FieldspeakerAnalysis[].durationFormat Typestring DescriptionThe same time in MM:SS format
FieldmeetingStrengths[] Typeobject[] DescriptionStrengths: strengthTitle and strengthExplanation
FieldmeetingWeaknesses[] Typeobject[] DescriptionWeaknesses: weaknessTitle and weaknessExplanation
FieldspeechStyleInfluence Typestring DescriptionHow the speaking style influenced the meeting
FieldengagementLevel Typestring DescriptionEngagement of the participants
FieldareasOfResponsibility Typestring DescriptionWho is responsible for what after the meeting
FieldfinalRecommendations Typestring DescriptionRecommendations for the next meeting

Efficiency score — `evaluation`

Field Type Description
FieldefficiencyValue Typenumber DescriptionOverall meeting efficiency, from 0 to 100
Fieldcalendar.overhead Typeboolean DescriptionWhether the meeting ran longer than necessary
Fieldcriteria Typeobject DescriptionMap of criteria. The key is the criterion code, the value is an object with the fields below
Fieldcriteria.<code>.value Typeboolean DescriptionWhether the criterion is met
Fieldcriteria.<code>.title Typestring DescriptionCriterion name
Fieldcriteria.<code>.criteria Typestring DescriptionCriterion wording
Fieldcriteria.<code>.thoughts Typestring DescriptionJustification of the score

Response example

The response to the request from the examples above. Base call fields always arrive, and the AI blocks contain exactly what is listed in select: inside overview — only the topic, the agreements and the action items, inside insights — only the participant analysis, inside evaluation — only the overall score. Employee mentions arrive as plain text, because mentionFormat: "none" was requested.

JSON 
{
  "success": true,
  "data": {
    "items": [
      {
        "callId": 12345,
        "callType": 1,
        "initiatorId": 7,
        "startDate": "2026-01-15T10:00:00+00:00",
        "endDate": "2026-01-15T10:42:00+00:00",
        "durationSeconds": 2520,
        "participants": [
          { "userId": 7, "name": "John Smith", "avatar": "https://example.bitrix24.com/upload/avatar.png", "workPosition": "Project manager", "talkedSeconds": 600 },
          { "userId": 42, "name": "Mary Jones", "avatar": "https://example.bitrix24.com/upload/avatar-2.png", "workPosition": "Developer", "talkedSeconds": 1200 }
        ],
        "outcomes": ["transcription", "overview", "summary", "insights", "evaluation"],
        "overview": {
          "topic": "Sprint planning",
          "agreements": [
            { "agreement": "Only the catalog import goes into the sprint", "quote": "I suggest we keep only the catalog import — we won't have time for the rest." }
          ],
          "actionItems": [
            { "actionItem": "Prepare the prototype by Friday", "quote": "Then we show the prototype on Friday." }
          ]
        },
        "insights": {
          "speakerAnalysis": [
            { "userId": 42, "detailedInsight": "The participant proposed cutting the scope and backed it with a deadline estimate.", "efficiencyValue": 82, "evaluationCriteria": "Constructiveness of proposals", "talkPercentage": 66, "duration": 1200, "durationFormat": "20:00" },
            { "userId": 7, "detailedInsight": "The participant ran the meeting and recorded the agreements.", "efficiencyValue": 74, "evaluationCriteria": "Discussion management", "talkPercentage": 34, "duration": 600, "durationFormat": "10:00" }
          ]
        },
        "evaluation": {
          "efficiencyValue": 75
        }
      },
      {
        "callId": 12318,
        "callType": 2,
        "initiatorId": 42,
        "startDate": "2026-01-12T09:00:00+00:00",
        "endDate": "2026-01-12T09:25:00+00:00",
        "durationSeconds": 1500,
        "participants": [
          { "userId": 42, "name": "Mary Jones", "avatar": "https://example.bitrix24.com/upload/avatar-2.png", "workPosition": "Developer", "talkedSeconds": 900 }
        ],
        "outcomes": ["transcription", "overview"],
        "overview": {
          "topic": "Review of the week's support requests",
          "agreements": [],
          "actionItems": [
            { "actionItem": "Collect frequent questions into the knowledge base", "quote": "Let's collect the recurring questions into one article." }
          ]
        },
        "insights": null,
        "evaluation": null
      }
    ],
    "hasMore": true,
    "afterCursor": { "startDate": "2026-01-12T09:00:00.000000+00:00", "id": 12318 }
  }
}

The second call shows a common case: not all of its AI blocks are ready. outcomes lists what has been generated, and blocks that were requested but are absent arrive as null — check them before accessing their fields.

See the Follow-up for a single call page for a call with all of its blocks filled in.

Error response example

400 — the request body has no filter object:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: filter.startDate.from/to (ISO 8601)"
  }
}

Errors

HTTP Code Description
HTTP400 CodeMISSING_PARAMS DescriptionThe request body has no filter object
HTTP400 CodeINVALID_PARAMS DescriptionThe value of a request field is not in the list of allowed values — mentionFormat, for example. If Bitrix24 rejected the value of a specific field, the response additionally contains an error.validation array with the field name
HTTP401 CodeMISSING_API_KEY DescriptionThe X-Api-Key header was not passed
HTTP401 CodeTOKEN_MISSING DescriptionThe key has no portal tokens. An OAuth application key requires the Authorization: Bearer header
HTTP403 CodeSCOPE_DENIED DescriptionThe key has no call scope
HTTP403 CodeBITRIX_ACCESS_DENIED DescriptionBitrix24 denied access. A common cause is that the set of scopes the key uses to reach the portal does not include call. The full list of causes and what to do per key type — Errors
HTTP422 CodeBITRIX_ERROR DescriptionUnsupported field in select — error.b24Code is invalid_select_field, and the message names the field
HTTP422 CodeBITRIX_ERROR DescriptionThe request was rejected: incorrect date range, disallowed field in select, incorrect pagination or order, no access to the data. The reason is in error.message
HTTP429 CodeRATE_LIMITED DescriptionRequest rate exceeded on the Bitrix24 side
HTTP429 CodeQUEUE_OVERFLOW, QUEUE_TIMEOUT DescriptionThe portal request queue is full or the request did not get through the queue in time. The Retry-After header suggests the delay before a retry
HTTP503 CodeBITRIX_TIMEOUT DescriptionBitrix24 accepted the request but did not respond within 60 seconds. Retrying a read request is safe
HTTP502 CodeBITRIX_UNAVAILABLE DescriptionBitrix24 is unavailable

The full list of common API errors — Errors.

Known specifics

Calls without AI processing do not appear in the list. The list contains only the calls for which a Follow-up has already been generated. An empty items array means there are no such calls for the period.

An incomplete period is rejected with code 422, not 400. The code 400 MISSING_PARAMS is returned only when there is no filter object in the request body at all. A missing to, or a period where from is later than to, returns 422 BITRIX_ERROR with a description of the reason.

Participant analysis is not available on every Bitrix24 account. When it is unavailable, the insights block comes back with speakerEvaluationAvailable: false and an empty participant analysis. This is not a request error — the response structure does not change.

Results are limited by the employee's permissions. The key returns Follow-ups of the calls in which the key owner took part, or whose linked chat the key owner belongs to. The Bitrix24 account administrator sees all calls of the account. That is why the same period gives different lists for different employees.

See also