Регистрация звонка голосового ИИ в Битрикс24 связывает внешний вызов с записью в телефонии и CRM. Руководство помогает разделить события АТС, голосового компонента и CRM, сопоставить идентификаторы звонка, передать фактический исход, обработать повторные и запоздавшие события и проверить запись разговора, если она создаётся.
Краткий ответ: чтобы зарегистрировать внешний звонок голосового ИИ в Битрикс24, свяжите идентификатор вызова АТС с идентификатором звонка, полученным при регистрации, затем передайте завершение и проверьте созданное дело CRM. Готовую запись разговора прикрепляйте после завершения звонка, если она действительно создаётся в проекте и её передача предусмотрена процессом.
Разделите роли систем
До настройки определите источник каждого события. АТС или телефонный провайдер знает номер и состояние физического вызова; голосовой компонент знает этап диалога и его результат; Битрикс24 хранит зарегистрированный звонок и связанное дело. При отсутствии общей схемы один и тот же звонок может появиться дважды или быть привязан не к тому клиенту.
Согласуйте, какие данные связывают системы: внешний идентификатор звонка, направление, номер клиента, номер линии, пользователь или ответственный, время начала и номер CRM-объекта. Заранее определите, какие из этих данных существуют в каждой системе и кто их передаёт. Используйте устойчивый ID физического вызова, а не только номер телефона: один клиент может звонить повторно, а общий номер может принадлежать нескольким контактам.
Сопоставьте регистрацию и завершение
В актуальной REST-документации Битрикс24 метод telephony.externalCall.register регистрирует внешний звонок и возвращает CALL_ID; для завершения звонка используется отдельный telephony.externalCall.finish, которому нужен этот ID (регистрация внешнего звонка, завершение внешнего звонка). Поэтому сохраните связь между ID АТС и CALL_ID Битрикс24 в журнале интеграции до отправки следующего события.
Сверьте обязательные параметры, права приложения, направление вызова и нужную линию с вашей конфигурацией. Проверьте, какой CRM-объект может быть создан при регистрации и по каким признакам система ищет клиента. Не включайте автоматическое создание контакта или лида, пока владелец процесса не определил ожидаемое поведение при неизвестном номере.
Передайте реальный исход звонка
При завершении передайте фактический статус и длительность, если они доступны и соответствуют требованиям метода. Сопоставьте результат разговора с перечнем статусов команды: разговор состоялся, клиент не ответил, связь оборвалась, был перевод или потребовалась помощь сотрудника. Не трактуйте длительность как подтверждение успешного диалога: итог нужно передавать отдельно по согласованной схеме.
После ответа на завершение проверьте ID дела и запись в таймлайне CRM. Это позволяет сверить фактически сохранённый результат с событием от АТС. Если внешний обработчик получил тайм-аут, перед повторной отправкой выясните, создалась ли запись ранее. Операция с неизвестным результатом должна оставаться в журнале как ожидающая проверки.
Документация Битрикс24 отмечает, что повторная регистрация по telephony.externalCall.register в пределах 30 минут может вернуть уже существующий CALL_ID по техническим параметрам звонка. Это поведение конкретного метода; включите его в приёмочные тесты и не переносите как универсальное правило на другие вызовы или платформы.
Прикрепите запись после завершения
Если телефонная система формирует аудиозапись и проект предусматривает её хранение в CRM, проверьте её отдельно от факта регистрации звонка. В документации метод telephony.externalCall.attachRecord предназначен для прикрепления записи к завершённому звонку и вызывается после finish, когда запись готова (прикрепление записи к завершённому звонку). Отсутствие файла не должно превращаться в фиктивную ссылку или сообщение об успешном прикреплении.
Проверьте, что загруженный файл относится к правильному звонку, открывается у пользователя с нужными правами и совпадает по длительности с ожидаемым материалом. Если запись появляется с задержкой, отдельно зафиксируйте её событие готовности и правило повторной передачи.
Проверьте повторы и несопоставленные события
Проведите тесты для успешного входящего и исходящего звонка, пропущенного вызова, обрыва до разговора, запоздавшего завершения, повторного уведомления и поздно готовой записи. Для каждого сценария заранее укажите ожидаемую карточку CRM, номер линии, статус, длительность и результат прикрепления файла.
Обычный звонок может пройти регистрацию и завершение автоматически, если ID и CRM-связь определены однозначно. Отправьте событие на ручную проверку, если внешний ID отсутствует, контакт сопоставлен неоднозначно, события пришли в невозможном порядке, запись не прикрепилась или ответственному нужна интерпретация разговора. Если сам клиент просит сотрудника, событие передачи должно сохранить этот исход в связанном контексте.
Таблица приёмки
| Проверка | Ожидаемое состояние в Битрикс24 | Что сравнить |
|---|---|---|
| Начало разговора | Появился зарегистрированный звонок | ID АТС, CALL_ID, номер и линия |
| Нормальное завершение | В CRM появилось дело с исходом | Статус, длительность, ответственный |
| Повторная регистрация | Не создана лишняя несвязанная запись | Результат поиска по внешнему ID |
| Позднее завершение | Звонок связан с ранее зарегистрированным | Идентификаторы и время |
| Готовая запись | Файл связан с завершённым звонком | Доступность и правильность файла |
Ограничения и обсуждение проекта
Методы относятся к REST API Битрикс24 и работают в условиях, которые описаны в документации метода. Доступ, доступность нужной линии, правила сопоставления CRM и фактическое хранение аудио проверяются отдельно. Эта статья рассматривает учёт телефонного жизненного цикла; подключение чат-бота к Открытым линиям описано в материале об интеграции ИИ с Битрикс24, а общая передача контекста — в руководстве по интеграции с CRM.
Для обсуждения подготовки интеграции выпишите источники событий, примеры повторных уведомлений и ожидаемые записи CRM на странице внедрения.
Частые вопросы
Когда в Битрикс24 прикреплять запись телефонного разговора?
В официальном REST-описании `telephony.externalCall.attachRecord` указано, что запись прикрепляется к завершённому звонку после вызова `telephony.externalCall.finish`, когда файл уже готов.
Что проверить при повторной регистрации одного звонка?
Проверьте внешний идентификатор, `CALL_ID` и параметры поиска существующей регистрации. Поведение метода при повторе нужно подтвердить в тестовом проекте, прежде чем принимать интеграцию.
Никита Воробьёв
Внедряю ИИ-сотрудников для чатов, мессенджеров и телефонной первой линии.
Обновлено: . Как устроены материалы
О моём подходе