Для AI-агентов: markdown этой страницы — /docs-content/calls/followup/get.md индекс документации — /llms.txt
Follow-up по одному звонку
GET /v1/calls/followups/:callId
Возвращает AI Follow-up одного завершённого звонка.
Параметры
| Параметр | Тип | Обяз. | Описание |
|---|---|---|---|
ПараметрcallId (path) |
Типinteger | Обяз.да | ОписаниеИдентификатор звонка. Положительное целое. Где взять — POST /v1/calls/followups/list |
Параметрselect (query) |
Типstring[] | Обяз.нет | ОписаниеКакие поля вернуть. Передаётся повторяющимся параметром или списком через запятую. Словарь значений общий со списком — раздел «Поле select» страницы Список Follow-up |
ПараметрmentionFormat (query) |
Типstring | Обяз.нет | ОписаниеФормат @-упоминаний в текстовых полях: bb, html или none. По умолчанию — bb |
Поле select
Значение select |
Что в ответе |
|---|---|
| Значение selectНе указан | Что в ответеПолный объект Follow-up. Присутствуют все поля, отсутствующие данные приходят как null |
| Значение selectПустой массив | Что в ответеТолько базовые метаданные: callId, callType, initiatorId, startDate, endDate, durationSeconds |
| Значение selectСписок полей | Что в ответеТолько перечисленные поля и всегда callId. Запрошенное, но незаполненное поле приходит как null |
Примеры
Запрос без select — возвращается весь Follow-up целиком. mentionFormat: none убирает разметку упоминаний, поэтому текст готов к передаче в нейросеть или к сохранению в задачу. Чтобы забрать только часть блоков, добавьте select — например ?select=overview.actionItems&select=evaluation.efficiencyValue.
curl — личный ключ
curl "https://vibecode.bitrix24.tech/v1/calls/followups/12345?mentionFormat=none" \
-H "X-Api-Key: YOUR_API_KEY"
curl — OAuth-приложение
curl "https://vibecode.bitrix24.tech/v1/calls/followups/12345?mentionFormat=none" \
-H "X-Api-Key: YOUR_APP_KEY" \
-H "Authorization: Bearer USER_SESSION_TOKEN"
JavaScript — личный ключ
const params = new URLSearchParams({ mentionFormat: 'none' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/followups/12345?${params}`, {
headers: { 'X-Api-Key': 'YOUR_API_KEY' },
})
const body = await res.json()
if (!body.success) {
// Ошибку разбираем явно: иначе на 403 или 422 код упадёт на обращении к data
throw new Error(`${body.error.code}: ${body.error.message}`)
}
const { data } = body
const call = data.item
// Готовые AI-блоки перечислены в outcomes, неготовые приходят как null
console.log(call.outcomes, `${call.durationSeconds} сек`)
console.log(call.overview?.topic ?? 'обзор ещё не сформирован')
for (const item of call.overview?.actionItems ?? []) {
console.log('задача:', item.actionItem, '— цитата:', item.quote)
}
// speakerAnalysis отсутствует, если разбор участников на портале недоступен
for (const speaker of call.insights?.speakerAnalysis ?? []) {
console.log(`участник ${speaker.userId}: ${speaker.talkPercentage}% времени, оценка ${speaker.efficiencyValue}`)
}
// Критерии — карта, ключи зависят от типа встречи: обходим по ключам
for (const [code, criterion] of Object.entries(call.evaluation?.criteria ?? {})) {
console.log(code, criterion.value ? 'выполнен' : 'не выполнен', '—', criterion.thoughts)
}
JavaScript — OAuth-приложение
const params = new URLSearchParams({ mentionFormat: 'none' })
const res = await fetch(`https://vibecode.bitrix24.tech/v1/calls/followups/12345?${params}`, {
headers: {
'X-Api-Key': 'YOUR_APP_KEY',
'Authorization': 'Bearer USER_SESSION_TOKEN',
},
})
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.item)
Поля ответа
| Поле | Тип | Описание |
|---|---|---|
Полеsuccess |
Типboolean | ОписаниеВсегда true при успехе |
Полеdata.item |
Типobject | ОписаниеFollow-up звонка. Поля — в таблице ниже |
Поля объекта item:
| Поле | Тип | Описание |
|---|---|---|
Полеitem.callId |
Типnumber | ОписаниеИдентификатор звонка |
Полеitem.callType |
Типnumber | ОписаниеВид звонка: 1 — мгновенный, 2 — конференция, 3 — большая комната |
Полеitem.initiatorId |
Типnumber | ОписаниеИнициатор звонка. Карточка сотрудника — GET /v1/users/:id |
Полеitem.startDate |
Типstring | ОписаниеНачало звонка, ISO 8601 в UTC |
Полеitem.endDate |
Типstring | null | ОписаниеОкончание звонка, ISO 8601 в UTC |
Полеitem.durationSeconds |
Типnumber | ОписаниеДлительность звонка в секундах |
Полеitem.uuid |
Типstring | ОписаниеИдентификатор сессии звонка |
Полеitem.language |
Типstring | ОписаниеКод языка транскрипции |
Полеitem.version |
Типnumber | ОписаниеВерсия схемы AI-данных |
Полеitem.participants |
Типobject[] | ОписаниеУчастники звонка |
Полеitem.outcomes |
Типstring[] | ОписаниеГотовые AI-блоки этого звонка |
Полеitem.createdAt |
Типstring | ОписаниеВремя последней AI-записи |
Полеitem.tracks |
Типobject[] | ОписаниеЗаписи звонка |
Полеitem.transcription |
Типobject | null | ОписаниеТранскрипция разговора |
Полеitem.overview |
Типobject | null | ОписаниеОбзор встречи |
Полеitem.summary |
Типobject | null | ОписаниеКраткое изложение по фрагментам |
Полеitem.evaluation |
Типobject | null | ОписаниеОценка эффективности встречи |
Полеitem.insights |
Типobject | null | ОписаниеАналитические выводы и разбор участников |
Участники — `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 | ОписаниеОбоснование оценки |
Пример ответа
{
"success": true,
"data": {
"item": {
"callId": 12345,
"callType": 1,
"initiatorId": 7,
"startDate": "2026-01-15T10:00:00+00:00",
"endDate": "2026-01-15T10:42:00+00:00",
"durationSeconds": 2520,
"uuid": "bb085e5d-5160-4a63-9ac4-152248046c39",
"language": "ru",
"version": 3,
"participants": [
{ "userId": 7, "name": "Иван Петров", "workPosition": "Руководитель проекта", "talkedSeconds": 600 }
],
"outcomes": ["transcription", "overview", "summary", "insights", "evaluation"],
"createdAt": "2026-01-15T11:05:00+00:00",
"tracks": [
{ "trackId": 100, "type": "mixed_audio", "duration": 2520, "fileName": "call_12345.wav", "mimeType": "audio/wav", "url": "https://example.bitrix24.ru/disk/call_12345.wav", "dateCreate": "2026-01-15T11:00:00+00:00" }
],
"transcription": {
"language": "ru",
"segments": [
{ "userId": 7, "userName": "Иван Петров", "start": 12, "end": 25, "text": "Давайте зафиксируем объём спринта. Что берём в работу?" },
{ "userId": 42, "userName": "Мария Иванова", "start": 26, "end": 48, "text": "Предлагаю оставить только импорт каталога, остальное не успеем." },
{ "userId": 7, "userName": "Иван Петров", "start": 49, "end": 70, "text": "Согласен. Тогда прототип показываем в пятницу." }
]
},
"overview": {
"topic": "Планирование спринта",
"detailedTakeaways": "Команда сократила объём спринта до импорта каталога и договорилась показать прототип в пятницу.",
"meetingType": {
"typeTag": "planning",
"title": "Планирование",
"explanation": "Участники распределяли задачи и сроки на ближайшую итерацию."
},
"agenda": {
"explanation": "Определить объём спринта и сроки демонстрации.",
"quote": "Давайте зафиксируем объём спринта."
},
"agreements": [
{ "agreement": "В спринт берём только импорт каталога", "quote": "Предлагаю оставить только импорт каталога, остальное не успеем." }
],
"actionItems": [
{ "actionItem": "Подготовить прототип к пятнице", "quote": "Тогда прототип показываем в пятницу." }
],
"meetings": [
{ "meeting": "Демонстрация прототипа в пятницу", "quote": "Тогда прототип показываем в пятницу." }
]
},
"summary": {
"segments": [
{ "start": 0, "end": 600, "title": "Объём спринта", "summary": "Обсудили, что успеет команда, и сократили набор задач до импорта каталога." },
{ "start": 601, "end": 2520, "title": "Сроки и демонстрация", "summary": "Договорились показать прототип в пятницу и вернуться к остальным задачам в следующем спринте." }
]
},
"insights": {
"speakerEvaluationAvailable": true,
"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"
}
],
"meetingStrengths": [
{ "strengthTitle": "Чёткий итог", "strengthExplanation": "Встреча завершилась зафиксированным решением и сроком." }
],
"meetingWeaknesses": [
{ "weaknessTitle": "Неравное участие", "weaknessExplanation": "Две трети времени говорил один участник." }
],
"speechStyleInfluence": "Спокойный темп речи помог быстро прийти к решению.",
"engagementLevel": "Высокая вовлечённость обоих участников.",
"areasOfResponsibility": "Импорт каталога закреплён за Марией Ивановой.",
"finalRecommendations": "Заранее рассылать повестку, чтобы сократить обсуждение объёма."
},
"evaluation": {
"efficiencyValue": 75,
"calendar": { "overhead": false },
"criteria": {
"agenda_defined": {
"value": true,
"criteria": "Повестка обозначена в начале встречи",
"title": "Повестка",
"thoughts": "Ведущий сформулировал цель первой репликой."
},
"decisions_made": {
"value": true,
"criteria": "Приняты решения по обсуждаемым вопросам",
"title": "Решения",
"thoughts": "Объём спринта и срок демонстрации зафиксированы."
},
"all_participants_involved": {
"value": false,
"criteria": "Все участники вовлечены в обсуждение",
"title": "Вовлечённость",
"thoughts": "Распределение реплик — 66 на 34 процента."
}
}
}
}
}
}
Ключи в evaluation.criteria — коды критериев. Их набор зависит от типа встречи, поэтому обходите карту по ключам, а не по фиксированному списку.
Пример ответа при ошибке
422 — звонок не найден или его Follow-up недоступен:
{
"success": false,
"error": {
"code": "BITRIX_ERROR",
"message": "Нет доступа к данным Follow-up"
}
}
Текст error.message приходит от Битрикс24, поэтому его формулировка и язык зависят от языка портала. Ветвитесь по error.code, а не по тексту сообщения.
Ошибки
| HTTP | Код | Описание |
|---|---|---|
| HTTP400 | КодINVALID_PARAMS |
ОписаниеcallId в пути — не положительное целое число. Проверяется до обращения к Битрикс24 |
| HTTP400 | КодINVALID_PARAMS |
ОписаниеЗначение query-параметра вне списка допустимых — например 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. Проверка доступа к звонку может завершиться раньше проверки select |
| HTTP422 | КодBITRIX_ERROR |
ОписаниеЗапрос отклонён Битрикс24. Звонка с таким callId нет либо к его Follow-up нет доступа — сообщение «Нет доступа к данным Follow-up». Причина конкретного отказа — в error.message |
| HTTP429 | КодRATE_LIMITED |
ОписаниеПревышена частота запросов на стороне Битрикс24 |
| HTTP429 | КодQUEUE_OVERFLOW, QUEUE_TIMEOUT |
ОписаниеОчередь запросов портала переполнена или запрос не дождался очереди. Заголовок Retry-After подсказывает задержку перед повтором |
| HTTP503 | КодBITRIX_TIMEOUT |
ОписаниеБитрикс24 принял запрос, но не ответил за 60 секунд. Для чтения повтор безопасен |
| HTTP502 | КодBITRIX_UNAVAILABLE |
ОписаниеБитрикс24 недоступен |
Полный список общих ошибок API — Ошибки.
Известные особенности
Отличить несуществующий звонок от отказа в доступе по ответу нельзя. Оба случая приходят одинаковым ответом. Список Follow-up тоже не даёт ответа: в него попадают только звонки с готовым Follow-up и только те, к которым у сотрудника есть доступ, — отсутствие звонка в списке не означает, что звонка нет.
Звонки без AI-обработки. Если звонок завершён, но Follow-up по нему не сформирован, метод возвращает объект с метаданными: AI-блоки приходят как null, а outcomes — пустым массивом.
Разбор участников доступен не на каждом портале. Если на портале он недоступен, блок insights приходит с speakerEvaluationAvailable: false и пустым разбором участников. Это не ошибка запроса — структура ответа не меняется.
Доступ ограничен правами сотрудника. Follow-up доступен тому, кто участвовал в звонке или состоит в связанном чате — в том числе если его добавили в чат уже после разговора. Администратор портала видит Follow-up любого звонка портала.