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

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

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

```bash
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`](./get.md) |
| `items[].callType` | number | Вид встречи |
| `items[].initiatorId` | number \| null | Инициатор встречи. Карточка сотрудника — [`GET /v1/users/:id`](/docs/entities/users/get) |
| `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-блоков одинаков в списке и в ответе на получение одного фоллоуапа. Поля каждого блока — в разделе «Поля ответа» страницы [Фоллоуап встречи Синка](./get.md).

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

Ответ на запрос из примеров выше. Вернулись `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` — проверяйте их перед обходом.

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

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

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

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

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

## Ошибки

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

Полный список общих ошибок API — [Ошибки](/docs/errors).

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

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

**Встречи из обычных звонков сюда не попадают.** Видеозвонок в чате Битрикс24 формирует обычный Follow-up звонка, его читает [Список Follow-up](/docs/calls/followup/list). В этом списке — только встречи Синка.

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

- [Фоллоуап встречи Синка](/docs/calls/sync-followup/get)
- [Фоллоуапы встреч Синка](/docs/calls/sync-followup)
- [Follow-up звонков](/docs/calls/followup)
- [Звонки](/docs/calls)
- [Ошибки](/docs/errors)
