Вебхуки коллтрекинга

В этой статье обобщенно описана интеграция Коллтрекинга MANGO OFFICE с внешними бизнес-системами при помощи Webhooks (вебхуки). Информацию о других интеграциях, при помощи API MANGO OFFICE, вы можете найти в статье Кастомные интеграции

Обзор

Назначение и типы вебхуки

В коллтрекинге есть возможность передавать четыре типа вебхуки, они перечислены в таблице ниже:

Тип вебхука	Событие на Вашем сайте, при совершении которого коллтрекинг передает вебхук	Ограничения по отправке вебхука данного типа
На начало звонка	При звонке на номер коллтрекинга, коллтрекинг отправляет вебхук с определенными Вами параметрами на указанный Вами URL.	-
На конец звонка	Сразу после завершения звонка на номер коллтрекинга, коллтрекинг отправляет вебхук с определенными Вами параметрами на указанный Вами URL.	-
Обратный звонок	При поступлении заказа через виджет «Заказ обратного звонка MANGO OFFICE», коллтрекинг отправляет вебхук с определенными Вами параметрами на указанный Вами URL.	1) на Вашем сайте должен быть установлен виджет «Заказ обратного звонка MANGO OFFICE», при помощи которого Клиент сможет оставить заявку на обратный звонок; 2) интеграция коллтрекинга с виджетом «Заказ обратного звонка MANGO OFFICE» должна быть выполнена в Личном кабинете MANGO OFFICE.
Заявка с сайта	При поступлении обращения с сайта, коллтрекинг отправляет вебхук с определенными Вами параметрами на указанный Вами URL.	1) на Вашем сайте должна быть установлена форма для обращения Клиентов (другое ее название – Форма обратной связи, ФОС); 2) интеграция коллтрекинга с ФОС должна быть выполнена в Личном кабинете MANGO OFFICE.

Коллтрекинг передает вебхуки в режиме реального времени (real-time).

Подключив и настроив опцию "Вебхуки", Вы сможете передавать в Ваши внешние аналитические системы информацию о событиях, перечисленных в таблице выше. Интеграция с коллтрекингом через вебхуки может быть полезна для CRM-систем, систем сквозной аналитики, систем управления контекстной рекламой и внутренних аналитических систем рекламных агентств.

Обобщённое описание принципа работы вебхуки коллтрекинга

Принцип работы вебхуков следующий: коллтрекинг в момент совершения события на Вашем сайте будет отправлять GET-запрос на указанный в настройках вебхуков URL и передавать рекламные метки и другую информацию о событии в виде параметров. Соответственно, внешняя система сможет привязать звонок/обращение к конкретному контрагенту (если это CRM) или посетителю сайта и корректно отобразить данные о звонке, посетителе сайта и рекламных параметрах в собственных отчетах.

Подключение и настройка вебхуков

Чтобы подключить вебхуки, на сайте «Личный кабинет» в разделе "Коллтрекинг" следует:

выберите пункт "Настройки";
выберите API;
выберите виджет коллтрекинга, который будем настраивать;
проверьте, создан ли Token для работы API. Для этого проверьте, указана ли строка символов в поле «Идентификатор, использующийся для обращения к API коллтрекинга», а также в группе «Доступные методы API» перечислены доступные Вам методы API, см. рисунок ниже. Если токен не создан, нажмите кнопку «Создать токен»;
выполните одно из следующих действий:

если Вы создаете первый вебхук, то на странице «API» в блоке «Вебхуки» будет отображаться поле «Вебхуки необходимы для отправки данных в ваши…», в котором нужно выбрать тип вебхука, который будем настраивать;
если Вы создаете второй и последующий вебхуки, то на странице «API» в блоке «Вебхуки» будет отображаться список ранее созданных вебхуков и кнопки и . Вам нужно нажать на кнопку , затем выбрать тип вебхука, который будем настраивать;

нажмите кнопку «Создать вебхук»:

В открывшемся конструкторе вебхуков, выполните следующие действия:

введите URL-адрес вебхука, на который необходимо передавать информацию. Формат URL адреса для вебхука следующий:

https://example.com/

где:

https или http – протокол;
example.com - URL-адрес вебхука;

установите "галочки" в нужных Вам параметрах вебхука. В правой части конструктора вебхуков будет показано название параметра, то как тот или иной параметр будет называться в вебхуке; Параметры вебхуки разные для каждого события. Описание параметров вебхука смотрите в таблице.
нажмите кнопку "Сохранить":

На открывшейся странице "API" выполните:

нажмите кнопку "Скопировать ссылку";
нажмите кнопку Сохранить;
если Вам необходимо отправлять данные на несколько адресов, добавьте еще один вебхук и настройте его аналогично.

Параметры, передаваемые в вебхуки и их описание

Все доступные наименования параметров коллтрекинга перечислены в таблице ниже. Вы можете использовать их все (или часть из них) в любой комбинации в параметрах URL.

Название	Тип данных	Описание

Базовые параметры вебхуков
webhookType	number	Тип вебхуки. Возможные значения: 1 - Старт звонка, 2 - Конец звонка, 3 - ФОС, 4 - ОЗ
callId	number	id звонка
dateStart	date	Время поступления звонка в формате ISO 8601, DD-MM-YYYYThh:mmZ
dateEnd	date	Время окончания звонка в формате ISO 8601, DD-MM-YYYYThh:mmZ
callType	number	Тип звонка: 1 - динамический, 2 - статический, 3 - дефолтный
callStatus	number	Статус завершения звонка как в ВАТС API, 11XX- звонок был принят, иначе - отклонён
number	number	Динамический номер, на который был принят звонок
callerNumber	number	Номер звонившего
duration	number	Продолжительность звонка в секундах. Считается только продолжительность разговора с оператором. Без учета времени ожидания в IVR и ожидания распределения звонка внутри группы операторов.
waitDuration	number	Время ожидания до соединения с оператором в секундах
isNew	boolean	Флаг уникального звонка
isQuality	boolean	Флаг качественного звонка
isDuplicate	boolean	Флаг того, что с этого номера звонили последние 3 месяца
uid	string	Уникальный идентификатор клиента MANGO OFFICE
gaCid	string	Идентификатор клиента Google Analytics
yaCid	string	Идентификатор клиента Яндекс.Метрики
rsCid	string	Идентификатор сеанса (визита), используемый в системе "Roistat"
utmSource	string	Источник
utmMedium	string	Канал
utmCampaign	string	Кампания
utmContent	string	Содержание (объявления)
utmTerm	string	Ключевое слово
countryCode	string	Код ISO страны
regionCode	string	Код ISO региона
city	string	Название города
device	string	Тип устройства: desktop, tablet или mobile
ip	string	IP адрес пользователя
URLl	string	Адрес страницы сайта, с которой был совершен звонок
firstUrl	string	Адрес страницы входа пользователя на сайт
customParam	string	Дополнительные параметры, передаваемые в код виджета тем, кто разместил его на сайте. Ограничение - 4000 символов.
lastGroup	string	Название группы операторов, сотрудник которой обработал звонок
recordUrl	string	URL для скачивания записи разговора
Специальные параметры для ФОС

name	string	Имя пользователя
number	number	Номер телефона пользователя в формате 79451112233
email	string	Электронная почта пользователя
subject	string	Тема ФОС
comment	string	Комменты ФОС
Специальные параметры для ОЗ

callId	number	Id звонка
dateStart	date	Время поступления звонка
callerNumber	number	Номер звонившего
number	number	Номер, на который был принят звонок
dateEnd	date	Время окончания звонка
callStatus	number	Статус завершения звонка
duration	number	Продолжительность звонка в секундах
waitDuration	number	Время ожидания до соединения с оператором в секундах