#Телефония

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

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

Быстрый старт | Полный пример | Справочник эндпоинтов | Коды ошибок

#Разделы документации

Звонки в CRM — регистрация внешних звонков, завершение, карточка оператору, транскрипции
Исходящие звонки — обратный звонок и автоматические звонки с синтезом речи или аудиофайлом
Линии — внешние линии приложения и список арендованных у Voximplant
Аналитика и справочники — статистика звонков и справочник голосов для синтеза речи

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

#1. Зарегистрируйте звонок

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
  }'

Ответ (HTTP 201):

JSON

{
  "success": true,
  "data": {
    "CALL_ID": "externalCall.00b1e735843c558431be668e3687a58b.1777974304",
    "CRM_CREATED_LEAD": 1001069,
    "CRM_CREATED_ENTITIES": [{"ENTITY_TYPE": "LEAD", "ENTITY_ID": 1001069}],
    "CRM_ENTITY_TYPE": "LEAD",
    "CRM_ENTITY_ID": 1001069
  }
}

#2. Завершите звонок

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/calls/externalCall.00b1e735843c558431be668e3687a58b.1777974304/finish \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": 1, "duration": 120, "statusCode": "200"}'

#3. Прикрепите транскрипцию

Terminal

curl -X POST https://vibecode.bitrix24.tech/v1/calls/externalCall.00b1e735843c558431be668e3687a58b.1777974304/transcription \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"side": "User", "startTime": 0, "stopTime": 3, "message": "Здравствуйте, чем могу помочь?"},
      {"side": "Client", "startTime": 4, "stopTime": 8, "message": "У меня вопрос по заказу"}
    ]
  }'

Ответ:

JSON

{ "success": true, "data": { "TRANSCRIPT_ID": 3 } }

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

JavaScript-скрипт обработки входящего звонка: регистрация в CRM с автосозданием лида → отображение карточки оператору → завершение → прикрепление транскрипции → проверка статистики.

javascript

const KEY = process.env.VIBE_API_KEY
const BASE = 'https://vibecode.bitrix24.tech/v1'

async function api(method, path, body) {
  const opts = { method, headers: { 'X-Api-Key': KEY } }
  if (body) {
    opts.headers['Content-Type'] = 'application/json'
    opts.body = JSON.stringify(body)
  }
  const res = await fetch(`${BASE}${path}`, opts)
  if (res.status === 204) return null
  return res.json()
}

// 1. Регистрируем внешний звонок и создаём лид, если номера ещё нет в CRM
const reg = await api('POST', '/calls/register', {
  userId: 1,
  phoneNumber: '+79161234567',
  type: 2,
  crmCreate: true
})
const callId = reg.data.CALL_ID
console.log('Звонок зарегистрирован:', callId)
console.log('Создан лид:', reg.data.CRM_CREATED_LEAD)

// 2. Показываем карточку звонка оператору
await api('POST', `/calls/${callId}/show`, { userId: 1 })

// 3. Завершаем звонок (длительность 245 секунд, успех)
const fin = await api('POST', `/calls/${callId}/finish`, {
  userId: 1,
  duration: 245,
  statusCode: '200'
})
console.log('CRM-активность:', fin.data.CRM_ACTIVITY_ID)

// 4. Прикрепляем транскрипцию
await api('POST', `/calls/${callId}/transcription`, {
  messages: [
    { side: 'User', startTime: 0, stopTime: 4, message: 'Здравствуйте, компания Вайб!' },
    { side: 'Client', startTime: 5, stopTime: 12, message: 'Здравствуйте, я хотел бы уточнить детали заказа 4521' },
    { side: 'User', startTime: 13, stopTime: 25, message: 'Конечно, заказ отправлен, трек-номер RU123456789' }
  ]
})

// 5. Смотрим статистику за сегодня
const today = new Date().toISOString().slice(0, 10) + 'T00:00:00'
const stats = await api('GET', `/calls/statistics?filter[>CALL_START_DATE]=${today}`)
console.log(`Звонков сегодня: ${stats.total}`)

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

Метод	Путь	Bitrix24 метод	Описание
POST	/v1/calls/register	telephony.externalcall.register	Зарегистрировать внешний звонок в CRM
POST	/v1/calls/:callId/finish	telephony.externalcall.finish	Завершить звонок
POST	/v1/calls/:callId/show	telephony.externalcall.show	Показать карточку звонка оператору
POST	/v1/calls/:callId/hide	telephony.externalcall.hide	Скрыть карточку звонка
POST	/v1/calls/:callId/transcription	telephony.call.attachTranscription	Прикрепить транскрипцию
POST	/v1/calls/callback	voximplant.callback.start	Обратный звонок (оператор → клиент)
POST	/v1/calls/auto-call	voximplant.infocall.startwithtext	Автозвонок с синтезом речи
POST	/v1/calls/auto-call-audio	voximplant.infocall.startwithsound	Автозвонок с воспроизведением аудиофайла
GET	/v1/telephony-lines	telephony.externalLine.get	Список линий приложения
POST	/v1/telephony-lines	telephony.externalLine.add	Добавить линию приложения
PATCH	/v1/telephony-lines/:number	telephony.externalLine.update	Обновить линию
DELETE	/v1/telephony-lines/:number	telephony.externalLine.delete	Удалить линию
GET	/v1/voximplant-lines	voximplant.line.get	Список линий Voximplant (арендованные и SIP)
GET	/v1/calls/statistics	voximplant.statistic.get	Статистика звонков
GET	/v1/calls/voices	voximplant.tts.voices.get	Справочник голосов синтеза речи

#Коды ошибок

#Ошибки телефонии

Код	HTTP	Описание
`MISSING_PARAMS`	400	Не передан обязательный параметр (точное сообщение зависит от эндпоинта)
`INVALID_MESSAGE_SHAPE`	400	Только для `transcription`: некорректная структура одного из элементов массива `messages`
`BITRIX_ERROR`	422	Битрикс24 вернул ошибку (сообщение из B24 в поле `error.message`)
`BITRIX_UNAVAILABLE`	502	Битрикс24 недоступен

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

Код	HTTP	Описание
`MISSING_API_KEY`	401	Не передан заголовок `X-Api-Key`
`INVALID_API_KEY`	401	Неверный API-ключ
`KEY_INACTIVE`	401	API-ключ неактивен или отозван
`TOKEN_MISSING`	401	Ключ не имеет настроенных токенов Битрикс24
`SCOPE_DENIED`	403	Ключу не хватает скоупа `telephony`
`RATE_LIMITED`	429	Превышен лимит запросов

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

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

Лиды — автоматически создаются при crmCreate: true в register
Контакты — связываются со звонками по номеру телефона
Сделки — звонки попадают в таймлайн связанной сделки