При разработке и поддержке проектов на платформе 1С-Битрикс критически важно использовать современные стандарты D7 API. В этом руководстве мы детально изучим тему «Зарегистрировать звонок в Битрикс24 telephony.externalcall.register», разберем архитектурные особенности и предоставим готовые к интеграции примеры кода.
Зарегистрировать звонок в Битрикс24 telephony.externalcall.register
Тут может не хватать некоторых данных — дополним в ближайшее время
- отсутствуют примеры
- отсутствует ответ в случае успеха
- отсутствует ответ в случае ошибки
Метод telephony.externalcall.register регистрирует звонок в Битрикс24, для чего ищет в CRM соответствующий номеру объект. Если находит, то добавляет звонок в привязке к найденному объекту. Если не находит, то может автоматически создать лид.
При использовании telephony.externalcall.register ответственным за новый лид будет автоматически назначен первый ответственный за данного клиента ранее. Сменить такого ответственного можно в дальнейшем через telephony.externalcall.finish.
Одновременно с регистрацией звонка метод опционально может показать пользователю карточку звонка. Пользователь, которому показывается карточка, идентифицируется либо по USER_ID, либо по USER_PHONE_INNER. (То есть поля помечены как обязательные, но фактически нужно только одно из двух.)
Не нужно повторно вызывать этот метод для звонков, полученных на событии OnExternalCallStart. Эти звонки уже зарегистрированы в системе и для них надо вызывать только telephony.externalcall.finish в конце звонка.
Повторный вызов
telephony.externalcall.register с теми же параметрами, без закрытия предыдущего звонка методом telephony.externalcall.finish, выдает тот же CALL_ID в течение 30 минут.Для создания дела «звонок» необходимо также вызывать метод telephony.externalcall.finish.
| Параметр / Тип | Описание | ||
|---|---|---|---|
USER_PHONE_INNER^^ string | Внутренний номер пользователя. | ||
USER_ID^^ int | Идентификатор пользователя. | ||
PHONE_NUMBER^^ string | Номер телефона. | ||
CALL_START_DATE string | Дата/время звонка в формате iso8601. Обратите внимание, что в дате необходимо передавать часовой пояс, для избежания искажения времени звонка. Пример: 2021-02-03T18:25:10+03:00. | ||
CRM_CREATE int | [0\/1] — Автоматическое создание в CRM сущности, связанной со звонком. При необходимости создает в CRM лид или сделку, в зависимости от настроек и режима работы CRM. Обратите внимание, что дело звонка создается при любом значении этого параметра, если создание возможно. | ||
CRM_SOURCE string | STATUS_ID источника из справочника источников. Получить список источников можно методом crm.status.list с фильтром по «ENTITY_ID»: «SOURCE». | ||
CRM_ENTITY_TYPE string | Тип объекта CRM, из карточки которого совершается звонок — CONTACT \ | COMPANY \ | LEAD. |
CRM_ENTITY_ID int | Идентификатор объекта CRM, тип которого указан в CRM_ENTITY_TYPE. | ||
SHOW int | [0/1] Показывать ли карточку звонка (по умолчанию 1). | ||
CALL_LIST_ID int | Идентификатор списка обзвона, к которому должен быть привязан звонок. | ||
LINE_NUMBER string | Номер внешней линии, через который совершался звонок (см. telephony.externalLine.add). Значения из этого параметра используются в сценариях сквозной аналитики Битрикс24. Поэтому решения по интеграции с телефонией для каталога Приложения24 в обязательном порядке должны передавать здесь номер, на который был совершён регистрируемый входящий звонок. | ||
TYPE^^ integer | Тип звонка: 1 — исходящий 2 — входящий 3 — входящий с перенаправлением 4 — обратный |
Возвращаемые данные
| Значение / Тип | Описание | ||
|---|---|---|---|
CALL_ID string | Идентификатор звонка внутри Битрикс24. | ||
CRM_CREATED_LEAD int | Идентификатор созданного лида (создается, если в CRM не найден объект по входящему номеру). | ||
CRM_ENTITY_ID int | Идентификатор найденного в CRM объекта. | ||
CRM_ENTITY_TYPE string | Тип найденного в CRM объекта по входящему номеру CONTACT \ | COMPANY \ | LEAD. |
CRM_CREATED_ENTITIES array | Массив автоматически созданных в CRM сущностей при регистрации звонка. Формат: — ENTITY_TYPE — тип созданной сущности — ENTITY_ID — идентификатор созданной сущности | ||
LEAD_CREATION_ERROR string | Текст ошибки, возникшей при попытке создания лида в CRM. |
[mode]: Существует:
- простой режим (без лидов) — при котором будет создаваться сделка, а не лид;
- режим повторных продаж, при котором будет создавать сделка/лид даже если сущность в сrm найдена. (Но не будет создаваться если есть активная сделка/лид или номер внесен в черный список crm).
💡 Экспертное мнение и рекомендации
Практические рекомендации:
- При написании кастомных компонентов для «Зарегистрировать звонок в Битрикс24 telephony.externalcall.register» всегда разделяйте бизнес-логику и представление (шаблон).
- Используйте отладку SQL-запросов через конструкцию
$wpdb->last_queryили стандартный трекер Битрикса, чтобы контролировать нагрузку.
Похожая задача в бизнесе?
Помогу автоматизировать процессы и внедрить ИИ
Меня зовут Андрей Горошко. Я Full-stack разработчик и эксперт по 1С-Битрикс. Настраиваю CRM Битрикс24, разрабатываю защищенные API и создаю умных ИИ-агентов для автоматизации рутины.
или на почту: gorandvas@yandex.ru
