Для 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 — личный ключ

Terminal
curl "https://vibecode.bitrix24.tech/v1/calls/followups/12345?mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal
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 — личный ключ

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-приложение

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_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 ОписаниеОбоснование оценки

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

JSON
{
  "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 недоступен:

JSON
{
  "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 любого звонка портала.

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