#Телефония

Управляйте внешними звонками через REST API. Регистрация звонков, автозвонки с синтезом речи и аудио, обратные звонки, транскрипции, статистика и TTS-голоса.

#Обзор

Telephony API — обёртка над Bitrix24 REST API (telephony.*, voximplant.*). Позволяет регистрировать внешние звонки в CRM, запускать автозвонки с синтезом речи, прикреплять транскрипции и аудиозаписи, делать обратные звонки и получать статистику.

Требуемый скоуп: telephony

Базовый URL: https://vibecode.bitrix24.tech/v1

Авторизация: заголовок X-Api-Key с вашим API-ключом.

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

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

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

Ответ:

JSON 
{
  "success": true,
  "data": {
    "CALL_ID": "externalCall.abc123",
    "CRM_CREATED_ENTITIES": ["CONTACT_1"]
  }
}

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/externalCall.abc123/finish \
  -H "X-Api-Key: $VIBE_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.abc123/transcription \
  -H "X-Api-Key: $VIBE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Оператор: Добрый день, компания ВибеКод.\nКлиент: Здравствуйте, хочу узнать про API."
  }'

#Регистрация звонка

#POST /v1/calls/register

Регистрирует внешний звонок в Битрикс24. Создаёт запись о звонке и автоматически привязывает к CRM-сущности по номеру телефона.

Bitrix24 метод: telephony.externalcall.register

Параметр В Тип Обяз. По умолч. Описание
userId body number да — ID пользователя Битрикс24, совершающего звонок
phoneNumber body string да — Номер телефона клиента
type body number нет — Тип звонка: 1 — исходящий, 2 — входящий
lineNumber body string нет — Номер внешней линии
crmCreate body boolean нет — Создать CRM-сущность, если не найдена по номеру
Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/calls/register \
  -H "X-Api-Key: $VIBE_KEY" \
  -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': VIBE_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    userId: 1,
    phoneNumber: '+79161234567',
    type: 2,
    crmCreate: true
  })
})

const { data } = await res.json()
console.log('Call ID:', data.CALL_ID)
console.log('CRM entities:', data.CRM_CREATED_ENTITIES)

Ответ:

JSON 
{
  "success": true,
  "data": {
    "CALL_ID": "externalCall.abc123",
    "CRM_CREATED_ENTITIES": ["CONTACT_1"],
    "CRM_ENTITY_TYPE": "CONTACT",
    "CRM_ENTITY_ID": 42
  }
}

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