[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"docs-telephony":3,"docs-tabs-telephony":6},{"content":4,"lastmod":5},"# Телефония\n\nУправление телефонией Битрикс24: регистрация внешних звонков в CRM, исходящие автоматические звонки и обратный звонок, прикрепление транскрипций, статистика звонков, управление линиями приложения.\n\n**Скоуп:** `telephony` | **Базовый URL:** `https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1` | **Авторизация:** `X-Api-Key`\n\n[Быстрый старт](#быстрый-старт) | [Полный пример](#полный-пример) | [Справочник эндпоинтов](#справочник-эндпоинтов) | [Коды ошибок](#коды-ошибок)\n\n## Разделы документации\n\n- [Звонки в CRM](\u002Fdocs\u002Ftelephony\u002Fcrm) — регистрация внешних звонков, завершение, карточка оператору, транскрипции\n- [Исходящие звонки](\u002Fdocs\u002Ftelephony\u002Foutbound) — обратный звонок и автоматические звонки с синтезом речи или аудиофайлом\n- [Линии](\u002Fdocs\u002Ftelephony\u002Flines) — внешние линии приложения и список арендованных у Voximplant\n- [Аналитика и справочники](\u002Fdocs\u002Ftelephony\u002Fanalytics) — статистика звонков и справочник голосов для синтеза речи\n\n---\n\n## Быстрый старт\n\n### 1. Зарегистрируйте звонок\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fcalls\u002Fregister \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"userId\": 1,\n    \"phoneNumber\": \"+79161234567\",\n    \"type\": 2,\n    \"crmCreate\": true\n  }'\n```\n\nОтвет (HTTP 201):\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"CALL_ID\": \"externalCall.00b1e735843c558431be668e3687a58b.1777974304\",\n    \"CRM_CREATED_LEAD\": 1001069,\n    \"CRM_CREATED_ENTITIES\": [{\"ENTITY_TYPE\": \"LEAD\", \"ENTITY_ID\": 1001069}],\n    \"CRM_ENTITY_TYPE\": \"LEAD\",\n    \"CRM_ENTITY_ID\": 1001069\n  }\n}\n```\n\n### 2. Завершите звонок\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fcalls\u002FexternalCall.00b1e735843c558431be668e3687a58b.1777974304\u002Ffinish \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\"userId\": 1, \"duration\": 120, \"statusCode\": \"200\"}'\n```\n\n### 3. Прикрепите транскрипцию\n\n```bash\ncurl -X POST https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1\u002Fcalls\u002FexternalCall.00b1e735843c558431be668e3687a58b.1777974304\u002Ftranscription \\\n  -H \"X-Api-Key: YOUR_API_KEY\" \\\n  -H \"Content-Type: application\u002Fjson\" \\\n  -d '{\n    \"messages\": [\n      {\"side\": \"User\", \"startTime\": 0, \"stopTime\": 3, \"message\": \"Здравствуйте, чем могу помочь?\"},\n      {\"side\": \"Client\", \"startTime\": 4, \"stopTime\": 8, \"message\": \"У меня вопрос по заказу\"}\n    ]\n  }'\n```\n\nОтвет:\n\n```json\n{ \"success\": true, \"data\": { \"TRANSCRIPT_ID\": 3 } }\n```\n\n---\n\n## Полный пример\n\nJavaScript-скрипт обработки входящего звонка: регистрация в CRM с автосозданием лида → отображение карточки оператору → завершение → прикрепление транскрипции → проверка статистики.\n\n```javascript\nconst KEY = process.env.VIBE_API_KEY\nconst BASE = 'https:\u002F\u002Fvibecode.bitrix24.tech\u002Fv1'\n\nasync function api(method, path, body) {\n  const opts = { method, headers: { 'X-Api-Key': KEY } }\n  if (body) {\n    opts.headers['Content-Type'] = 'application\u002Fjson'\n    opts.body = JSON.stringify(body)\n  }\n  const res = await fetch(`${BASE}${path}`, opts)\n  if (res.status === 204) return null\n  return res.json()\n}\n\n\u002F\u002F 1. Регистрируем внешний звонок и создаём лид, если номера ещё нет в CRM\nconst reg = await api('POST', '\u002Fcalls\u002Fregister', {\n  userId: 1,\n  phoneNumber: '+79161234567',\n  type: 2,\n  crmCreate: true\n})\nconst callId = reg.data.CALL_ID\nconsole.log('Звонок зарегистрирован:', callId)\nconsole.log('Создан лид:', reg.data.CRM_CREATED_LEAD)\n\n\u002F\u002F 2. Показываем карточку звонка оператору\nawait api('POST', `\u002Fcalls\u002F${callId}\u002Fshow`, { userId: 1 })\n\n\u002F\u002F 3. Завершаем звонок (длительность 245 секунд, успех)\nconst fin = await api('POST', `\u002Fcalls\u002F${callId}\u002Ffinish`, {\n  userId: 1,\n  duration: 245,\n  statusCode: '200'\n})\nconsole.log('CRM-активность:', fin.data.CRM_ACTIVITY_ID)\n\n\u002F\u002F 4. Прикрепляем транскрипцию\nawait api('POST', `\u002Fcalls\u002F${callId}\u002Ftranscription`, {\n  messages: [\n    { side: 'User', startTime: 0, stopTime: 4, message: 'Здравствуйте, компания Вайб!' },\n    { side: 'Client', startTime: 5, stopTime: 12, message: 'Здравствуйте, я хотел бы уточнить детали заказа 4521' },\n    { side: 'User', startTime: 13, stopTime: 25, message: 'Конечно, заказ отправлен, трек-номер RU123456789' }\n  ]\n})\n\n\u002F\u002F 5. Смотрим статистику за сегодня\nconst today = new Date().toISOString().slice(0, 10) + 'T00:00:00'\nconst stats = await api('GET', `\u002Fcalls\u002Fstatistics?filter[>CALL_START_DATE]=${today}`)\nconsole.log(`Звонков сегодня: ${stats.total}`)\n```\n\n---\n\n## Справочник эндпоинтов\n\n| Метод | Путь | Bitrix24 метод | Описание |\n|-------|------|----------------|---------|\n| POST | [\u002Fv1\u002Fcalls\u002Fregister](\u002Fdocs\u002Ftelephony\u002Fcrm\u002Fregister) | telephony.externalcall.register | Зарегистрировать внешний звонок в CRM |\n| POST | [\u002Fv1\u002Fcalls\u002F:callId\u002Ffinish](\u002Fdocs\u002Ftelephony\u002Fcrm\u002Ffinish) | telephony.externalcall.finish | Завершить звонок |\n| POST | [\u002Fv1\u002Fcalls\u002F:callId\u002Fshow](\u002Fdocs\u002Ftelephony\u002Fcrm\u002Fshow) | telephony.externalcall.show | Показать карточку звонка оператору |\n| POST | [\u002Fv1\u002Fcalls\u002F:callId\u002Fhide](\u002Fdocs\u002Ftelephony\u002Fcrm\u002Fhide) | telephony.externalcall.hide | Скрыть карточку звонка |\n| POST | [\u002Fv1\u002Fcalls\u002F:callId\u002Ftranscription](\u002Fdocs\u002Ftelephony\u002Fcrm\u002Ftranscription) | telephony.call.attachTranscription | Прикрепить транскрипцию |\n| POST | [\u002Fv1\u002Fcalls\u002Fcallback](\u002Fdocs\u002Ftelephony\u002Foutbound\u002Fcallback) | voximplant.callback.start | Обратный звонок (оператор → клиент) |\n| POST | [\u002Fv1\u002Fcalls\u002Fauto-call](\u002Fdocs\u002Ftelephony\u002Foutbound\u002Fauto-call) | voximplant.infocall.startwithtext | Автозвонок с синтезом речи |\n| POST | [\u002Fv1\u002Fcalls\u002Fauto-call-audio](\u002Fdocs\u002Ftelephony\u002Foutbound\u002Fauto-call-audio) | voximplant.infocall.startwithsound | Автозвонок с воспроизведением аудиофайла |\n| GET | [\u002Fv1\u002Ftelephony-lines](\u002Fdocs\u002Ftelephony\u002Flines\u002Flist) | telephony.externalLine.get | Список линий приложения |\n| POST | [\u002Fv1\u002Ftelephony-lines](\u002Fdocs\u002Ftelephony\u002Flines\u002Fcreate) | telephony.externalLine.add | Добавить линию приложения |\n| PATCH | [\u002Fv1\u002Ftelephony-lines\u002F:number](\u002Fdocs\u002Ftelephony\u002Flines\u002Fupdate) | telephony.externalLine.update | Обновить линию |\n| DELETE | [\u002Fv1\u002Ftelephony-lines\u002F:number](\u002Fdocs\u002Ftelephony\u002Flines\u002Fdelete) | telephony.externalLine.delete | Удалить линию |\n| GET | [\u002Fv1\u002Fvoximplant-lines](\u002Fdocs\u002Ftelephony\u002Flines\u002Fvoximplant) | voximplant.line.get | Список линий Voximplant (арендованные и SIP) |\n| GET | [\u002Fv1\u002Fcalls\u002Fstatistics](\u002Fdocs\u002Ftelephony\u002Fanalytics\u002Fstatistics) | voximplant.statistic.get | Статистика звонков |\n| GET | [\u002Fv1\u002Fcalls\u002Fvoices](\u002Fdocs\u002Ftelephony\u002Fanalytics\u002Fvoices) | voximplant.tts.voices.get | Справочник голосов синтеза речи |\n\n---\n\n## Коды ошибок\n\n### Ошибки телефонии\n\n| Код | HTTP | Описание |\n|-----|------|---------|\n| `MISSING_PARAMS` | 400 | Не передан обязательный параметр (точное сообщение зависит от эндпоинта) |\n| `INVALID_MESSAGE_SHAPE` | 400 | Только для `transcription`: некорректная структура одного из элементов массива `messages` |\n| `BITRIX_ERROR` | 422 | Битрикс24 вернул ошибку (сообщение из B24 в поле `error.message`) |\n| `BITRIX_UNAVAILABLE` | 502 | Битрикс24 недоступен |\n\n### Системные ошибки\n\n| Код | HTTP | Описание |\n|-----|------|---------|\n| `MISSING_API_KEY` | 401 | Не передан заголовок `X-Api-Key` |\n| `INVALID_API_KEY` | 401 | Неверный API-ключ |\n| `KEY_INACTIVE` | 401 | API-ключ неактивен или отозван |\n| `TOKEN_MISSING` | 401 | Ключ не имеет настроенных токенов Битрикс24 |\n| `SCOPE_DENIED` | 403 | Ключу не хватает скоупа `telephony` |\n| `RATE_LIMITED` | 429 | Превышен лимит запросов |\n\nПолный список общих ошибок API — [Ошибки](\u002Fdocs\u002Ferrors).\n\n---\n\n## Смотрите также\n\n- [Лиды](\u002Fdocs\u002Fentities\u002Fleads) — автоматически создаются при `crmCreate: true` в register\n- [Контакты](\u002Fdocs\u002Fentities\u002Fcontacts) — связываются со звонками по номеру телефона\n- [Сделки](\u002Fdocs\u002Fentities\u002Fdeals) — звонки попадают в таймлайн связанной сделки\n","2026-06-24",{}]