Отправка информации из Calltouch с помощью webhook'ов

Webhook - это исходящий HTTP-запрос, отправляемый в момент наступления определенного события. В запросе передается информация о лиде согласно выбранным настройкам.  C помощью вебхуков вы можете интегрировать Calltouch с внешними системами - для этого вам необходимо настроить отправку вебхуков в личном кабинете Calltouch. Добавить и настроить webhook'и можно в меню "Интеграции", раздел «Отправка данных во внешние системы - API и Webhooks»:

В каком формате передаются webhook'и

Данные передаются в виде GET или POST запроса с набором выбранных параметров. Все данные, передаваемые в webhook'ах, проходят URL Encode и кодируются ASCII символами. При обработке данных на своей стороне, используйте, пожалуйста, URL Decoder для расшифровки значений параметров.

Адреса API/webhook серверов Calltouch

Вебхуки отправляются с наших серверов, расположенных на подсети 92.118.66.0/23. Эту подсеть необходимо добавить в список исключений файрволла на стороне вашего сервера.

Для тестирования вебхуков используйте сервис https://pipedream.com. Если вебхук приходит на тестовый сервер, но не приходит вам – значит причины необходимо искать на стороне вашего сервера.

Для добавления нового webhook'а, кликните на соответствующую кнопку "Добавить webhook":

Если вам необходимо настроить отправку уведомлений о чатах, зафиксированных в Calltouch, на ваш сервер в виде POST или GET запросов, перейдите на соответствующую вкладку для добавления webhook'а . 

И затем в открывшемся окне произведите настройки webhook'а , которые подробно описаны далее:

Настройка адреса обработчика webhook'а

Необходимо указать HTTP(S) адрес обработчика webhook'ов на вашем сервере, на который будут отправляться HTTP-запросы с нашей стороны автоматически при наступлении определенного события.

Домен в указываемом адресе обработчика не обязательно должен быть подключен к нашему сервису для отслеживания звонков, заявок с него - главное чтобы на нем присутствовало какое-либо приложение для регистрации webhook'ов.

Пример простого обработчика webhook'ов на PHP

Представленный пример парсит получаемый GET-запрос webhook'а, разбивая его по строкам и отправляет результат в письме с темой «Webhooks Test» на указанную Вами почту test@test.ru:

Скопировать скрипт:

<?php
$params = $_GET;
$mail_body = '';
foreach ($params as $k => $param){
if (!is_array($param))
$mail_body .= $k.' = '.$param."\n";
else
$mail_body .= $k.' = '.var_export($param, true)."\n";
}
mail("test@test.ru", "Webhooks Test", $mail_body);
?>
   

Вы можете протестировать этот пример, сохранив его в .php файл, расположенный на вашем сервере, и в настройках webhook'ах указать адрес к этому файлу в качестве обработчика. В зависимости от настроек, описываемых далее, на указанную вами почту в коде обработчика по факту начала и/или завершения звонка поступят webhook'и следующего содержания:

Рассматриваемый обработчик, отправляющий только письма на почту, является просто примером. Возможности же вашего собственного обработчика webhook'ов ничем не ограничены.

Метод отправки webhook'ов

По умолчанию webhook отправляется с помощью метода POST. Однако, вы можете изменить метод отправки на GET с помощью выпадающего меню:

В чем разница между методами отправки GET и POST?

Существует множество отличий между этими методами, из которых можно выделить три основных:

Модель атрибуции лидов в webhook'ах

Модель атрибуции - эта правило определения источников для звонков и заявок. Источник обращения, переданный в webhook'е, может быть определен по одной из моделей атрибуции:

• Последний непрямой (по умолчанию) - источник обращения определится по последнему непрямому переходу на сайт. Если прямой переход на сайт будет единственным переходом перед совершением звонка или отправкой заявки, то источник определится как прямой переход. Источник "прямой переход" в статистики Calltouch обозначается как (direct) / (none).
• Последнее взаимодействие - источник обращения определится по последнему переходу на сайт перед совершением звонка или отправкой заявки.

Модель атрибуции выбирается из выпадающего списка:

 Данные настройки моделей атрибуций для webhook'ов не повлияют на отображение статистики в отчетах личного кабинета Calltouch. Модель атрибуции для отчетов настраивается в разделе личного кабинета Calltouch: Настройки => Статистика.

В чем разница моделей атрибуции лидов в webhook'ах?

Предположим, вы настроили два webhook'а по событию начала звонка - первый с моделью атрибуции "Последнее взаимодействие", второй с моделью атрибуции "Последний непрямой". Затем посетитель днем с работы перешел на ваш сайт по платной рекламе yandex / cpc, ознакомился с контентом вашего сайта, добавил ваш сайт в закладки браузера и взял паузу на принятие решения. Вечером с того же устройства и браузера он вернулся на ваш сайт из закладок и совершил звонок. Переход из закладок браузера равносилен прямому переходу на сайт, в Calltouch он обозначается как (direct) / (none). На указанный вами адрес отправятся два webhook'а по одному и тому же звонку, но с разными моделями атрибуций, где источник звонка будет равен:

• в webhook'е с моделью атрибуции "Последнее взаимодействие" источник звонка = прямой переход (direct) / (none);
• в webhook'е с моделью атрибуции "Последний непрямой" источник звонка = платная реклама yandex / cpc.

Таким образом, источник одного и того же звонка определился по разному в каждом webhook'е, в соответствии с выбранной моделью атрибуции.

Метрики для отправок webhook'ов

По умолчанию отправка осуществляется по всем лидам. Однако, в зависимости от ваших потребностей, есть возможность ограничить HTTP-запросы только по определенным видам и типам лидов. Например, настроить отправку только для уникальных звонков и уникальных заявок: 

Обратите внимание, что ограничив список лидов, вы рискуете пропустить важную информацию.

Фильтр лидов по тегам

По умолчанию отправка осуществляется по всем лидам. Однако, в зависимости от ваших потребностей, есть возможность ограничить HTTP-запросы только по лидам, имеющим определенный тег. Например, настроить отправку только лидов с тегом "Отдел продаж": 

Обратите внимание, что ограничив список лидов, вы рискуете пропустить важную информацию. Также обращаем внимание, что ограничение не распространяется на отправку вебхуков по событию начала звонка.

Фильтр лидов по трафику

По умолчанию отправка осуществляется по всем лидам. Однако, в зависимости от ваших потребностей, есть возможность ограничить HTTP-запросы только по лидам, имеющим определенный источник. Например, настроить отправку только лидов, пришедших с платной рекламы: 

Обратите внимание, что ограничив список лидов, вы рискуете пропустить важную информацию. Также обращаем внимание, что источник лида определяется согласно выбранной модели атрибуции в настройках вебхука.

Модель отправки

На выбор представлено 2 модели отправок:

• Упрощенная (по умолчанию) - модель, в рамках которой доступны 3 триггера для отправок: начало звонка, завершение звонка и создание заявки. Отличительной возможностью данной модели является опциональная отсрочка для событий завершения звонка и создания заявки. Установка отсрочек позволяет дождаться наиболее полной информации о лиде (например, автоматического тегирования Calltouch Предикт) и отправить ее на ваш сервер однократно. Максимальная величина задержки - 1440 минут, то есть 1 сутки. Список доступных событий:
  • Начало звонка;
  • Завершение звонка;
  • Создание заявки.
• Событийная - модель, в рамках которой отправка HTTP-запросов происходит без каких-либо агрегаций сразу по наступлению события, на который подписан вебхук. При срабатывании триггера, на ваш сервер будет отправлен весь набор выбранных параметров согласно настройкам. Список доступных событий:
  • Начало звонка;
  • Завершение звонка;
  • Создание заявки;
  • Изменение статуса звонка;
  • Изменение признака «Спам» у звонка;
  • Расшифровка звонка в текст;
  • Изменение тегов;
  • Изменение комментариев;
  • Изменение менеджера;
  • Изменение рейтинга.

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

Как идентифицировать webhook'и одного и того же лида

В рамках одного лида может быть отправлено несколько HTTP-запросов. Идентифицировать webhook'и в рамках одного лида можно по его идентификатору:

• id - идентификатор звонка внутри Calltouch;
• requestId - идентификатор заявки внутри Calltouch.

На следующей табе "Передаваемая информация" необходимо выбрать параметры звонков и заявок, которые будут отправлены в webhook'е в вашу систему на указанный адрес обработчика:

По умолчанию передаются все параметры лидов. С помощью чекбоксов напротив названия каждого параметра вы сможете отключить или включить передачу какого-либо параметра. Кликнув на название параметра, раскроется его описание со списком возможных значений, информацией по типу обращений, для которых доступен параметр, и информацией об ограничениях по отправке параметра. Название параметра соответствует его макросу, однако вы можете изменить название параметра по своему усмотрению, кликнув в поле названия параметра и переименовав его.

Описание параметров:

Выбранные параметры webhook'ов для вашего удобства будут отображены в поле "Итоговый HTTP-запрос" - итоговый запрос, который будет передан в вашу систему:

После того, как все настройки выполнены - для активации webhook'ов необходимо сохранить настройки и вернувшись на страницу с их списком, активировать необходимый webhook с помощью соответствующего переключателя:

В случае, если приложение-обработчик в dашей системе не отвечает либо отвечает с ошибками, будет выведено уведомление, в котором будет предложено активировать вебхук, несмотря на то, что обработчик отвечает не 200 OK:

Для перенастройки существующего webhook'а достаточно навести на него курсором и кликнуть в появившемся меню на соответствующую кнопку "Редактировать". Для удобства вы можете так же создать копию существующего webhook'а со всеми его настройками. Созданная копия будет по умолчанию не активна:

В случае, если вашим обработчиком не были получены данные (ответ сервера не 200 OK), либо обработчик работал некорректно (ответ сервера 200 OK, но данные использовались неверно), то вы можете вручную запустить процесс синхронизации данных, в результате чего будут переотправлены вебхуки по звонкам и заявкам за указанный период. Переотправка подразумевает повторную попытку отправки – это значит, что текущие настройки вебхука игнорируются. Переотправка осуществляется только по тем звонкам и заявкам, по которым была хотя бы одна попытка отправки. Выполнить переотправку за период, в котором вебхука не существовало или вебхук был выключен, невозможно. Максимально возможный выбранный период - 31 день. 

По окончании пересбора вы увидите новое оповещение, которое будет содержать статус отправок: