Для AI-агентов: markdown этой страницы — /docs-content/telephony/crm.md индекс документации — /llms.txt

Звонки в 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, принимающего звонок. Положительное целое число, принимается также числовая строка "42". Список пользователей
Параметр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()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типobject ОписаниеЗарегистрированный звонок и его привязка к CRM
Полеdata.callId Типstring ОписаниеИдентификатор звонка для всех последующих операций
Полеdata.crmCreatedLead Типnumber | null ОписаниеID созданного лида. null, если лид не создан
Полеdata.crmCreatedEntities Типarray ОписаниеМассив созданных CRM-сущностей [{entityType, entityId}]
Полеdata.crmEntityType Типstring ОписаниеТип привязанной CRM-сущности: LEAD, CONTACT, COMPANY или пустая строка
Полеdata.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 (positive integer), phoneNumber (non-empty string)"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_PARAMS ОписаниеuserId не передан или не распознан как положительное целое число, либо phoneNumber не передан или не распознан как непустая строка или число
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч не опознан: такой строки на платформе нет
HTTP401 КодTOKEN_MISSING ОписаниеКлюч не имеет настроенных токенов Битрикс24
HTTP401 КодKEY_INACTIVE ОписаниеAPI-ключ неактивен или отозван
HTTP403 КодSCOPE_DENIED ОписаниеКлючу не хватает скоупа telephony
HTTP422 КодBITRIX_ERROR Описаниеtype не передан или его значение вне перечня 1–5 — в error.message приходит Unknown TYPE
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 вернул ошибку (текст в error.message)
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов
HTTP502 Код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 в пути запроса.

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