Содержание
Отображение заявок в статистике
Чтобы эффективно анализировать статистику, необходимо отслеживать как можно больше обращений клиентов. А клиенты могут обращаться в Вашу компанию не только посредством звонков, но и оставляя заявки на Вашем сайте. Заявки в Calltouch так же являются составляющей лида. Напомним, что лид в Calltouch это звонок + обратный звонок + заявка. Созданные заявки будут доступны в качестве метрик любого отчета Calltouch, как на графиках:
Так и в таблицах в виде отдельных столбцов:
А так же в отдельном отчете Журнал заявок:
API-метод для создания заявок
Запрос
Поддерживаемые методы отправки: GET и POST.
API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
API-токен для создания заявок не требуется.
Параметры запроса:
| Параметр | Описание |
| subject |
Произвольное название формы на Вашем сайте, с которой отправляется заявка в Calltouch. В последствие переданное название формы отображается в одноименном столбце журнала заявок:
|
| requestNumber |
Уникальный идентификатор заявки на Вашем сайте. В качестве идентификатора может быть передано строковое значение до 256 символов. Переданный идентификатор отображается в столбце "Номер заявки" журнала заявок над названием формы:
Параметр является необязательным, если его не передавать, то вместо него в журнале заявок будет отображаться уникальный идентификатор заявки в Calltouch. |
| requestDate |
Дата и время отправки заявки в формате: dd.mm.yyyy%20hh:mm:ss. Дата и время заявки отображается в одноименном столбце "Журнала заявок":
Параметр является необязательным, если его не передавать, то заявке будет автоматически присвоена текущая дата и время отправки API-запроса на создание заявки. |
| sessionId |
Идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее. Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Получить идентификатор сессии можно обратившись к глобальной JS-переменной window.call_value, пример из консоли Google Chrome:
Обратите внимание, что в примере выше обращение идет не к переменной window.call_value, а к переменной window.call_value_1. Нестандартные названия переменной (_N в конце имени) возможны, когда Ваш один и тот же сайт отслеживается, например, одновременно в несколько личных кабинетах Calltouch. Если в Вашем случае будет использовать как раз такой нестандартный скрипт Calltouch, обратитесь к Вашему аккаунт-менеджеру Calltouch или на почту [email protected], чтобы узнать так называемый Specific ID - именно он отображается в качестве _N в конце имени переменной window.call_value.
Если в API-запросе на создание заявки передать в параметре sessionId значение undefined, то API-запрос завершиться с ошибкой и заявка не будет создана. В подобных случаях, когда не удается определить источник перехода посетителя на сайт, не передавайте вовсе параметр sessionId при отправке API-запроса на создание заявки. Определившийся источник заявки (с помощью переданного значения сессии) будет отображен в журнале заявок:
Параметр sessionId является необязательным, но если его не передавать, источник заявки не удасться определить как показано на скриншоте выше. |
| fio |
Произвольное имя пользователя, отправившего заявку. Переданное значение отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете имя клиента, то обязательно должны передать хотя бы номер телефона или почту клиента, для его последующей идентификации в журнале заявок. |
| phoneNumber |
Номер телефона. Перед отправкой номера телефона из формы, необходимо проверить валидность введенного пользователем номера и привести его к формату: 7XXXXXXXXXX. Переданный номер телефона отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок.
|
|
Почта клиента. Переданная почта отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок.
|
Пример GET-запроса на создание заявки
GET-запрос:
Создаст в ЛК Calltouch сайта с идентификатором 18990 следующую заявку:
Формат тела запроса при использовании метода POST
При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":
При использовании метода POST, одним API-запросом можно создать только одну заявку.
Ответ
После успешной отправки API-запроса на создание заявки, возвращается следующий JSON-ответ:
{
"date": 1522047600000,
"requestNumber": "zi0D8c0c",
"requestType": "CLIENT_ORDER",
"dateStr": "26/03/2018 10:00:00",
"session": {
"keywords": "",
"city": "vladimir",
"ip": "95.66.182.68",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
"source": "yandex",
"medium": "cpc",
"ref": "",
"url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110,\"r7k12_si\":1156810694}",
"utmSource": "yandex",
"utmMedium": "cpc",
"utmTerm": "",
"utmContent": "",
"utmCampaign": "",
"guaClientId": "",
"sessionId": 1845461367,
"additionalTags": [],
"attribution": 1
},
"requestId": 5222102,
"subject": "Моя форма",
"client": {
"fio": "Вася",
"clientId": 37633316,
"phones": [
{
"phoneNumber": "79205550055",
"phoneType": "OTHER"
}
],
"contacts": [
{
"contactType": "EMAIL",
"contactValue": "[email protected]"
}
]
},
"order": null,
"status": "NOT_SET"
}JSON-объекты:
| Объект | Описание |
| date | Дата и время создания заявки в формате Unix Timestamp в миллисекундах. |
| requestNumber | Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте requestId далее). |
| dateStr | Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. |
| session |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
API-метод для выгрузки заявок
Посмотреть создавшиеся заявки можно не только в интерфейсе Calltouch, но и получить их выгрузку в формате JSON через API.
Запрос
Поддерживаемый метод отправки: GET.
API-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Обязательный параметр. В отличие от API-запроса на создание сделки, в API-запросе на их выгрузку требуется указывать токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
| dateFrom | Обязательный параметр. Начальная дата создания заявок, с которой они будут выгружены. Формат mm/dd/yyyy. |
| dateTo | Обязательный параметр. Конечная дата создания заявок, до которой они будут выгружены. Формат mm/dd/yyyy. |
| subject | Необязательный параметр. В качестве его значения можно указать название формы, для выгрузки только тех заявок, которые были сделаны с этой формы. Поиск среди заявок происходит по названию формы, которое "начинается с" указанного значения в параметре subject. |
| keywords | Необязательный параметр. В качестве его значения можно указать ключевой запрос, по которому пользователь совершил переход на отслеживаемый сайт и оставил заявку - в этом случае Поиск среди заявок происходит по ключевому запросу, который "содержит" указанное значение в параметре keywords. |
| city | Необязательный параметр. В качестве его значения можно указать название города, для выгрузки только тех заявок, которые были сделаны пользователем из этого города. Поиск среди заявок происходит по названию города, которое "полностью совпадает" с указанным значением в параметре city. Название городов указываются в формате базы данных Sypex Geo. |
| source | Необязательный параметр. В качестве его значения можно указать название источника, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого источника. Поиск среди заявок происходит по названию источника, которое "полностью совпадает" с указанным значением в параметре source. Название городов указываются в формате базы данных Sypex Geo. |
| medium | Необязательный параметр. В качестве его значения можно указать название канала, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого канала. Поиск среди заявок происходит по названию канала, которое "полностью совпадает" с указанным значением в параметре medium. |
| bindTo |
Необязательный параметр. Флаг выгрузки заявок с привязкой к разным метрикам. Возможные значения:
|
Для выгрузки данных только по одной определенной заявки, используйте API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {requestId} - ID заявки внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в JSON-ответе на API-запрос создания заявки.
В качестве параметров, в нем необходимо указать только токен clientApiId (см. таблицу выше).
Примеры GET-запросов на выгрузку заявок
- Выгрузка нескольких заявок
Запрос далее выгрузит заявки, созданные за период с 1 по 27 марта 2018 года:
- Выгрузка одной заявки
Запрос далее выгрузит заявку с идентификатором 79825254:
Ответ
После успешной отправки API-запроса на выгрузку заявок, возвращается следующий JSON-ответ:
[
{
"date": 1522134000000,
"requestNumber": "5228513",
"requestType": "CLIENT_ORDER",
"dateStr": "27/03/2018 10:00:00",
"session": {
"keywords": "<не заполнено>",
"city": "vladimir",
"ip": "95.66.182.68/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
"source": "yandex",
"medium": "cpc",
"ref": "",
"url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110}",
"utmSource": "yandex",
"utmMedium": "cpc",
"utmTerm": "<не заполнено>",
"utmContent": "<не заполнено>",
"utmCampaign": "<не заполнено>",
"guaClientId": null,
"sessionId": 1845461367,
"additionalTags": [],
"attribution": 1
},
"requestId": 5228513,
"subject": "Моя форма",
"client": {
"fio": "Вася",
"clientId": 37662915,
"phones": [
{
"phoneNumber": "79205550054",
"phoneType": "OTHER"
}
],
"contacts": [
{
"contactType": "EMAIL",
"contactValue": "[email protected]"
}
]
},
"order": {
"orderId": 7811220,
"callId": null,
"dateCreated": 1522047600000,
"status": "PENDING",
"realSum": null,
"offered": null,
"sent": "26.03.2018",
"sum": "1000.0000",
"isMarked": null,
"commentsCount": 0,
"currentAmount": 1000,
"orderNumber": "xX8H9M65412313",
"orderSum": "1000.0000",
"orderStatus": "PENDING",
"orderComments": "",
"session": {
"keywords": "<не заполнено>",
"city": "vladimir",
"ip": "95.66.182.68/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
"source": "yandex",
"medium": "cpc",
"ref": "",
"url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110}",
"utmSource": "yandex",
"utmMedium": "cpc",
"utmTerm": "<не заполнено>",
"utmContent": "<не заполнено>",
"utmCampaign": "<не заполнено>",
"guaClientId": null,
"sessionId": 1845461367,
"additionalTags": [],
"attribution": 1
}
},
"status": "NOT_SET"
},
...
{
...
}
]JSON-объекты:
| Объект | Описание |
| date | Дата и время создания заявки в формате Unix Timestamp в миллисекундах. |
| requestNumber | Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. далее). |
| dateStr | Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. |
| session |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
| order |
Объект будет содержать вложенные объекты с описанием сделки, если таковая была создана по заявке (см. статью Управление сделками через API). Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
Подключение к отслеживанию заявок с форм сайта
Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны далее.
Реализация на клиентской стороне
Данный способ можно использовать, например, когда на сайте средствами JavaScript уже организован обработчик отправки некоторой формы. При ее отправке в рамках данного обработчика выполняется проверка введенных на форме данных. Если валидация формы пройдена успешно, данный обработчик отправляет введенную информацию из формы в обработчик на сервере, где уже происходит обработка полученных данных, например, отправка данной заявки на email менеджера Вашей компании для ее дальнейшей обработки.
В данном случае оптимальным вариантом будет добавление дополнительного скрипта Calltouch в текущий обработчик формы. Обратите внимание, что скрипт отправки заявки в Calltouch необходимо выполнять только при успешном прохождении валидации формы. Ниже представлен пример скрипта для отправки API-запроса на создание заявки средствами JavaScript, используя функцию AJAX библиотеки jQuery:
var ct_node_id = 'X';
var ct_site_id = '{site_id}';
var ct_data = {
fio: 'Иванов Иван Иванович',
phoneNumber: '79000000000',
email: '[email protected]',
subject: 'Заявка с сайта',
sessionId: window.call_value
};
jQuery.ajax({
url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',
dataType: 'json',
type: 'POST',
data: ct_data
});Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
- ct_data - массив передаваемых входных параметров API-запроса на создание заявки.
Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы. При написании реального скрипта на сайте для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.
По умолчанию AJAX-запрос выполняется асинхронно. Если при отправке формы на сайте происходит редирект или обновление страницы, мы рекомендуем использовать синхронный AJAX-запрос, чтобы избежать случаев, когда редирект при отправке формы выполнится быстрее, чем API-запрос на создание заявки в Calltouch. Для этого в AJAX-функцию необходимо добавить параметр async: false.
В случае, если форма на сайте имеет простой функционал и минимальный набор полей, можно организовать скрипт отправки заявок из формы в Calltouch с помощью отдельного внешнего обработчика. Приведем пример скрипта, реализованном с использованием функций библиотеки jQuery, в котором по событию submit некоторой формы будет производится сбор введенных в форме данных и отправка заявки в Calltouch:
<script type="text/javascript">
/* Вешаем обработчик по событию submit формы с идентификатором myform */
jQuery(document).on('submit', 'form#myform', function() {
/* Записываем в переменную form объект с формой, на которой сработало событие submit */
var form = jQuery(this);
/* Ищем на форме input для ввода номера телефона и получаем его значение, в примере поиск производится по наличию у input атрибута name со значением phone */
var phone = form.find('input[name="phone"]').val();
/* Аналогично собираем другие введенные в поля формы данные, например, ФИО и email */
var fio = form.find('input[name="name"]').val();
var mail = form.find('input[name="email"]').val();
/* Указываем название формы */
var sub = 'Заявка на звонок';
/* Указываем ID сайта внутри Calltouch и адрес API-сервера */
var ct_node_id = 'X';
var ct_site_id = '{site_id}';
/* Формируем массив входных параметров запроса */
var ct_data = {
fio: fio,
phoneNumber: phone,
email: mail,
subject: sub,
sessionId: window.call_value
};
/* При необходимости делаем проверку на корректность собранных с формы данных */
/* Например, обязательным для заполнения на форме является поле с телефоном, проверяем его наличие и не пустое ли оно */
if (typeof(phone)!='undefined' && phone!=''){
/* Выполняем AJAX-запрос */
jQuery.ajax({
url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',
dataType: 'json',
type: 'POST',
data: ct_data,
async: false /* Предположим, после отправки формы на сайте настроен редирект на другую страницу, поэтому используем параметр async: false для синхронной отправки запроса */
});
}
});
</script>Скрипт выше является примером и требует адаптации под конкретные формы Вашего сайта. Его использование и внесение в него изменений требует наличие на сайте библиотеки jQuery и навыков ее использования.
Реализация на серверной стороне
В случае, если основной функционал обработки, валидации и отправки формы организован на стороне сервера, то можно встроить функционал отправки заявок в Calltouch скриптом на сервере. Приведем пример реализации скрипта на PHP с использованием CURL:
$call_value = $_POST['call_value']; /* ID сессии Calltouch, полученный из JS-переменной, и отправленный в обработчик на сервере */
$ct_node_id = 'X';
$ct_site_id = '{site_id}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: application/x-www-form-urlencoded;charset=utf-8"));
curl_setopt($ch, CURLOPT_URL,'https://api-node'.$ct_node_id.'.calltouch.ru/calls-service/RestAPI/requests/'.$ct_site_id.'/register/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
"fio=".urlencode($_POST['name'])
."&phoneNumber=".$_POST['phone']
."&email=".$_POST['email']
."&subject=".urlencode('Заявка с сайта')
."".($call_value != 'undefined' ? "&sessionId=".$call_value : ""));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$calltouch = curl_exec ($ch);
curl_close ($ch);Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
При использование такого метода, следует обратить внимание на 3 пункта:
- ID сессии Calltouch, который необходимо отправить в качестве параметра sessionId API-запроса на создание заявки, необходимо передавать в PHP-обработчик с клиентской стороны, получая значение ID сессии из соответствующей переменной (по умолчанию window.call_value).
- Для корректной передачи кириллических символов в запросе и обхода проблем с кодировкой, необходимо применять PHP-функцию urlencode ко всем PHP-переменным, передаваемым в качестве входных параметров API-запроса. Т.е., если ФИО клиента находится в $_POST['name'], то в API-запрос ее надо добавить как urlencode($_POST['name']).
- В API-запросе в явном виде должна быть указана кодировка utf-8.
Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы соответственно: $_POST['name'], $_POST['phone'], $_POST['email'] и значение "Заявка с сайта". При написании реального скрипта на сервере для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.
0 Комментарии