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

`GET /v1/calls/sync-followups/:followupId`

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

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

## Параметры

| Параметр | Тип | Обяз. | Описание |
|----------|-----|:-----:|---------|
| `followupId` (path) | integer | да | Номер фоллоуапа, положительное целое. Это поле `callId` элемента [списка фоллоуапов Синка](./list.md) |
| `select` (query) | string[] | нет | Какие поля вернуть. Передаётся повторяющимся параметром или списком через запятую. Словарь значений общий со списком — раздел «Поле select» страницы [Список фоллоуапов Синка](./list.md) |
| `mentionFormat` (query) | string | нет | Формат `@`-упоминаний в текстовых полях: `bb`, `html` или `none`. По умолчанию — `bb`. Как выглядит каждый формат — раздел «Формат упоминаний» страницы [Список фоллоуапов Синка](./list.md) |

Другие query-параметры отклоняются с `400 INVALID_PARAMS`.

## Поле select

| Значение `select` | Что в ответе |
|---|---|
| Не указан | Полный фоллоуап: метаданные и все AI-блоки |
| `?select=` или `?select=[]` | Только базовые поля: `callId`, `callType`, `initiatorId`, `startDate`, `endDate`, `durationSeconds` |
| Список полей | Только перечисленные поля и всегда `callId` |

Этим получение отличается от [списка](./list.md): там запрос без `select` возвращает только базовые поля.

## Примеры

Запрос без `select` — возвращается весь фоллоуап. `mentionFormat=none` убирает разметку упоминаний, поэтому текст готов к передаче в нейросеть или к сохранению в задачу. Чтобы забрать только часть блоков, добавьте `select` — например `?select=overview.actionItems&select=evaluation.efficiencyValue`.

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

```bash
curl "https://vibecode.bitrix24.tech/v1/calls/sync-followups/1204?mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY"
```

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

```bash
curl "https://vibecode.bitrix24.tech/v1/calls/sync-followups/1204?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/sync-followups/1204?${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 meeting = body.data.item

console.log(meeting.outcomes, `${meeting.durationSeconds} сек`)
console.log(meeting.overview?.topic ?? 'обзор не сформирован')

// agreements, actionItems и meetings приходят null, если на встрече их нет
for (const item of meeting.overview?.actionItems ?? []) {
  console.log('задача:', item.actionItem, '— цитата:', item.quote)
}

for (const speaker of meeting.insights?.speakerAnalysis ?? []) {
  console.log(`участник ${speaker.userId}: ${speaker.talkPercentage}% времени, оценка ${speaker.efficiencyValue}`)
}

// Набор критериев зависит от типа встречи: обходим карту по ключам
for (const [code, criterion] of Object.entries(meeting.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/sync-followups/1204?${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}`)
}

console.log(body.data.item)
```

## Поля ответа

| Поле | Тип | Описание |
|------|-----|---------|
| `success` | boolean | Всегда `true` при успехе |
| `data.item` | object | Фоллоуап встречи. Поля — в таблице ниже |

Поля объекта `item`:

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

### Участники — `participants[]`

| Поле | Тип | Описание |
|------|-----|---------|
| `userId` | number | Идентификатор сотрудника. Карточка — [`GET /v1/users/:id`](/docs/entities/users/get) |
| `name` | string | Имя сотрудника |
| `avatar` | string | Ссылка на аватар |
| `workPosition` | string | Должность |
| `talkedSeconds` | number | Сколько секунд участник говорил |

### Записи встречи — `tracks[]`

| Поле | Тип | Описание |
|------|-----|---------|
| `trackId` | number | Идентификатор записи |
| `callId` | number | Номер фоллоуапа, к которому относится запись |
| `type` | string | Вид дорожки, например `record` |
| `fileId` | number | Идентификатор файла записи |
| `diskFileId` | number | Идентификатор файла на Диске. Не совпадает с `fileId` |
| `duration` | number | Длительность записи в секундах |
| `fileName` | string | Имя файла |
| `fileSize` | number | Размер файла в байтах |
| `mimeType` | string | MIME-тип файла, например `audio/mp4` |
| `relUrl` | string | Путь для скачивания относительно адреса портала |
| `url` | string | Полная ссылка для скачивания: адрес портала и `relUrl`. Наличие ссылки не гарантирует, что запись можно скачать |
| `dateCreate` | string | Когда запись создана, ISO 8601 |

### Транскрипция — `transcription`

| Поле | Тип | Описание |
|------|-----|---------|
| `language` | string | Код языка расшифровки |
| `segments[]` | object[] | Реплики в хронологическом порядке |
| `segments[].userId` | number | Кто говорит |
| `segments[].userName` | string | Имя говорящего |
| `segments[].start` | string | Начало реплики от начала встречи, `ММ:СС`. Значение минут может превышать 59 |
| `segments[].end` | string | Конец реплики от начала встречи, `ММ:СС` |
| `segments[].text` | string | Текст реплики |

### Обзор встречи — `overview`

| Поле | Тип | Описание |
|------|-----|---------|
| `topic` | string | Тема встречи |
| `detailedTakeaways` | string | Развёрнутые выводы |
| `meetingType` | object | Тип встречи: `typeTag` — код, например `status_meeting`, `title` — название, `explanation` — обоснование |
| `agenda` | object | Повестка: `explanation` — формулировка, `quote` — цитата из разговора |
| `agreements[]` | object[] \| null | Договорённости: `agreement` — формулировка, `quote` — цитата. `null`, если договорённостей нет |
| `actionItems[]` | object[] \| null | Задачи. `null`, если задач нет |
| `actionItems[].actionItem` | string | Формулировка задачи. Упоминания сотрудников оформлены по `mentionFormat` |
| `actionItems[].actionItemMentionLess` | string | Та же формулировка без разметки упоминаний: имена сотрудников остаются обычным текстом |
| `actionItems[].quote` | string | Цитата из разговора |
| `meetings[]` | object[] \| null | Назначенные встречи: `meeting` — формулировка с упоминаниями по `mentionFormat`, `meetingMentionLess` — та же формулировка без разметки упоминаний, `quote` — цитата. `null`, если встреч не назначено |

### Краткое изложение — `summary`

| Поле | Тип | Описание |
|------|-----|---------|
| `segments[]` | object[] | Фрагменты разговора |
| `segments[].start` | string | Начало фрагмента, `ММ:СС` |
| `segments[].end` | string | Конец фрагмента, `ММ:СС` |
| `segments[].title` | string | Заголовок фрагмента |
| `segments[].summary` | string | Изложение фрагмента |

### Аналитические выводы — `insights`

| Поле | Тип | Описание |
|------|-----|---------|
| `speakerEvaluationAvailable` | boolean | Доступен ли разбор участников |
| `speakerAnalysis[]` | object[] | Разбор участников, по убыванию `talkPercentage` |
| `speakerAnalysis[].userId` | number | Идентификатор сотрудника. Карточка — [`GET /v1/users/:id`](/docs/entities/users/get) |
| `speakerAnalysis[].detailedInsight` | string | Вывод по участнику |
| `speakerAnalysis[].efficiencyValue` | number | Оценка эффективности участника, от 0 до 100 |
| `speakerAnalysis[].evaluationCriteria` | object | Карта критериев оценки участника. Ключ — код критерия, например `politeness` или `staysOnTopic` |
| `speakerAnalysis[].evaluationCriteria.<код>.value` | boolean | Выполнен ли критерий |
| `speakerAnalysis[].evaluationCriteria.<код>.title` | string | Название критерия |
| `speakerAnalysis[].evaluationCriteria.<код>.criteria` | string | Формулировка критерия |
| `speakerAnalysis[].talkPercentage` | number | Доля времени, которую участник говорил, в процентах |
| `speakerAnalysis[].duration` | number | Сколько секунд участник говорил |
| `speakerAnalysis[].durationFormat` | string | То же время текстом, например `18 мин` |
| `meetingStrengths`, `meetingWeaknesses`, `speechStyleInfluence`, `engagementLevel`, `areasOfResponsibility`, `finalRecommendations` | null | Поля присутствуют в блоке и приходят со значением `null` |

### Оценка эффективности — `evaluation`

| Поле | Тип | Описание |
|------|-----|---------|
| `efficiencyValue` | number | Общая эффективность встречи, от 0 до 100 |
| `calendar` | null | Поле присутствует в блоке и приходит со значением `null` |
| `criteria` | object | Карта критериев. Ключ — код критерия, например `communicationClear`. Набор кодов зависит от типа встречи |
| `criteria.<код>.value` | boolean | Выполнен ли критерий |
| `criteria.<код>.title` | string | Название критерия |
| `criteria.<код>.criteria` | string | Формулировка критерия |
| `criteria.<код>.thoughts` | string | Обоснование оценки |

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

Ответ на запрос из примеров выше. Упоминания идут чистым текстом, потому что запрошен `mentionFormat=none`, поэтому `actionItem` и `actionItemMentionLess` совпадают. С `bb` или `html` в `actionItem` имя исполнителя обёрнуто в разметку упоминания.

```json
{
  "success": true,
  "data": {
    "item": {
      "callId": 1204,
      "callType": 1,
      "chatId": 3150,
      "initiatorId": null,
      "startDate": "2026-03-12T10:00:00+00:00",
      "endDate": "2026-03-12T10:30:40+00:00",
      "durationSeconds": 1840,
      "uuid": "01jc9m4x7k2p8q3r5s6t7v8w9y",
      "language": "ru",
      "version": 3,
      "participants": [
        { "userId": 7, "talkedSeconds": 1100, "name": "Иван Петров", "avatar": "https://example.bitrix24.ru/upload/avatar.png", "workPosition": "Руководитель проекта" },
        { "userId": 42, "talkedSeconds": 740, "name": "Мария Иванова", "avatar": "https://example.bitrix24.ru/upload/avatar-2.png", "workPosition": "Аналитик" }
      ],
      "outcomes": ["transcription", "overview", "summary", "insights", "evaluation"],
      "createdAt": "2026-03-12T10:52:10+00:00",
      "tracks": [
        {
          "trackId": 310,
          "type": "record",
          "fileId": 52011,
          "diskFileId": 18470,
          "duration": 1835,
          "fileName": "Запись звонка от 2026-03-12.m4a",
          "fileSize": 7340032,
          "mimeType": "audio/mp4",
          "callId": 1204,
          "relUrl": "/bitrix/services/main/ajax.php?action=FILE_ACTION&fileId=52011",
          "url": "https://example.bitrix24.ru/bitrix/services/main/ajax.php?action=FILE_ACTION&fileId=52011",
          "dateCreate": "2026-03-12T10:31:15+00:00"
        }
      ],
      "transcription": {
        "language": "ru",
        "segments": [
          { "userId": 7, "userName": "Иван Петров", "start": "00:05", "end": "00:18", "text": "Пройдёмся по статусам задач." },
          { "userId": 42, "userName": "Мария Иванова", "start": "00:19", "end": "00:41", "text": "Две задачи выполнены, одна в работе, дедлайн у неё в пятницу." }
        ]
      },
      "overview": {
        "topic": "Статус задач команды",
        "detailedTakeaways": "Команда сверила статусы задач: две выполнены, одна в работе. Дедлайн оставшейся задачи — пятница.",
        "meetingType": {
          "explanation": "Участники сверяли статусы задач и сроки.",
          "typeTag": "status_meeting",
          "title": "Встреча по статусу задач"
        },
        "agenda": {
          "explanation": "Статусы задач и дедлайны на неделю.",
          "quote": "Пройдёмся по статусам задач."
        },
        "agreements": [
          { "agreement": "Задачу в работе закрываем до пятницы", "quote": "Давайте закроем её до пятницы." }
        ],
        "actionItems": [
          {
            "actionItem": "Иван Петров закроет задачу по отчёту до пятницы",
            "actionItemMentionLess": "Иван Петров закроет задачу по отчёту до пятницы",
            "quote": "Задачу по отчёту закрою до пятницы."
          }
        ],
        "meetings": null
      },
      "summary": {
        "segments": [
          { "start": "00:00", "end": "12:30", "title": "Статусы задач", "summary": "Сверили статусы: две задачи выполнены, одна в работе." },
          { "start": "12:31", "end": "30:40", "title": "Дедлайны", "summary": "Подтвердили дедлайн задачи в работе и назначили ответственного." }
        ]
      },
      "insights": {
        "speakerEvaluationAvailable": true,
        "speakerAnalysis": [
          {
            "detailedInsight": "Участник вёл встречу, сверил статусы задач и зафиксировал дедлайны.",
            "evaluationCriteria": {
              "politeness": { "value": true, "criteria": "Вежливость", "title": "Вежливое общение" },
              "positiveAttitude": { "value": true, "criteria": "Позитивный настрой", "title": "Позитивный настрой участника" },
              "staysOnTopic": { "value": true, "criteria": "Следование теме", "title": "Следует теме" },
              "communicationClarity": { "value": true, "criteria": "Ясность коммуникации", "title": "Ясно излагает" },
              "individualContribution": { "value": true, "criteria": "Индивидуальный вклад", "title": "Вклад в обсуждение" },
              "timeManagementConciseness": { "value": false, "criteria": "Краткость и тайм-менеджмент", "title": "Краткость" }
            },
            "userId": 7,
            "efficiencyValue": 88,
            "talkPercentage": 60,
            "duration": 1100,
            "durationFormat": "18 мин"
          }
        ],
        "meetingStrengths": null,
        "meetingWeaknesses": null,
        "speechStyleInfluence": null,
        "engagementLevel": null,
        "areasOfResponsibility": null,
        "finalRecommendations": null
      },
      "evaluation": {
        "efficiencyValue": 92,
        "calendar": null,
        "criteria": {
          "meetingSummarized": {
            "value": true,
            "criteria": "Подведение итогов",
            "thoughts": "В конце встречи ведущий перечислил задачи, их статусы и дедлайны.",
            "title": "Итоги подведены"
          },
          "communicationClear": {
            "value": true,
            "criteria": "Ясность коммуникации",
            "thoughts": "Участники формулировали задачи с конкретными сроками.",
            "title": "Ясная коммуникация"
          }
        }
      }
    }
  }
}
```

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

403 — фоллоуапа с таким номером нет или он принадлежит другому пользователю:

```json
{
  "success": false,
  "error": {
    "code": "BITRIX_ACCESS_DENIED",
    "message": "Нет доступа к данным Follow-up"
  }
}
```

Текст `error.message` приходит от Битрикс24, его язык зависит от языка портала. Ветвитесь по `error.code`, а не по тексту сообщения.

## Ошибки

| HTTP | Код | Описание |
|------|-----|---------|
| 400 | `INVALID_PARAMS` | `followupId` в пути — не положительное целое число |
| 400 | `INVALID_PARAMS` | Неизвестное поле в `select`, `mentionFormat` вне `bb`, `html`, `none` или другой query-параметр |
| 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` | Другой отказ Битрикс24. Причина — в `error.message` |

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

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

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

**Номер фоллоуапа не совпадает с номером звонка.** `followupId` не принимает идентификатор обычного звонка и не сопоставляется с `callId` [Follow-up по одному звонку](/docs/calls/followup/get).

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

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