Для 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 записей.
Навигация
- Первый запрос отправляется без
pagination.afterCursor. - Если в ответе
hasMoreравноtrue, скопируйтеdata.afterCursorцеликом вpagination.afterCursorследующего запроса. - Повторяйте, пока
hasMoreне станетfalse.
pagination.limit — по умолчанию 50, максимум 200. При выборе полей с большим объёмом данных максимум снижается до 20.
{ "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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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".
{
"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:
{
"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 тех звонков, в которых владелец ключа участвовал или состоит в связанном чате. Администратор портала видит все звонки портала. Поэтому один и тот же период у разных сотрудников даёт разные списки.