Для AI-агентов: markdown этой страницы — /docs-content/calls/followup/list.md индекс документации — /llms.txt

Список Follow-up

POST /v1/calls/followups/list

Возвращает список AI Follow-up завершённых звонков за указанный период. Навигация по выдаче — курсорная.

Поля запроса (body)

Поле Тип Обяз. Описание
Полеfilter Типobject Обяз.да ОписаниеУсловия выборки. Без этого объекта запрос отклоняется
Полеfilter.startDate.from Типstring Обяз.да ОписаниеНачало периода, ISO 8601 — 2026-01-01T00:00:00Z
Полеfilter.startDate.to Типstring Обяз.да ОписаниеКонец периода, ISO 8601. Значение раньше from отклоняется
Полеfilter.participantId Типinteger Обяз.нет ОписаниеВыборка по одному участнику. Только для администратора портала: рядовому сотруднику фильтр по другому участнику недоступен. Список сотрудников — GET /v1/users
Полеselect Типstring[] Обяз.нет ОписаниеКакие поля вернуть. Словарь значений — в разделе «Поле select»
Полеorder Типobject Обяз.нет ОписаниеСортировка по дате начала: { "startDate": "asc" } или { "startDate": "desc" }. По умолчанию — desc
Полеpagination Типobject Обяз.нет ОписаниеРазмер страницы и курсор. Правила — в разделе «Навигация»
Полеpagination.limit Типinteger Обяз.нет ОписаниеЗаписей на страницу. По умолчанию 50, максимум 200. При выборе полей с большим объёмом данных максимум снижается до 20
Полеpagination.afterCursor Типobject Обяз.нет ОписаниеКурсор следующей страницы. Копируется целиком из data.afterCursor предыдущего ответа. В первом запросе не передаётся
ПолеmentionFormat Типstring Обяз.нет ОписаниеФормат @-упоминаний в текстовых полях: bb, html или none. По умолчанию — bb

Поле select

Без select возвращаются только метаданные звонка. Остальные поля запрашиваются явно. Неизвестное значение отклоняется с 422 BITRIX_ERROR, error.b24Code: "invalid_select_field" и сообщением, которое называет отклонённое поле.

Метаданные

Значение Что вернётся
ЗначениеcallId, callType, initiatorId, startDate, endDate, durationSeconds Что вернётсяБазовые поля. В списке возвращаются всегда
Значениеuuid Что вернётсяИдентификатор сессии звонка
Значениеparticipants Что вернётсяСписок участников
Значениеtracks Что вернётсяЗаписи звонка со ссылками на скачивание
Значениеoutcomes Что вернётсяПеречень готовых AI-блоков
Значениеlanguage Что вернётсяЯзык транскрипции
Значениеversion Что вернётсяВерсия схемы AI-данных
ЗначениеcreatedAt Что вернётсяВремя последней AI-записи

AI-блоки

Блок запрашивается целиком или отдельным подполем через точку.

Блок Подполя
Блокtranscription Подполяtranscription.language, transcription.segments
Блокoverview Подполяoverview.topic, overview.detailedTakeaways, overview.meetingType, overview.agenda, overview.agreements, overview.actionItems, overview.meetings
Блокsummary ПодполяЗапрашивается только целиком
Блокinsights Подполяinsights.speakerEvaluationAvailable, insights.speakerAnalysis, insights.meetingStrengths, insights.meetingWeaknesses, insights.speechStyleInfluence, insights.engagementLevel, insights.areasOfResponsibility, insights.finalRecommendations
Блокevaluation Подполяevaluation.efficiencyValue, evaluation.calendar, evaluation.criteria

Правила выбора:

  • Запрос блока целиком (["overview"]) возвращает все его подполя.
  • Запрос подполя (["overview.topic"]) возвращает только это подполе, остальные опускаются.
  • transcription, transcription.segments, overview и insights содержат много данных. Их выбор снижает максимальный размер страницы до 20 записей.

Навигация

  1. Первый запрос отправляется без pagination.afterCursor.
  2. Если в ответе hasMore равно true, скопируйте data.afterCursor целиком в pagination.afterCursor следующего запроса.
  3. Повторяйте, пока hasMore не станет false.

pagination.limit — по умолчанию 50, максимум 200. При выборе полей с большим объёмом данных максимум снижается до 20.

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

Формат упоминаний

mentionFormat управляет тем, как выглядят @-упоминания сотрудников во всех текстовых AI-полях — transcription.segments[].text, overview.*, insights.*, evaluation.criteria.*.thoughts.

Значение Текст в ответе Когда выбирать
Значениеbb Текст в ответе[USER=7]Иван Петров[/USER] Когда выбиратьВывод в интерфейсе, который понимает BB-код
Значениеhtml Текст в ответе<span class="bx-call-mention" …>Иван Петров</span> Когда выбиратьВывод в вебе
Значениеnone Текст в ответеИван Петров Когда выбиратьПередача текста в нейросеть, поиск, экспорт

Примеры

Разбор встреч одного сотрудника за январь: берём метаданные звонка, тему, договорённости и задачи из обзора, разбор участников и общую оценку. Сортировка — от новых к старым, упоминания приходят чистым текстом. Это первый запрос, поэтому afterCursor в нём нет — курсор для следующей страницы придёт в ответе.

curl — личный ключ

Terminal
curl -X POST https://vibecode.bitrix24.tech/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-приложение

Terminal
curl -X POST https://vibecode.bitrix24.tech/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 — личный ключ

javascript
const res = await fetch('https://vibecode.bitrix24.tech/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) {
  // Ошибку разбираем явно: иначе на 403 или 422 код упадёт на обращении к data
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

const { data } = body

for (const call of data.items) {
  // AI-блоки готовы не у каждого звонка: у части из них приходит null
  const topic = call.overview?.topic ?? 'тема не определена'
  const score = call.evaluation?.efficiencyValue ?? '—'
  console.log(call.startDate, topic, `оценка: ${score}`)

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

// Следующая страница: курсор из ответа кладём в pagination.afterCursor нового запроса
console.log(data.hasMore, data.afterCursor)

JavaScript — OAuth-приложение

javascript
const res = await fetch('https://vibecode.bitrix24.tech/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) {
  // Ошибку разбираем явно: иначе на 403 или 422 код упадёт на обращении к data
  throw new Error(`${body.error.code}: ${body.error.message}`)
}

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

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.items Типobject[] ОписаниеМассив Follow-up. Поля элемента — в таблице ниже
Полеdata.hasMore Типboolean ОписаниеЕсть ли записи за пределами текущей страницы
Полеdata.afterCursor Типobject | null ОписаниеКурсор следующей страницы. null — записей больше нет

Поля элемента массива:

Поле Тип Описание
Полеitems[].callId Типnumber ОписаниеИдентификатор звонка. Передаётся в GET /v1/calls/followups/:callId
Полеitems[].callType Типnumber ОписаниеВид звонка: 1 — мгновенный, 2 — конференция, 3 — большая комната
Полеitems[].initiatorId Типnumber ОписаниеИнициатор звонка. Карточка сотрудника — GET /v1/users/:id
Полеitems[].startDate Типstring ОписаниеНачало звонка, ISO 8601 в UTC
Полеitems[].endDate Типstring | null ОписаниеОкончание звонка, ISO 8601 в UTC
Полеitems[].durationSeconds Типnumber ОписаниеДлительность звонка в секундах
Полеitems[].uuid Типstring ОписаниеИдентификатор сессии звонка
Полеitems[].language Типstring ОписаниеКод языка транскрипции
Полеitems[].version Типnumber ОписаниеВерсия схемы AI-данных
Полеitems[].participants Типobject[] ОписаниеУчастники звонка
Полеitems[].outcomes Типstring[] ОписаниеГотовые AI-блоки этого звонка
Полеitems[].createdAt Типstring ОписаниеВремя последней AI-записи
Полеitems[].tracks Типobject[] ОписаниеЗаписи звонка
Полеitems[].transcription Типobject ОписаниеТранскрипция разговора
Полеitems[].overview Типobject ОписаниеОбзор встречи
Полеitems[].summary Типobject ОписаниеКраткое изложение по фрагментам
Полеitems[].evaluation Типobject ОписаниеОценка эффективности встречи
Полеitems[].insights Типobject ОписаниеАналитические выводы и разбор участников

Участники — `participants[]`

Поле Тип Описание
ПолеuserId Типnumber ОписаниеИдентификатор сотрудника
Полеname Типstring ОписаниеИмя сотрудника
Полеavatar Типstring ОписаниеСсылка на аватар
ПолеworkPosition Типstring ОписаниеДолжность
ПолеtalkedSeconds Типnumber ОписаниеСколько секунд участник говорил. Разбор из insights для этого поля не нужен, а в самом разборе время участника приходит в insights.speakerAnalysis[].duration

Записи звонка — `tracks[]`

Поле Тип Описание
ПолеtrackId Типnumber ОписаниеИдентификатор записи
Полеtype Типstring ОписаниеВид дорожки, например mixed_audio
Полеduration Типnumber ОписаниеДлительность записи в секундах
ПолеfileName Типstring ОписаниеИмя файла
ПолеmimeType Типstring ОписаниеMIME-тип файла
Полеurl Типstring ОписаниеСсылка на скачивание
ПолеdateCreate Типstring ОписаниеКогда запись создана, ISO 8601

Транскрипция — `transcription`

Поле Тип Описание
Полеlanguage Типstring ОписаниеКод языка расшифровки
Полеsegments[] Типobject[] ОписаниеРеплики в хронологическом порядке
Полеsegments[].userId Типnumber ОписаниеКто говорит
Полеsegments[].userName Типstring ОписаниеИмя говорящего
Полеsegments[].start Типnumber ОписаниеНачало реплики, секунды от начала звонка
Полеsegments[].end Типnumber ОписаниеКонец реплики, секунды от начала звонка
Полеsegments[].text Типstring ОписаниеТекст реплики

Обзор встречи — `overview`

Поле Тип Описание
Полеtopic Типstring ОписаниеТема встречи
ПолеdetailedTakeaways Типstring ОписаниеРазвёрнутые выводы
ПолеmeetingType Типobject ОписаниеТип встречи: typeTag — код, title — название, explanation — обоснование
Полеagenda Типobject ОписаниеПовестка: explanation — формулировка, quote — цитата из разговора
Полеagreements[] Типobject[] ОписаниеДоговорённости: agreement — формулировка, quote — цитата
ПолеactionItems[] Типobject[] ОписаниеЗадачи: actionItem — формулировка, quote — цитата
Полеmeetings[] Типobject[] ОписаниеНазначенные встречи: meeting — формулировка, quote — цитата

Краткое изложение — `summary`

Поле Тип Описание
Полеsegments[] Типobject[] ОписаниеФрагменты разговора
Полеsegments[].start Типnumber ОписаниеНачало фрагмента, секунды
Полеsegments[].end Типnumber ОписаниеКонец фрагмента, секунды
Полеsegments[].title Типstring ОписаниеЗаголовок фрагмента
Полеsegments[].summary Типstring ОписаниеИзложение фрагмента

Аналитические выводы — `insights`

Поле Тип Описание
ПолеspeakerEvaluationAvailable Типboolean ОписаниеДоступен ли разбор участников на портале
ПолеspeakerAnalysis[] Типobject[] ОписаниеРазбор участников, по убыванию talkPercentage
ПолеspeakerAnalysis[].userId Типnumber ОписаниеИдентификатор сотрудника. Карточка — GET /v1/users/:id
ПолеspeakerAnalysis[].detailedInsight Типstring ОписаниеВывод по участнику
ПолеspeakerAnalysis[].efficiencyValue Типnumber ОписаниеОценка эффективности участника, от 0 до 100
ПолеspeakerAnalysis[].evaluationCriteria Типstring ОписаниеКритерий, по которому дана оценка
ПолеspeakerAnalysis[].talkPercentage Типnumber ОписаниеДоля времени, которую участник говорил, в процентах
ПолеspeakerAnalysis[].duration Типnumber ОписаниеСколько секунд участник говорил, в составе разбора участника. Вне блока insights время участника приходит в поле participants[].talkedSeconds
ПолеspeakerAnalysis[].durationFormat Типstring ОписаниеТо же время в виде ММ:СС
ПолеmeetingStrengths[] Типobject[] ОписаниеСильные стороны: strengthTitle и strengthExplanation
ПолеmeetingWeaknesses[] Типobject[] ОписаниеСлабые стороны: weaknessTitle и weaknessExplanation
ПолеspeechStyleInfluence Типstring ОписаниеКак манера речи повлияла на встречу
ПолеengagementLevel Типstring ОписаниеВовлечённость участников
ПолеareasOfResponsibility Типstring ОписаниеКто за что отвечает по итогам
ПолеfinalRecommendations Типstring ОписаниеРекомендации к следующей встрече

Оценка эффективности — `evaluation`

Поле Тип Описание
ПолеefficiencyValue Типnumber ОписаниеОбщая эффективность встречи, от 0 до 100
Полеcalendar.overhead Типboolean ОписаниеБыла ли встреча избыточной по времени
Полеcriteria Типobject ОписаниеКарта критериев. Ключ — код критерия, значение — объект с полями ниже
Полеcriteria.<код>.value Типboolean ОписаниеВыполнен ли критерий
Полеcriteria.<код>.title Типstring ОписаниеНазвание критерия
Полеcriteria.<код>.criteria Типstring ОписаниеФормулировка критерия
Полеcriteria.<код>.thoughts Типstring ОписаниеОбоснование оценки

Пример ответа

Ответ на запрос из примеров выше. Базовые поля звонка приходят всегда, а из AI-блоков вернулось ровно то, что перечислено в select: внутри overview — только тема, договорённости и задачи, внутри insights — только разбор участников, внутри evaluation — только общая оценка. Упоминания сотрудников идут чистым текстом, потому что запрошен mentionFormat: "none".

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": "Иван Петров", "avatar": "https://example.bitrix24.ru/upload/avatar.png", "workPosition": "Руководитель проекта", "talkedSeconds": 600 },
          { "userId": 42, "name": "Мария Иванова", "avatar": "https://example.bitrix24.ru/upload/avatar-2.png", "workPosition": "Разработчик", "talkedSeconds": 1200 }
        ],
        "outcomes": ["transcription", "overview", "summary", "insights", "evaluation"],
        "overview": {
          "topic": "Планирование спринта",
          "agreements": [
            { "agreement": "В спринт берём только импорт каталога", "quote": "Предлагаю оставить только импорт каталога, остальное не успеем." }
          ],
          "actionItems": [
            { "actionItem": "Подготовить прототип к пятнице", "quote": "Тогда прототип показываем в пятницу." }
          ]
        },
        "insights": {
          "speakerAnalysis": [
            { "userId": 42, "detailedInsight": "Участник предложил сократить объём и обосновал это оценкой сроков.", "efficiencyValue": 82, "evaluationCriteria": "Конструктивность предложений", "talkPercentage": 66, "duration": 1200, "durationFormat": "20:00" },
            { "userId": 7, "detailedInsight": "Участник вёл встречу и зафиксировал договорённости.", "efficiencyValue": 74, "evaluationCriteria": "Управление обсуждением", "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": "Мария Иванова", "avatar": "https://example.bitrix24.ru/upload/avatar-2.png", "workPosition": "Разработчик", "talkedSeconds": 900 }
        ],
        "outcomes": ["transcription", "overview"],
        "overview": {
          "topic": "Разбор обращений за неделю",
          "agreements": [],
          "actionItems": [
            { "actionItem": "Собрать частые вопросы в базу знаний", "quote": "Давай соберём повторяющиеся вопросы в одну статью." }
          ]
        },
        "insights": null,
        "evaluation": null
      }
    ],
    "hasMore": true,
    "afterCursor": { "startDate": "2026-01-12T09:00:00.000000+00:00", "id": 12318 }
  }
}

Второй звонок показывает частый случай: у него готовы не все AI-блоки. В outcomes перечислено то, что сформировано, а запрошенные, но отсутствующие блоки приходят как null — проверяйте их перед обращением к полям.

Как выглядит звонок со всеми заполненными блоками, показано на странице Follow-up по одному звонку.

Пример ответа при ошибке

400 — в теле запроса нет объекта filter:

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

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_PARAMS ОписаниеВ теле запроса нет объекта filter
HTTP400 КодINVALID_PARAMS ОписаниеЗначение поля запроса вне списка допустимых — например mentionFormat. Если Битрикс24 отклонил значение по полю, ответ дополнительно содержит массив error.validation с именем поля
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет токенов портала. Ключ OAuth-приложения требует заголовок Authorization: Bearer
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа call
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе. Частый случай — набор скоупов, с которым ключ обращается к порталу, не содержит call. Полный разбор причин и что делать по типу ключа — Ошибки
HTTP422 КодBITRIX_ERROR ОписаниеНедопустимое поле в select — error.b24Code равен invalid_select_field, сообщение называет поле
HTTP422 КодBITRIX_ERROR ОписаниеЗапрос отклонён: некорректный диапазон дат, недопустимое поле в select, некорректные pagination или order, нет доступа к данным. Причина — в error.message
HTTP429 КодRATE_LIMITED ОписаниеПревышена частота запросов на стороне Битрикс24
HTTP429 КодQUEUE_OVERFLOW, QUEUE_TIMEOUT ОписаниеОчередь запросов портала переполнена или запрос не дождался очереди. Заголовок Retry-After подсказывает задержку перед повтором
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 принял запрос, но не ответил за 60 секунд. Для чтения повтор безопасен
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 недоступен

Полный список общих ошибок API — Ошибки.

Известные особенности

Звонки без AI-обработки в список не попадают. В выдаче только те звонки, по которым Follow-up уже сформирован. Пустой массив items означает, что за период таких звонков нет.

Неполный период отклоняется кодом 422, а не 400. Код 400 MISSING_PARAMS приходит только тогда, когда объекта filter нет в теле запроса вовсе. Пропущенный to или период, где from позже to, возвращают 422 BITRIX_ERROR с описанием причины.

Разбор участников доступен не на каждом портале. Если на портале он недоступен, блок insights приходит с speakerEvaluationAvailable: false и пустым разбором участников. Это не ошибка запроса — структура ответа не меняется.

Выдача ограничена правами сотрудника. Ключ возвращает Follow-up тех звонков, в которых владелец ключа участвовал или состоит в связанном чате. Администратор портала видит все звонки портала. Поэтому один и тот же период у разных сотрудников даёт разные списки.

Смотрите также