Наверх
Подписаться

Отправка звонков из Calltouch в любую систему с помощью webhook'ов

Содержание

 

 

Описание технологии

C помощью данной технологии Вы получаете возможность широкой настройки работы с собственными системами - для этого Вам необходимо лишь указать ссылку или несколько ссылок с адресом обработчика webhook'ов на Вашем сервере, который будет вызываться с нашей стороны автоматически каждый раз по факту получения и/или завершения звонка на отслеживаемый номер Calltouch. Добавить и настроить webhook'и можно в меню "Настройка", раздел "Передача данных через API, webhooks":

Screenshot_at_Jun_13_00-11-30.png 

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

Webhook'и передаются в Вашу систему из Calltouch в момент начала звонка или в момент завершения - в зависимости от выбранных настроек.

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

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

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

В целях безопасности Вы можете добавить IP-адреса наших API/webhook серверов, с которых будут отправляться webhook'и, в список исключения брандмауэра Вашего сервера:

  • 95.163.114.64/27
  • 95.163.114.128/27

 

 

Добавление нового webhook'а

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

Screenshot_at_Jun_13_00-19-21.png

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

Screen_Shot_2018-06-13_at_00.20.41.png

  

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

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

Домен в указываемом адресе обработчика не обязательно должен быть подключен к нашему сервису для отслеживания звонков с него - главное чтобы на нем присутствовало какое-либо приложение для регистрации 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'и следующего содержания:

webhooks_test_new.jpg

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

 

Выбор метода GET или POST для отправки webhook'ов

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

Screenshot_at_Jun_13_09-34-23.png

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

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

Принцип отправки Метод GET передает данные серверу используя URL, в то время как POST передает данные, используя тело HTTP запроса.
Размер запроса

Длина GET-запроса может быть ограничена обработчиками на стороне клиента, а длина POST-запроса не ограничена, либо ограничение несоизмеримо больше, чем сам запрос.

Безопасность

Передача данных методом POST более безопасна, чем методом GET, так как секретные данные (например, API-токен ссылки на скачивание записи звонка в параметре reclink webhook'а) не отображаются напрямую в URL GET-запроса.

Это наглядно демонстрируется в поле итогового HTTP-запроса, который и будет улетать от нас на Ваш сервер:

Screenshot_at_Jun_13_10-04-12.png

 

Выбор модели атрибуции webhook'а

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

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

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

Screenshot_at_Jun_13_09-40-15.png

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

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

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

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

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

 

Выбор в какой момент отправлять webhook

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

Screenshot_at_Jun_13_09-50-17.png

Возможные варианты отправки webhook'а:

  • Отправка по одному звонку одновременно двух webhook'ов в момент начала звонка и в момент завершения
  • Отправка webhook'а в момент начала звонка
  • Отправка webhook'а в момент завершения звонка

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

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

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

По его идентификатору id Уникальный параметр id, который присутствует в обоих webhook'ах (в момент начала звонка и в момент завершения) и значение которого одинаково в разных webhook'ах одного и того же звонка.
По параметру callphase

Присутствует в обоих webhook'ах и показывать в какой именно момент звонка поступает webhook на указанный Вами сервер. Параметр будет принимать следующие значения:

  • callphase=callconnected, если webhook отправлен в момент начала звонка
  • callphase=calldisconnected, если webhook отправлен в момент завершения звонка

advice_ver2.png В какой момент звонка передаются различные параметры звонка описано далее в настройках передаваемой информации.

 

Настройка передаваемой информации в webhook'ах

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

Screen_Shot_2018-06-13_at_10.06.05.png

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

Рассмотрим каждый параметр более детально.

Название

Параметр

Описание

В какой момент звонка передается
Фаза звонка

callphase

Показывает в какой момент звонка по нему был отправлен webhook'.
Возможные значения:
callconnected — в момента начала звонка
calldisconnected — в момент заверешения звонка

В момент начала и завершения звонка
ID звонка

id

Уникальный идентификатор звонка в Calltouch.

В момент начала и завершения звонка
ID клиента

ctCallerId

Уникальный идентификатор клиента в Calltouch.
Определяется по номеру телефона клиента. Его удобно использовать, когда нужно идентифицировать клиента без использования его персональных данных (номер телефона).

В момент начала и завершения звонка
Номер клиента

callerphone

Телефонный номер клиента, с которого он выполняет звонок.

Формат: 7XXXXXXXXXX

В момент начала и завершения звонка
Отслеживаемый номер

phonenumber

Отслеживаемый номер, на который звонит клиент.

Формат: 7XXXXXXXXXX

В момент начала и завершения звонка
Номер переадресации redirectNumber Номер переадресации, на который переадресовался звонок клиента.
Если номер не удалось определить, а так же во всех webhook'ах по началу звонка, передается значаение undefined.
В момент завершения звонка
Длительность разговора

duration

Длительность телефонного разговора в секундах.

В момент завершения звонка
Длительность ожидания

waiting_time

Длительность ожидания (гудки до поднятия трубки оператором) в секундах.

В момент завершения звонка
Дата и время звонка в формате YYYY-MM-DD hh:mm:ss

calltime

Дата и время звонка начала звонка.

В момент начала и завершения звонка
Дата и время звонка в формате Unix Time Stamp

timestamp

Дата и время начала звонка в формате Unix Time Stamp в секундах.

В момент начала и завершения звонка
Статус звонка

status

Статус звонка. Возможные значения:
successful - удачный звонок
unsuccessful - неудачный звонок

В момент завершения звонка
Уникальный звонок или нет

unique

Уникальный звонок - это первый звонок клиент со своего номера.
Если тот же клиент перезвонит с того же номера - звонок будет повторным. Если тот же клиент перезвонит с другого номера - звонок будет вновь уникальным.
Возможные значения:
true - уникальный звонок
false - повторный звонок

В момент начала и завершения звонка
Целевой звонокили нет

targetcall

Целевой звонок - это звонок, длительность которого уложилась в рамки целевого звонка, заданных в системных настройках ЛК, по умолчанию от 30 сек.
Возможные значения:
target - целевой звонок
non-target - нецелевой звонок

В момент завершения звонка
Уникально-целевой звонокили нет

uniqtargetcall

Уникально-целевой звонок - это первый звонок от клиента, укладывающийся в рамки целевого звонка. Возможные значения:
uniqtarget - уникально-целевой звонок
non-uniqtarget - не уникально-целевой звонок

В момент завершения звонка
Обратный звонок или нет

callback

Обратный звонок - это звонок либо с виджета обратного звонка Calltouch, либо с кастомной формы или кнопки сайта, подключенной к обратному звонку Calltouch.
Возможные значения:
callback - обратный звонок
non-callback - прямой звонок на отслеживаемый номер

В момент начала и завершения звонка
В рабочее или нерабочее время поступил звонок

worktime

Рабочее или нерабочее время, в которое пришел звонок, устанавливается в настройках прежней версии ЛК. Возможные значения:
worktime - рабочее время
non-worktime - нерабочее время

В момент начала и завершения звонка
Звонок на статический или динамический номер

pool

Показывает за каким типом пула закреплен номер, на который позвонил клиент.
Возможные значения:
dynamic - звонок на номер из динамического пула
staticOffline - звонок на статический оффлайн номер
staticOnline - звонок на статический онлайн номер

В момент начала и завершения звонка
Рейтинг звонка

rating

Рейтинг, присвоенный звонку в журнале звонков ЛК.
Возможные значения:
0 - рейтинг не присвоен звонку
1/2/3/4/5 - звонку присвоен рейтинг от 1 до 5 соответственно

В момент завершения звонка
Комментарии ко звонку

comment

Комментарии ко звонку, оставленные через плеер журнала звонков во время разговора.
Передаются массивом по шаблону:
comment[0][party]=user1&
comment[0][comment]=comment_by_user1&
comment[1][party]=user2&
comment[1][comment]=comment_by_user2&
Если звонку не присвоен комментарий, параметр comment не передается вовсе.

В момент завершения звонка
Теги Calltouch Predict

tags_auto_pr

Теги, присвоенные звонку автоматически системой Calltouch Predict.
Если такие теги не были присвоены звонку, передается значение null.

В момент завершения звонка
Теги Calltouch Антифрод

tags_auto_af

Теги, присвоенные звонку автоматически системой Calltouch Антифрод.
Если такие теги не были присвоены звонку, передается значение null.

В момент завершения звонка
Теги по добавочным

tags_auto_ct

Теги, присвоенную звонку автоматически на основе введенных тоновых сигналов (добавочных) клиентом или оператором в ходе разговора.
Если такие теги не были присвоены звонку, передается значение null.

В момент завершения звонка
Теги по номерам

tags_auto_pn

Теги, присвоенную звонку автоматически в зависимости от номеров, на которые или с которых звонят клиенты.
Если такие теги не были присвоены звонку, передается значение null.

В момент начала и завершения звонка
Вручную проставленные теги

tags_manual

Теги, присвоенную звонку во время разговора вручную пользователем в журнале звонков Calltouch.
Если такие теги не были присвоены звонку, передается значение null.

В момент завершения звонка
Модель атрибуции

attribution

Выбранная модель атрибуции в настройках webhook'а, согласно которой будет передаваться источник звонка.
Возможные значение:
1 - выбрана модель атрибуции “Последний непрямой” (по умолчанию)
0 - выбрана модель атрибуции “Последнее взаимодействие”

В момент начала и завершения звонка
Источник

source

Источник трафика перехода на сайт.
Либо название источника в настройках статического пула, если номер закреплен за ним и переход на сайт не предусмотрен.

В момент начала и завершения звонка
Канал

medium

Канал трафика перехода на сайт.
Либо название канала в настройках статического пула, если номер закреплен за ним и переход на сайт не предусмотрен. Если значение отсутствует, передается значение <не указано>.

В момент начала и завершения звонка
Метка utm_source

utm_source

Значение utm-метки utm_source.
Если в URL перехода отсутствовали все utm-метки, то передается значение <не указано>. Если в URL перехода были utm-метки, но utm_source отсутствовала или была пуста, то передается значение <не заполнено>.

В момент начала и завершения звонка
Метка utm_medium

utm_medium

Значение utm-метки utm_medium.
Если в URL перехода отсутствовали все utm-метки, то передается значение <не указано>. Если в URL перехода были utm-метки, но utm_medium отсутствовала или была пуста, то передается значение <не заполнено>.

В момент начала и завершения звонка
Метка utm_campaign

utm_campaign

Значение utm-метки utm_campaign.
Если в URL перехода отсутствовали все utm-метки, то передается значение <не указано>. Если в URL перехода были utm-метки, но utm_campaign отсутствовала или была пуста, то передается значение <не заполнено>.

В момент начала и завершения звонка
Метка utm_content

utm_content

Значение utm-метки utm_content.
Если в URL перехода отсутствовали все utm-метки, то передается значение <не указано>. Если в URL перехода были utm-метки, но utm_content отсутствовала или была пуста, то передается значение <не заполнено>.

В момент начала и завершения звонка
Метка utm_term

utm_term

Значение utm-метки utm_term.
Если в URL перехода отсутствовали все utm-метки, то передается значение <не указано>. Если в URL перехода были utm-метки, но utm_term отсутствовала или была пуста, то передается значение <не заполнено>.

В момент начала и завершения звонка
Дополнительные отслеживаемые параметры

add_url_params

Дополнительный отслеживаемый произвольный параметр в URL, по которому перешли на сайт.
Дополнительные отслеживаемые параметры добавляются в настройках прежней версии ЛК. Например, если клиент перешел на сайт по URL:
https://site.ru?utm_source=yandex&utm_medium=cpc&abtest=a
где параметр abtest был ранее добавлен к отслеживанию в url, то webhook'ах будет передан массив:
add_url_params[0][name]=abtest&
add_url_params[0][value]=a&
Если дополнительных параметров не было в URL перехода, параметр add_url_params не передается вовсе.

В момент начала и завершения звонка
Google Client ID

gcid

Идентификатор Google Client ID. Присутствует при настроенной интеграции с Google Analytics. Если интеграция не настроена, или настроена, но Google Client ID не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
Yandex Client ID

yaClientId

Идентификатор Yandex Client ID. Присутствует при настроенной интеграции с Яндекс.Метрика на отправку звонков. Если интеграция не настроена, или настроена, но Yandex Client ID не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
ID сессии Calltouch

sessionId

Идентификатор сессии Calltouch.

В момент начала и завершения звонка
Отслеживаемый сайт

hostname

Отслеживаемый домен или поддомен ресурса, на который был осуществлен переход (например: ok.ru, vk.com, google.com).

В момент начала и завершения звонка
Страница входа на сайт

url

URL, по которому попали на сайт (куда перешел посетитель). Фиксируется только страница входа в пределах сессии. Если URL не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
Сторонние cookie attrs Название зафиксированной cookie и ее значение, например: "cookie1":"value1","cookie2":"value2". Сторонние cookie могут быть зафиксированы Calltouch по запросу в тех. поддержку. Данный функционал может быть полезен для сквозной аналитики между Calltouch и другими сервисами. В момент начала и завершения звонка
Страница звонка call_url URL, находясь на котором, посетитель совершил звонок. В момент начала и завершения звонка
Источник реферального перехода

ref

URL источника пользовательского перехода (откуда пришел посетитель). Присутствует только если был выполнен реферальный переход с какой-либо рекламной площадки, иначе передается пустое значение.

В момент начала и завершения звонка
Город

city

Город, в котором находится клиент, совершивший звонок. Определение города происходит по IP-адресу клиента, используется гео-база sypexgeo.net. Если город не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
Браузер

browser

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

В момент начала и завершения звонка
Операционная система

os

Наименование и версия операционной системы. Определяется по User Agent клиента. Если ОС не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
Устройство

device

Информация об устройстве, с которого клиент перешел на сайт. Определяется по User Agent клиента. Если устройство не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
IP-адрес

ip

IP-адрес клиента, совершившего звонок.
Если IP не удалось определить, параметр передается с пустым значением.

В момент начала и завершения звонка
ID сеанса SIP

sip_call_id

Уникальный идентификатор сеанса связи с АТС Calltouch. Его значение отправляется на ваше оборудование в случае использования переадресации по SIP trunk. Может быть полезен при интеграции с вашей АТС. В момент завершения звонка
ID звонка с АТС callReferenceNumber Технический идентификатор звонка внутри БД Calltouch. Может применяться для отладки каких-либо интеграций между Calltouch и внешними сервисами. В момент начала и завершения звонка
Запись разговора

reclink

Ссылка на запись звонка. Присутствует, если в настройках webhook'ов не запрещено скачивание записей разговоров. Содержит ссылку со специальным JWT-токеном, по которой можно будет скачать только ту запись звонка, по которому был отправлен этот webhook. Таким образом, при каждой отправке webhook’а будет генерироваться уникальный JWT-токен.

В момент завершения звонка
ИД сделки orderId Идентификатор сделки по звонку, если таковая была создана во время разговора из плеера журнала звонков ЛК либо по API Calltouch. В момент завершения звонка
ИД сайта siteId Уникальный идентификатор вашего сайта внутри Calltouch, на котором был зафиксирован звонок. В момент завершения звонка 
Название сайта siteName Название вашего сайта внутри Calltouch, на котором был зафиксирован звонок. В момент завершения звонка

 

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

Screenshot_at_Jun_13_10-04-12.png

 

 

Активирование webhook'а

После того, как Вы указали HTTP(S) адрес приложения для регистрации и обработки webhook'ов, выбрали метод отправки POST или GET, выбрали параметры для передачи в них информации по звонкам, указали необходимую модель атрибуции и выбрали в какой момент отправлять webhook'и - для активации webhook'ов необходимо сохранить настройки и вернувшись на страницу с их списком, активировать необходимый webhook с помощью соответствующего переключателя:

Screenshot_at_Jun_13_10-14-27.png

В случае, если приложение обработчик в Вашей системе не будет найдено, активировать webhook не удасться, а Вам будет отображено сообщение с соответствующей ошибкой:

Screenshot_at_Jun_13_10-18-15.png

 

 

Редактирование существующего webhook'а

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

Screenshot_at_Jun_13_10-16-59.png

Была ли эта статья полезной?
Пользователи, считающие этот материал полезным: 11 из 12
Еще есть вопросы? Отправить запрос

0 Комментарии

Войдите в службу, чтобы оставить комментарий.