Звонки

Программный доступ к 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`. Если задача звучит как «получить текст разговора с клиентом по сделке или лиду» — вам туда, а не в этот раздел.

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

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

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" } },
    "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
  }
}

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

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

Terminal 
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` call.followup.list Список Follow-up за период с фильтром, сортировкой и курсорной навигацией
GET `/v1/calls/followups/:callId` 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 на стороне портала. Переподключите ключ с нужным правом
422 METHOD_NOT_YET_AVAILABLE Обновление call 26.600.0 на портале ещё не выпущено
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 — Ошибки.

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