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

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

Содержание

 

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

Раздел "Интеграции => Webhooks" личного кабинета Calltouch позволяет настроить вызовы Ваших сторонних приложений посредством отправки уведомлений о звонках, зафиксированных в сервисе Calltouch, на Ваш сервер в виде GET или POST запросов.

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

webhooks.png

 

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

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

 

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

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

 

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

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

  • 95.163.114.93
  • 95.163.114.87
  • 95.163.114.147
  • 95.163.114.80
  • 95.163.114.130

 

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

 

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

Для добавления нового WebHook'а, вначале необходимо заполнить HTTP(S) адрес обработчика WebHook'ов на Вашем сервере, который будет вызываться с нашей стороны автоматически каждый раз по факту начала и/или завершения звонка на отслеживаемый номер Calltouch. При необходимости можно добавить или удалить дополнительные WebHook'и с помощью кнопок button1.png или button2.png.

На первом скриншоте выше это HTTPS адреса приложений обработчиков WebHook'ов:

https://myserver1/
https://myserver2/

Обратите внимание! Если в качестве серверов myserver1 и myserver2 Вы указываете какие-либо домены, то они не обязательно должны быть подключены к нашему сервису для отслеживания звонков с них - главное чтобы на них присутствовало какое-либо приложение для регистрации 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.png

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

 

Настройка выходных параметров WebHook'а

Далее необходимо указать выходные параметры WebHook'а, которые будут отправлены нами в Вашу систему на указанный обработчик в предыдущем пункте. Для этого необходимо кликнуть на "Параметры-макросы" напротив каждого WebHook'а и в открывшемся списке отметить галочками параметры звонка, которые будут передаваться в WebHook'е. По умолчанию название параметра соответствует его макросу, однако Вы можете изменить название параметра по своему усмотрению, кликнув в поле имени макроса и переименовать его.

webhooks_macros.png

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

Параметр Макрос Описание (возможные значения)
callphase {callphase}

В зависимости от того, в какой момент был отправлен WebHook, параметр может принимать значения:

  • callconnected - в момент начала звонка
  • calldisconnected - в момент завершения звонка
callerphone {callerphone} Телефонный номер звонящего абонента.
phonenumber {phonenumber} Номер Calltouch, на который звонит абонент.
duration {duration} Длительность телефонного разговора.
tags_auto_pr {tags_auto_pr} Теги, проставленные автоматически системой Calltouch Predict.
tags_auto_af {tags_auto_af} Теги, проставленные автоматически системой Calltouch Антифрод.
tags_auto_ct {tags_auto_ct} Теги, проставленные автоматически на основе введенных тоновых сигналов клиентом или оператором в ходе разговора.
tags_auto_pn {tags_auto_pn} Теги, проставленные автоматически в зависимости от номеров, на которые или с которых звонят клиенты.
tags_manual {tags_manual} Теги, проставленные вручную пользователем в журнале звонков личного кабинета Calltouch.
city {city} Город, с которого был осуществлен звонок.
browser {browser} Наименование и версия браузера, в котором был осуществлен переход.
id {id} Уникальный идентификатор звонка.
waiting_time {waiting_time} Длительность ожидания (гудки).
os {os} Наименование и версия операционной системы.
device {device} Информация об устройстве, с которого клиент перешел на сайт.
status {status} Статус звонка.
unique {unique} Уникальный звонок или нет (true / false).
targetcall {targetcall} Целевой звонок или нет (target / non-target).
uniqtargetcall {uniqtargetcall} Уникально-целевой звонок или нет (uniqtarget / non-uniqtarget).
callback {callback} Обратный звонок или нет (callback / non-callback).
gcid {gcid} Идентификатор посетителя в Universal Analytics - google client id.
worktime {worktime} Время, в которое пришел звонок, рабочее или нерабочее (worktime / non-worktime).
callReferenceNumber {callReferenceNumber}

Уникальный идентификатор звонка с АТС. Может быть полезен при интеграции с Вашей АТС.

rating {rating}

Данные из блока "Рейтинг" нового журнала звонков.

pool {pool}

Звонок на номер либо из динамического пула (dynamic), либо на статический оффлайн номер (staticOffline), либо на статический онлайн номер (staticOnline).

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

orderId {orderId}

Идентификатор сделки по звонку, если таковая была создана.

comment {comment}

Комментарии к звонку, оставленные через плеер журнала звонков. Передаются массивом по шаблону:

comment[0][party]=ЛогинПользователя1&comment[0][comment]=КомментарийПользователя1
comment[1][party]=ЛогинПользователя2&comment[1][comment]=КомментарийПользователя2
ip {ip}

IP-адрес клиента, совершившего звонок.

url {url}

URL по которому попали на сайт (куда перешел посетитель).

ref {ref} URL источника пользовательского перехода (откуда пришёл посетитель). Присутствует только если был выполнен реферальный переход с какой-либо рекламной площадки.
hostname {hostname} Домен или поддомен ресурса, на который был осуществлен переход (например: ok.ru, vk.com, google.com).
add_url_params {add_url_params}

Дополнительные параметры отслеживания платного трафика. Если таковые заранее настроены в системных настройках личного кабинета Calltouch и имеются в URL, по которому перешел посетитель сайта, совершивший звонок, то они будут передаваться массивом по шаблону:

add_url_params[0][name]=Параметр1&add_url_params[0][value]=ЗначениеПараметра1
add_url_params[1][name]=Параметр2&add_url_params[1][value]=ЗначениеПараметра2
utm_source {utm_source} Значение utm-метки utm_source.
utm_medium {utm_medium} Значение utm-метки utm_medium.
utm_campaign {utm_campaign} Значение utm-метки utm_campaign.
utm_content {utm_content} Значение utm-метки utm_content.
utm_term {utm_term} Значение utm-метки utm_term.
source {source} Источник перехода.
medium {medium} Тип источника перехода.
calltime {calltime} Дата и время звонка в формате 2016-07-30 01:02:03.
timestamp {timestamp} Дата и время звонка в формате unix timestamp.
reclink {reclink} API-запрос для скачивания записи звонка. Подробное описание запроса находится в инструкции по API.
sessionId {sessionId} Идентификатор сессии Calltouch.
attribution {attribution}  Выбранная модель атрибуции WebHook'ов. Подробное описание далее.
ctCallerId {ctCallerId} Уникальный идентификатор клиента в Calltouch. Определяется по номеру телефона клиента. Его удобно использовать, когда нужно идентифицировать клиента без использования его персональных данных (номер телефона).

 

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

https://myserver1/?callerphone={callerphone}&callerphone={callerphone}&phonenumber={phonenumber}&duration={duration}&tags_auto_pr={tags_auto_pr}&tags_auto_af={tags_auto_af}&tags_auto_ct={tags_auto_ct}&tags_auto_pn={tags_auto_pn}&tags_manual={tags_manual}&city={city}&browser={browser}&id={id}&waiting_time={waiting_time}&os={os}&device={device}&status={status}&unique={unique}&targetcall={targetcall}&uniqtargetcall={uniqtargetcall}&callback={callback}&worktime={worktime}&callClientUniqueId={callClientUniqueId}&rating={rating}&pool={pool}&orderId={orderId}&comment={comment}&clientCrmId={clientCrmId}&ip={ip}&gcid={gcid}&url={url}&ref={ref}&hostname={hostname}&add_url_params={add_url_params}&utm_source={utm_source}&utm_medium={utm_medium}&utm_campaign={utm_campaign}&utm_content={utm_content}&utm_term={utm_term}&source={source}&medium={medium}&calltime={calltime}&timestamp={timestamp}&reclink={reclink}&sessionId={sessionId}&attribution={attribution}

Обратите внимание! При выборе метода POST, параметры будут отправлены в теле HTTP запроса, а не в самом URL, как будет указано в поле "Результат".

 

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

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

webhooks_method.png

 

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

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

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

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

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

 

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

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

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

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

webhooks_attribution.png

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

 

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

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

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

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

 

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

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

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

Рассмотрим все варианты более детально.

 

Отправка в момент начала звонка

Для отправки WebHook'а с информацией о поступившем звонке в момент его начала включите в настройках одноименную опцию:

webhook_callconnected.png

После этого в момент начала звонка на указанный Вами сервер(а) поступит WebHook со следующей информацией о звонке:

Параметр Макрос Описание (возможные значения)
callphase {callphase}

В зависимости от того, в какой момент был отправлен WebHook, параметр может принимать значения:

  • callconnected - в момент начала звонка
  • calldisconnected - в момент завершения звонка

Т.к. данный вебхук пришел в момент начала звонка, параметр примет значение: callphase=callconnected.

callerphone {callerphone} Телефонный номер звонящего абонента.
phonenumber {phonenumber} Номер Calltouch, на который звонит абонент.
id {id} Уникальный идентификатор звонка.
callback {callback} Обратный звонок или нет (callback / non-callback).
calltime {calltime} Дата и время звонка в формате 2016-07-30 01:02:03.
timestamp {timestamp} Дата и время звонка в формате unix timestamp.

Все остальные параметры звонка могут быть отправлены уже в WebHook'е по завершению звонка.

Обратите внимание! Данный WebHook поступит на указанный Вами сервер(а) еще до начала разговора - в момент когда у оператора будет звонить телефон, а клиент будет ждать ответа, слушая гудки. Таким образом информация в Вашу систему поступит еще до того, как оператор ответит клиенту! В ближайшее время в данном WebHook'е будет реализована возможность передачи сразу источника звонка, включая ключевой запрос, чтобы оператор представлял о чем будет идти разговор с клиентом еще до его начала!

 

Отправка в момент завершения звонка

Для отправки WebHook'а с информацией о завершившемся звонке в момент его завершения включите в настройках одноименную опцию:

webhook_calldisconnected.png

После этого в момент завершения звонка на указанный Вами сервер(а) поступит WebHook со всеми параметрами звонка, перечисленными в таблице выходных параметров WebHook'ов, содержащими полную информацию о звонке.

Обратите внимание! В WebHook'е по завершению звонка параметр callphase примет значение calldisconnected. Таким образом, Вы сможете различить WebHook'и одного и того же звонка в разные моменты времени - в момент начала звонка параметр callphase будет равен callconnected, а в момент завершения calldisconnected.

 

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

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

webhooks_both.png

 

 

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

Идентифицировать два WebHook'а одного и того же звонка можно по двум параметрам:

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

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

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

 

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

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

После активирования WebHook'ов для проверки соединения со стороны Calltouch в Вашу систему будет автоматически отправлен тестовый WebHook, где вместо реальных значений параметров, будут указаны значения calltouch_test_N, где N – порядковый номер переменной в запросе.

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

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

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

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