Документация для разработчиков
Темная тема

telephony.externalcall.register

Scope: telephony Права на выполнение: для всех

Метод регистрирует звонок в Битрикс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.

Возвращаемое значение

Метод возвращает массив:

Параметр ОписаниеТип значения
CALL_ID Идентификатор звонка внутри Битрикс24.string
CRM_CREATED_LEAD Идентификатор созданного лида (создается, если в CRM не найден объект по входящему номеру)int
CRM_ENTITY_ID Идентификатор найденного в CRM объекта.int
CRM_ENTITY_TYPE Тип найденного в CRM объекта по входящему номеру CONTACT | COMPANY | LEAD.string
CRM_CREATED_ENTITIES Массив автоматически созданных в CRM сущностей при регистрации звонка. Формат:
  • ENTITY_TYPE - тип созданной сущности
  • ENTITY_ID - идентификатор созданной сущности
array
LEAD_CREATION_ERROR Текст ошибки, возникшей при попытке создания лида в CRM.string

Параметры функции

Параметр ОписаниеТип значения
USER_PHONE_INNER Внутренний номер пользователя. Обязательный.string
USER_ID Идентификатор пользователя. Обязательный.int
PHONE_NUMBER Номер телефона. Обязательныйstring
CALL_START_DATE Дата/время звонка в формате iso8601. Обратите внимание, что в дате необходимо передавать часовой пояс, для избежания искажения времени звонка. Пример: 2021-02-03T18:25:10+03:00 .string
CRM_CREATE [0/1] - Автоматическое создание в CRM сущности, связанной со звонком. При необходимости, создает в CRM лид или сделку, в зависимости от настроек и режима работы CRM Существует:
- простой режим (без лидов) - при котором будет создаваться сделка, а не лид;
- режим повторных продаж, при котором будет создавать сделка/лид даже если сущность в сrm найдена. (Но не будет создаваться если есть активная сделка/лид или номер внесен в черный список crm).
. Обратите внимание, что дело звонка создается при любом значении этого параметра, если создание возможно.
int
CRM_SOURCE STATUS_ID источника из справочника источников. Получить список источников можно методом crm.status.list с фильтром по "ENTITY_ID": "SOURCE".string
CRM_ENTITY_TYPE Тип объекта CRM, из карточки которого совершается звонок - CONTACT | COMPANY | LEAD.string
CRM_ENTITY_ID Идентификатор объекта CRM, тип которого указан в CRM_ENTITY_TYPEint
SHOW [0/1] Показывать ли карточку звонка (по умолчанию 1).int
CALL_LIST_ID Идентификатор списка обзвона, к которому должен быть привязан звонок.int
LINE_NUMBER Номер внешней линии, через который совершался звонок (см. telephony.externalLine.add). Необязательный.

Важно! Значения из этого параметра используются в сценариях сквозной аналитики Битрикс24. Поэтому решения по интеграции с телефонией для каталога Приложения24 в обязательном порядке должны передавать здесь номер, на который был совершён регистрируемый входящий звонок.

string
TYPE Обязательный. Тип звонка:
1 - исходящий
2 - входящий
3 - входящий с перенаправлением
4 - обратный
integer


Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
1
Константин Сурнин
Сообщение не промодерировано, возможны ошибки и неточности.
При указании только USER_PHONE_INNER приходит ответ {'error': '', 'error_description': 'USER_ID or USER_PHONE_INNER should be set'}
Так что USER_ID нужен в любом случае, я так понимаю
0
Михаил Долбилов
Сообщение не промодерировано, возможны ошибки и неточности.
Цитата
avtomatika-itk пишет:
Если найдено несколько различных типов объектов, то, как сообщили в службе технической поддержки, приоритет следующий: контакт => лид => компания
ОБычно все-таки такой приоритет: контакт -> компания -> лид
2
Юрий Гранд
Обратите внимание если послать одновременно две команды с одним и тем же PHONE_NUMBER то создастся 2 лида. Соответственно в том случае если ещё нет номера у вас в базе
5
avtomatika-itk
Если найдено несколько различных типов объектов, то, как сообщили в службе технической поддержки, приоритет следующий: контакт => лид => компания
© «Битрикс», 2001-2024, «1С-Битрикс», 2024