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

Фоллоуапы встреч Синка

Чтение AI-фоллоуапов встреч, проведённых в Синке: транскрипция, обзор встречи, краткое изложение, аналитические выводы и оценка эффективности. Методы только читают данные и ничего не изменяют. Нужен скоуп syncconnector.

Методы в процессе раскатки — выходят в обновлении syncconnector 26.100.0; rest >= 26.1300.0. Если методов ещё нет на вашем портале Битрикс24, API вернёт 422 METHOD_NOT_YET_AVAILABLE с error.release. На порталах с доступными методами вызовы работают в обычном режиме.

Для ключа OAuth-приложения укажите syncconnector в scopes при создании приложения. Набор прав закрепляется за ключом в момент выпуска, поэтому уже созданному приложению право добавляют перевыпуском ключа авторизации: карточка приложения и его данные сохранятся (Перевыпуск ключа). Какие ключи получают syncconnector по умолчанию — Скоупы.

Битрикс24 API: syncconnector.followup.*

Скоуп: syncconnector | Базовый URL: https://vibecode.bitrix24.tech/v1 | Авторизация: X-Api-Key

Список фоллоуапов Синка

POST /v1/calls/sync-followups/list

Метод в процессе раскатки — выходит в обновлении syncconnector 26.100.0; rest >= 26.1300.0. Если метода ещё нет на вашем портале Битрикс24, API вернёт 422 METHOD_NOT_YET_AVAILABLE с error.release. На порталах с доступным методом вызов работает в обычном режиме.

Возвращает AI-фоллоуапы встреч Синка за указанный период. Навигация по выдаче — курсорная.

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

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

Тело принимает только перечисленные поля. page, offset, start, filter.participantId и любое другое поле отклоняются с 400 INVALID_PARAMS до обращения к порталу.

Поле select

Без select и с пустым массивом возвращаются только базовые поля: callId, callType, initiatorId, startDate, endDate, durationSeconds. С непустым select возвращаются перечисленные поля и всегда callId. Неизвестное значение отклоняется с 400 INVALID_PARAMS.

Метаданные

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

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.actionItems"]) возвращает блок только с этим подполем.
  • Любой AI-блок или его подполе в select снижает размер страницы: по умолчанию и максимум — 20 записей.

Навигация

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

pagination.limit — без AI-полей по умолчанию 50, максимум 200. С AI-полями по умолчанию и максимум 20.

jsonc
{ "pagination": { "limit": 50, "afterCursor": { "startDate": "2026-03-05T09:00:00.000000+00:00", "id": 1150 } } }

Курсор передаётся без изменений. Изменённый или собранный вручную курсор отклоняется с 422 BITRIX_ERROR.

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

mentionFormat управляет тем, как выглядят @-упоминания сотрудников в текстовых AI-полях, например в overview.actionItems[].actionItem.

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

Примеры

Задачи и тема каждой встречи за первую половину марта, от новых к старым, с упоминаниями чистым текстом. Это первый запрос, поэтому afterCursor в нём нет — курсор для следующей страницы придёт в ответе.

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

Terminal
curl -X POST https://vibecode.bitrix24.tech/v1/calls/sync-followups/list \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      "startDate": { "from": "2026-03-01T00:00:00Z", "to": "2026-03-15T23:59:59Z" }
    },
    "select": [
      "callId", "chatId", "startDate", "durationSeconds",
      "overview.topic", "overview.actionItems", "evaluation.efficiencyValue"
    ],
    "order": { "startDate": "desc" },
    "pagination": { "limit": 20 },
    "mentionFormat": "none"
  }'

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

Terminal
curl -X POST https://vibecode.bitrix24.tech/v1/calls/sync-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-03-01T00:00:00Z", "to": "2026-03-15T23:59:59Z" }
    },
    "select": [
      "callId", "chatId", "startDate", "durationSeconds",
      "overview.topic", "overview.actionItems", "evaluation.efficiencyValue"
    ],
    "order": { "startDate": "desc" },
    "pagination": { "limit": 20 },
    "mentionFormat": "none"
  }'

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

javascript
const res = await fetch('https://vibecode.bitrix24.tech/v1/calls/sync-followups/list', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: {
      startDate: { from: '2026-03-01T00:00:00Z', to: '2026-03-15T23:59:59Z' },
    },
    select: [
      'callId', 'chatId', 'startDate', 'durationSeconds',
      'overview.topic', 'overview.actionItems', '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 meeting of data.items) {
  const topic = meeting.overview?.topic ?? 'тема не определена'
  console.log(meeting.startDate, topic, `оценка: ${meeting.evaluation?.efficiencyValue ?? '—'}`)

  // actionItems приходит null, если задач на встрече не выделено
  for (const item of meeting.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/sync-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-03-01T00:00:00Z', to: '2026-03-15T23:59:59Z' },
    },
    select: [
      'callId', 'chatId', 'startDate', 'durationSeconds',
      'overview.topic', 'overview.actionItems', '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[] ОписаниеМассив фоллоуапов. Поля элемента — в таблице ниже
Полеdata.hasMore Типboolean ОписаниеЕсть ли записи за пределами текущей страницы
Полеdata.afterCursor Типobject | null ОписаниеКурсор следующей страницы: startDate и id. null — записей больше нет

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

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

Состав participants, tracks и AI-блоков одинаков в списке и в ответе на получение одного фоллоуапа. Поля каждого блока — в разделе «Поля ответа» страницы Фоллоуап встречи Синка.

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

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

JSON
{
  "success": true,
  "data": {
    "items": [
      {
        "callId": 1204,
        "chatId": 3150,
        "startDate": "2026-03-12T10:00:00+00:00",
        "durationSeconds": 1840,
        "overview": {
          "topic": "Статус задач команды",
          "actionItems": [
            {
              "actionItem": "Иван Петров закроет задачу по отчёту до пятницы",
              "actionItemMentionLess": "Иван Петров закроет задачу по отчёту до пятницы",
              "quote": "Задачу по отчёту закрою до пятницы."
            }
          ]
        },
        "evaluation": {
          "efficiencyValue": 92
        }
      },
      {
        "callId": 1187,
        "chatId": 3162,
        "startDate": "2026-03-10T14:30:00+00:00",
        "durationSeconds": 960,
        "overview": {
          "topic": "Планирование задач на неделю",
          "actionItems": null
        },
        "evaluation": {
          "efficiencyValue": 78
        }
      }
    ],
    "hasMore": true,
    "afterCursor": { "startDate": "2026-03-10T14:30:00.000000+00:00", "id": 1187 }
  }
}

Во второй встрече задачи не выделены: actionItems приходит null, а не пустым массивом. То же касается overview.agreements и overview.meetings — проверяйте их перед обходом.

Как выглядит фоллоуап со всеми блоками, показано на странице Фоллоуап встречи Синка.

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

400 — передан фильтр по участнику:

JSON
{
  "success": false,
  "error": {
    "code": "INVALID_PARAMS",
    "message": "filter.participantId не поддерживается: Синк отдаёт только встречи владельца ключа"
  }
}

Текст error.message этой ошибки зависит от языка пользователя. Ветвитесь по error.code, а не по тексту сообщения.

Ошибки

HTTP Код Описание
HTTP400 КодINVALID_PARAMS ОписаниеВ теле нет объекта filter, неполный или некорректный filter.startDate: нет from или to, дата без часового пояса, несуществующая дата, from позже to
HTTP400 КодINVALID_PARAMS ОписаниеПередано неподдерживаемое поле: page, offset, start, filter.participantId, лишнее поле в filter, filter.startDate, order или pagination
HTTP400 КодINVALID_PARAMS ОписаниеНедопустимое значение: select не массив строк или содержит неизвестное поле, filter.chatId не положительное целое, order не по startDate, mentionFormat вне bb, html, none, pagination.limit вне допустимого диапазона
HTTP400 КодINVALID_PARAMS Описаниеorder, pagination или pagination.afterCursor передан не объектом, например курсор строкой
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч в заголовке X-Api-Key не найден
HTTP401 КодTOKEN_MISSING ОписаниеУ ключа нет токенов портала. Ключ OAuth-приложения требует заголовок Authorization: Bearer
HTTP403 КодSCOPE_DENIED ОписаниеУ ключа нет скоупа syncconnector
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеБитрикс24 отказал в доступе к данным Синка. Полный разбор причин и что делать по типу ключа — Ошибки
HTTP422 КодMETHOD_NOT_YET_AVAILABLE ОписаниеНа портале нет нужного обновления. error.release равен syncconnector 26.100.0; rest >= 26.1300.0
HTTP422 КодBITRIX_ERROR ОписаниеКурсор в pagination.afterCursor изменён или собран вручную — error.b24Code равен invalid_pagination
HTTP422 КодBITRIX_ERROR ОписаниеДругой отказ Битрикс24. Причина — в error.message

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

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

Выдача — только встречи владельца ключа. Список содержит встречи пользователя, от имени которого идёт запрос: владельца личного ключа или пользователя сессии OAuth-приложения. Администратор портала тоже видит только свои встречи. Приложение на личном ключе показывает всем своим пользователям встречи владельца ключа.

Встречи из обычных звонков сюда не попадают. Видеозвонок в чате Битрикс24 формирует обычный Follow-up звонка, его читает Список Follow-up. В этом списке — только встречи Синка.

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