# Телефония

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

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

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

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

- [Звонки в CRM](/docs/telephony/crm) — регистрация внешних звонков, завершение, карточка оператору, транскрипции
- [Исходящие звонки](/docs/telephony/outbound) — обратный звонок и автоматические звонки с синтезом речи или аудиофайлом
- [Линии](/docs/telephony/lines) — внешние линии приложения и список арендованных у Voximplant
- [Аналитика и справочники](/docs/telephony/analytics) — статистика звонков и справочник голосов для синтеза речи

---

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

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

```bash
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. Завершите звонок

```bash
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. Прикрепите транскрипцию

```bash
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](/docs/telephony/crm/register) | telephony.externalcall.register | Зарегистрировать внешний звонок в CRM |
| POST | [/v1/calls/:callId/finish](/docs/telephony/crm/finish) | telephony.externalcall.finish | Завершить звонок |
| POST | [/v1/calls/:callId/show](/docs/telephony/crm/show) | telephony.externalcall.show | Показать карточку звонка оператору |
| POST | [/v1/calls/:callId/hide](/docs/telephony/crm/hide) | telephony.externalcall.hide | Скрыть карточку звонка |
| POST | [/v1/calls/:callId/transcription](/docs/telephony/crm/transcription) | telephony.call.attachTranscription | Прикрепить транскрипцию |
| POST | [/v1/calls/callback](/docs/telephony/outbound/callback) | voximplant.callback.start | Обратный звонок (оператор → клиент) |
| POST | [/v1/calls/auto-call](/docs/telephony/outbound/auto-call) | voximplant.infocall.startwithtext | Автозвонок с синтезом речи |
| POST | [/v1/calls/auto-call-audio](/docs/telephony/outbound/auto-call-audio) | voximplant.infocall.startwithsound | Автозвонок с воспроизведением аудиофайла |
| GET | [/v1/telephony-lines](/docs/telephony/lines/list) | telephony.externalLine.get | Список линий приложения |
| POST | [/v1/telephony-lines](/docs/telephony/lines/create) | telephony.externalLine.add | Добавить линию приложения |
| PATCH | [/v1/telephony-lines/:number](/docs/telephony/lines/update) | telephony.externalLine.update | Обновить линию |
| DELETE | [/v1/telephony-lines/:number](/docs/telephony/lines/delete) | telephony.externalLine.delete | Удалить линию |
| GET | [/v1/telephony-lines/fields](/docs/telephony/lines/fields) | — | Схема полей линии приложения |
| GET | [/v1/voximplant-lines](/docs/telephony/lines/voximplant) | voximplant.line.get | Список линий Voximplant (арендованные и SIP) |
| GET | [/v1/calls/statistics](/docs/telephony/analytics/statistics) | voximplant.statistic.get | Статистика звонков |
| GET | [/v1/calls/voices](/docs/telephony/analytics/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 — [Ошибки](/docs/errors).

---

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

- [Лиды](/docs/entities/leads)
- [Контакты](/docs/entities/contacts)
- [Сделки](/docs/entities/deals)