# Звонки

Программный доступ к AI Follow-up завершённых звонков Битрикс24: транскрипция разговора, обзор встречи, договорённости, задачи и оценка эффективности.

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

## Что такое Follow-up

Follow-up — это AI-разбор внутреннего звонка или совещания сотрудников: расшифровка разговора, тема встречи, договорённости, поставленные задачи, разбор участников и оценка эффективности. Битрикс24 формирует его сам после завершения звонка, методы раздела только читают готовый результат и ничего не создают.

Follow-up формируется не по каждому звонку. Готовые блоки перечислены в поле `outcomes` ответа, несформированные приходят как `null`.

**Это не расшифровка звонка клиенту.** Разговор с клиентом, залогированный делом CRM, расшифровывается отдельным механизмом — его текст возвращает [`GET /v1/activities/:activityId/transcript`](/docs/entities/activities/transcript). Если задача звучит как «получить текст разговора с клиентом по сделке или лиду» — вам туда, а не в этот раздел.

## Быстрый старт

Список звонков с готовым Follow-up за январь:

```bash
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" } },
    "pagination": { "limit": 5 }
  }'
```

Ответ содержит массив звонков в `data.items` и курсор следующей страницы в `data.afterCursor`:

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "callId": 12345,
        "callType": 1,
        "initiatorId": 7,
        "startDate": "2026-01-15T10:00:00+00:00",
        "endDate": "2026-01-15T10:42:00+00:00",
        "durationSeconds": 2520
      }
    ],
    "hasMore": false,
    "afterCursor": null
  }
}
```

## Полный пример

Разбор итогов встречи: находим звонок за период, читаем обзор и договорённости, забираем задачи.

```bash
BASE='https://vibecode.bitrix24.tech/v1'

# 1. Звонки с Follow-up за период → берём идентификатор первого
CALL_ID=$(curl -s -X POST "$BASE/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"}},
       "order": {"startDate": "desc"}, "pagination": {"limit": 1}}' | jq -r '.data.items[0].callId')

# 2. Обзор встречи и договорённости
curl -s "$BASE/calls/followups/$CALL_ID?select=overview&mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data.item.overview.topic, .data.item.overview.agreements'

# 3. Задачи, поставленные на встрече
curl -s "$BASE/calls/followups/$CALL_ID?select=overview.actionItems&mentionFormat=none" \
  -H "X-Api-Key: YOUR_API_KEY" | jq '.data.item.overview.actionItems'
```

`mentionFormat=none` убирает разметку `@`-упоминаний: текст приходит без служебных тегов и готов к передаче в нейросеть или к сохранению в задачу.

## Справочник эндпоинтов

| Метод | Путь | Bitrix24 метод | Описание |
|-------|------|---------------|----------|
| POST | [`/v1/calls/followups/list`](/docs/calls/followup/list) | call.followup.list | Список Follow-up за период с фильтром, сортировкой и курсорной навигацией |
| GET | [`/v1/calls/followups/:callId`](/docs/calls/followup/get) | call.followup.get | Полные данные Follow-up по одному звонку |

## Коды ошибок

### Ошибки раздела

| HTTP | Код | Когда |
|------|-----|-------|
| 400 | `MISSING_PARAMS` | В теле запроса нет объекта `filter` |
| 400 | `INVALID_PARAMS` | `callId` в пути — не положительное целое число |
| 400 | `INVALID_PARAMS` | Битрикс24 отклонил значение параметра. Ответ дополнительно содержит массив `error.validation` с именем поля |
| 403 | `BITRIX_ACCESS_DENIED` | Битрикс24 отказал в доступе. Частый случай — набор скоупов, с которым ключ обращается к порталу, не содержит `call`. Полный разбор причин и что делать по типу ключа — [Ошибки](/docs/errors/auth#bitrix_access_denied-403) |
| 422 | `METHOD_NOT_YET_AVAILABLE` | Обновление `call 26.600.0` на портале ещё не выпущено. Ответ содержит поле `error.release` со значением `call 26.600.0` — [разбор кода](/docs/errors/platform#method_not_yet_available-422) |
| 422 | `BITRIX_ERROR` | Запрос отклонён: некорректный диапазон дат, недопустимое поле в `select`, некорректные `pagination` или `order`, нет доступа к данным звонка |

### Системные ошибки

| HTTP | Код | Когда | Повтор |
|------|-----|-------|--------|
| 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | нет |
| 401 | `TOKEN_MISSING` | У ключа нет токенов портала. Ключ OAuth-приложения требует заголовок `Authorization: Bearer` | нет |
| 403 | `SCOPE_DENIED` | У ключа нет скоупа `call` | нет |
| 429 | `RATE_LIMITED` | Превышена частота запросов на стороне Битрикс24 | да, с задержкой |
| 429 | `QUEUE_OVERFLOW`, `QUEUE_TIMEOUT` | Очередь запросов портала переполнена или запрос не дождался очереди. Заголовок `Retry-After` подсказывает задержку | да, после `Retry-After` |
| 503 | `BITRIX_TIMEOUT` | Битрикс24 принял запрос, но не ответил за 15 секунд | да: методы раздела только читают данные, повтор безопасен |
| 502 | `BITRIX_UNAVAILABLE` | Битрикс24 недоступен | да, с задержкой |

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

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

- [Follow-up звонков](/docs/calls/followup)
- [Телефония](/docs/telephony)
- [Расшифровка звонка](/docs/entities/activities/transcript)
- [Ошибки](/docs/errors)