Звонки в CRM

Регистрация входящих и исходящих внешних звонков в CRM Битрикс24, отображение карточки звонка оператору, завершение со статусом и длительностью, прикрепление текстовой транскрипции диалога.

Bitrix24 API: telephony.externalcall.*, telephony.call.attachTranscription Скоуп: telephony

Зарегистрировать звонок

POST /v1/calls/register

Регистрирует входящий или исходящий звонок в Битрикс24 CRM. При crmCreate: true создаёт лид, если номер телефона не найден среди существующих сущностей. Возвращает callId для всех последующих операций со звонком.

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

Параметр Тип Обяз. По умолч. Описание
userId number да — ID пользователя Битрикс24, принимающего звонок. Список пользователей
phoneNumber string да — Номер телефона звонящего в международном формате
type number нет — Направление: 1 — исходящий, 2 — входящий, 3 — входящий с перенаправлением, 4 — обратный звонок, 5 — информационный
lineNumber string нет — Номер внешней линии приложения. Список линий
crmCreate boolean нет false true — создать лид, если номер не найден в CRM

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/register \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+79161234567",
    "type": 2,
    "crmCreate": true
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/register \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": 1,
    "phoneNumber": "+79161234567",
    "type": 2,
    "crmCreate": true
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+79161234567',
    type: 2,
    crmCreate: true,
  }),
})

const { success, data } = await res.json()
const callId = data.callId

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/calls/register', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+79161234567',
    type: 2,
    crmCreate: true,
  }),
})

const { success, data } = await res.json()

Поля ответа

Поле Тип Описание
callId string Идентификатор звонка для всех последующих операций
crmCreatedLead number | null ID созданного лида. null, если лид не создан
crmCreatedEntities array Массив созданных CRM-сущностей [{entityType, entityId}]
crmEntityType string Тип привязанной CRM-сущности: LEAD, CONTACT, COMPANY или пустая строка
crmEntityId number | null ID привязанной CRM-сущности. null, если сущность не привязана

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

HTTP 201 — звонок зарегистрирован, создан новый лид:

JSON 
{
  "success": true,
  "data": {
    "callId": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "crmCreatedLead": 1001069,
    "crmCreatedEntities": [{"entityType": "LEAD", "entityId": 1001069}],
    "crmEntityType": "LEAD",
    "crmEntityId": 1001069
  }
}

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

400 — не переданы обязательные параметры:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_PARAMS",
    "message": "Required: userId (number), phoneNumber (string)"
  }
}

Ошибки

HTTP Код Описание
400 MISSING_PARAMS Не передан userId или phoneNumber
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный API-ключ
401 TOKEN_MISSING Ключ не имеет настроенных токенов Битрикс24
401 KEY_INACTIVE API-ключ неактивен или отозван
403 SCOPE_DENIED Ключу не хватает скоупа telephony
422 BITRIX_ERROR Битрикс24 вернул ошибку (текст в error.message)
429 RATE_LIMITED Превышен лимит запросов
502 BITRIX_UNAVAILABLE Битрикс24 недоступен

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

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

Поиск существующей CRM-сущности при crmCreate: true. Битрикс24 сначала ищет лид, контакт или компанию с совпадающим номером телефона. При нахождении crmEntityId указывает на существующую сущность, а crmCreatedLead остаётся null. Новый лид создаётся только если совпадений нет.

CRM_* поля пустые при crmCreate: false. Привязка к CRM может произойти автоматически при завершении через `POST /v1/calls/:callId/finish`, если Битрикс24 найдёт совпадение по номеру в момент завершения.

callId — обязательный параметр для всех следующих шагов. Сохраните его сразу: все операции show, hide, finish, transcription принимают callId в пути запроса.

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