#Список Follow-up

⚠️ Метод в процессе раскатки — выходит в обновлении call 26.600.0. Доступен не на всех порталах Битрикс24. Если на вашем портале метод ещё не доступен, API вернёт 422 METHOD_NOT_YET_AVAILABLE — это не ошибка интеграции, а признак того, что обновление пока не приехало на портал.

POST /v1/calls/followups/list

Возвращает список AI Follow-up за указанный период. Курсорная (keyset) навигация.

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

Параметр Тип Обяз. Описание
filter object да Условия выборки (см. ниже)
filter.startDate.from string да Начало периода, ISO 8601 (2026-01-01T00:00:00Z)
filter.startDate.to string да Конец периода, ISO 8601, ≥ from
filter.participantId integer нет Только для администратора — выборка по пользователю
select string[] нет Какие поля вернуть (см. «Поле select»)
order object нет { "startDate": "asc" | "desc" }, по умолчанию desc
pagination object нет { limit, afterCursor } (см. «Навигация»)
mentionFormat string нет bb (по умолч.) | html | none

#Примеры

#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" } },
    "select": ["callId", "startDate", "participants", "overview.topic"],
    "order": { "startDate": "desc" },
    "pagination": { "limit": 20 },
    "mentionFormat": "html"
  }'

#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" } },
    "select": ["callId", "startDate", "overview.topic"],
    "pagination": { "limit": 20 }
  }'

#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' } },
    select: ['callId', 'startDate', 'overview.topic'],
    pagination: { limit: 20 },
  }),
})
const { success, data } = await res.json()
console.log(data.items, 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' } },
    select: ['callId', 'startDate', 'overview.topic'],
    pagination: { limit: 20 },
  }),
})
const { success, data } = await res.json()
console.log(data.items)

#Поля ответа

data = { items: [...], hasMore, afterCursor }. Поля элемента items[i] — см. раздел «Поля Follow-up».

jsonc 
{
  "success": true,
  "data": {
    "items": [
      {
        "callId": 12345,
        "startDate": "2026-01-15T10:00:00+00:00",
        "participants": [
          { "userId": 7, "name": "Иван Петров", "avatar": "https://...", "talkedSeconds": 600 },
          { "userId": 42, "name": "Мария Иванова", "talkedSeconds": 1200 }
        ],
        "overview": {
          "topic": "Планирование спринта",
          "actionItems": [
            { "actionItem": "Выкатить MVP к пятнице", "quote": "…" }
          ]
        }
      }
    ],
    "hasMore": true,
    "afterCursor": { "startDate": "2026-01-12T14:30:00.000000+00:00", "id": 12330 }
  }
}

#Навигация (курсорная)

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

pagination.limit — по умолчанию 50, максимум 200; при «тяжёлых» полях (transcription, overview, insights) максимум снижается до 20.

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

#Поле select

Без select возвращаются только дешёвые метаданные. Любое другое поле нужно запросить явно. Неизвестное значение → ошибка invalid_select_field.

#Метаданные

Значение Поле в ответе
callId, callType, initiatorId, startDate, endDate, durationSeconds базовые (в list всегда)
uuid UUID сессии звонка
participants список участников
tracks записи звонка со ссылками на скачивание
outcomes какие AI-блоки готовы
language язык транскрипции
version версия схемы AI-данных
createdAt время последней AI-записи

#AI-блоки

Можно запросить блок целиком или отдельное подполе через точку:

Блок Подполя (dotted-path)
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 — «тяжёлые»; их выбор снижает максимальный limit до 20.

#Поля Follow-up

#Корневой объект

Поле Тип Описание
callId int Идентификатор звонка
callType int 1 — мгновенный, 2 — конференция, 3 — большая комната
initiatorId int Инициатор звонка
startDate string Начало, ISO 8601 (UTC)
endDate string|null Окончание, ISO 8601 (UTC)
durationSeconds int Длительность в секундах
uuid string UUID сессии
language string Код языка транскрипции
version int Версия схемы AI-данных
participants object[] Участники
outcomes string[] Готовые AI-блоки
createdAt string Время последней AI-записи
tracks object[] Записи звонка
transcription object Транскрипция
overview object Обзор встречи
summary object Сегментированное саммари
insights object Инсайты и анализ спикеров (только CIS-регионы)
evaluation object Оценка эффективности встречи

#participants[]

jsonc 
{ "userId": 7, "name": "Иван Петров", "avatar": "https://.../100x100.png", "workPosition": "PM", "talkedSeconds": 600 }

#tracks[]

jsonc 
{ "trackId": 100, "type": "mixed_audio", "duration": 2520, "fileName": "call_12345.wav",
  "mimeType": "audio/wav", "url": "https://portal.example/...", "dateCreate": "2026-01-15T11:00:00+00:00" }

#transcription

  • language — код языка;
  • segments[] — { userId, userName, start, end, text }, реплики в хронологическом порядке.

#overview

  • topic — тема встречи;
  • detailedTakeaways — развёрнутые выводы;
  • meetingType — { explanation, typeTag, title };
  • agenda — { explanation, quote };
  • agreements[] — { agreement, quote };
  • actionItems[] — { actionItem, quote };
  • meetings[] — { meeting, quote }.

#summary

  • segments[] — { start, end, title, summary }.

#insights

  • speakerEvaluationAvailable (bool) — доступна ли оценка спикеров на портале;
  • speakerAnalysis[] — { userId, detailedInsight, efficiencyValue, evaluationCriteria, talkPercentage, duration, durationFormat }, отсортирован по talkPercentage ↓;
  • meetingStrengths[] — { strengthTitle, strengthExplanation };
  • meetingWeaknesses[] — { weaknessTitle, weaknessExplanation };
  • speechStyleInfluence, engagementLevel, areasOfResponsibility, finalRecommendations — текстовые оценки.

#evaluation

  • efficiencyValue (0..100) — общая эффективность встречи;
  • calendar — { overhead: bool };
  • criteria — карта критериев: { <код>: { value: bool, criteria, thoughts, title } }.

#mentionFormat

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

Значение Текст в ответе Когда использовать
bb (по умолчанию) [USER=42]Иван Петров[/USER] мобильный клиент, legacy-обработчики
html <span class="bx-call-mention" …>Иван Петров</span> вывод в вебе
none Иван Петров передача в LLM/инструменты, чистый текст

#Ошибки

HTTP Код Когда
400 MISSING_PARAMS Нет filter.startDate.from/to
401 MISSING_API_KEY Не передан X-Api-Key
403 SCOPE_DENIED Ключу не хватает скоупа call
422 BITRIX_ERROR Bitrix24 вернул ошибку (текст в error.message)
502 BITRIX_UNAVAILABLE Bitrix24 недоступен

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

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