JavaScript Callback API
Общая информация
API — это программный интерфейс для внешних программных продуктов. Рассматриваемый в данном разделе API интерфейс позволяет отправлять заявки на обратный звонок, информация о которых будет загружена в журнал звонков.
Данный метод удобен тем, что не требует дополнительных действий для настройки. Нет необходимости настраивать обработчик на сервере и передавать отдельно идентификатор сессии Calltouch. ID сессии передается автоматически.
Ниже представлены функции Javascript API для получения данных о настройках виджета и отправки заявок на обратный звонок в Calltouch.
Подключение
Для подключения необходимо:
- Пополнить баланс минут и активировать услугу обратного звонка
- Создать специальный тип виджета Автопрозвон заявок с сайта.
- Включить виджет
- Добавить скрипт отправки заявок в наш сервис с помощью Javascript API.
Далее представлены варианты передаваемых параметров для отправки заявок на обратный звонок.
Примеры обработки
Получение настроек виджета и отображение формы
window.ctw.getRouteKeyData('my_form_1', function(success, data){ console.log(success, data); if (success) { if (data.widgetFound) { if (data.widgetData.callCenterWorkingMode == 'working_hours') { console.log('колл-центр работает, отображение виджета'); } else { if (data.widgetData.collectNonWorkingRequests) { console.log('колл-центр не работает, но можем отобразить форму
нерабочего времени'); } else { console.log('колл-центр не работает, заявки в нерабочее время
не собираем'); } } } else { console.log('не найден включенный виджет по routeKey, либо услуга обратного
звонка не активна'); } } else { console.log('во время обработки произошла ошибка'); console.log(data) } });
Создание заявки для сайтов с одним скриптом Calltouch
window.ctw.createRequest( 'my_form_1', '7xxxxxxxxxx', [ {"name": "Name", "value": "Ivan"}, {"name": "Last name", "value": "Petrov"} ], function(success, data){ console.log(success, data) if (success) { console.log('Создана заявка на колбек, идентификатор: ' + data.callbackRequestId) } else { switch(data.type) { case "request_throttle_timeout": case "request_throttle_count": console.log('Достигнут лимит создания заявок, попробуйте позже'); break; case "request_phone_blacklisted": console.log('номер телефона находится в черном списке'); break; case "validation_error": console.log('были переданы некорректные данные'); break; default: console.log('Во время выполнения запроса произошла ошибка: ' + data.type); } } },
'2020-11-24 15:11:00',
[
'Тег_1',
'Тег_2'
],
12345 )
Блок с параметрами "name" и "value" имеет ограничение по количеству передаваемых полей — их может быть максимум 5, а в блоке "tags" максимум 10. Значения можно передавать как на латинице, так и на кириллице.
Значения этих полей вы можете использовать для передачи дополнительной информации ко звонку в Журнале звонков или для оповещения операторов с помощью Синтеза речи (подробнее о настройке Синтеза речи в нашей инструкции). Порядок передачи параметров в данном скрипте будет влиять на то, в каком виде они будут отображены в Журнале звонков и в каком порядке они будут проигрываться при активации Синтеза речи.
Создание заявки для сайтов с несколькими скриптами Calltouch
Этот функционал позволяет клиентам, не имеющим возможности использовать серверный Callback API, распределять заявки на обратный звонок из своих форм по разным кабинетам Calltouch, используя один домен.
Пример функции с передачей параметра:
window.ctw_qr245frf.createRequest(routeKey, phone, fields, requestCallback, scheduleTime, tags, unitId)
где qr245frf — mod_id нужного сайта Calltouch.
Функции
Получение данных виджета - window.ctw.getRouteKeyData
Описание функции получения данных виджета:
/** * Получение данных виджета * * Идентификатор формы (длина от 1 до 255) * @param {string} routeKey * * Функция обратного вызова для обработки результата запроса * @param {routeKeyDataRequestCallback} requestCallback */ function getRouteKeyData(routeKey, requestCallback) {},
Описание функции обратного вызова:
/** * Функция обратного вызова для обработки результата запроса получения данных виджета * * @callback routeKeyDataRequestCallback * * В случае успеха true иначе false * @param {bool} success * * Данные успешного ответа или ошибки * @param {RouteKeyDataSuccessResponse|ErrorResponse} responseData */
Данные в случае успешного выполнения запроса получения данных виджета:
/** * Данные успешного выполнения запроса получения данных виджета * * @typedef {Object} RouteKeyDataSuccessResponse * * Флаг указывает найден ли виджет * @property {bool} widgetFound * * Данные виджета, если widgetFound=false, то значение будет null иначе Object * @property {Object|null} widgetData * * Текущие режим работы колл-центра, возможные значения: * working_hours(рабочее время), non_working_hours(нерабочее время) * @property {string} widgetData.callCenterWorkingMode * * Флаг указывает собирать ли заявки в нерабочее время * @property {bool} widgetData.collectNonWorkingRequests
* @property {Object} widgetData.workingSchedule Рабочее время колл-центра
* @property {string} widgetData.workingSchedule.utcTimezone Временная зона колл-центра
* @property {array} widgetData.workingSchedule.hours Список рабочих часов по дням недели
* @property {integer} widgetData.workingSchedule.hours[].hour Час, от 0 до 23
* @property {integer} widgetData.workingSchedule.hours[].dayOfWeek День недели, от 1 до 7
*/
Примеры данных
1. В случае когда по идентификатору формы не найдено включенного виджета или услуга обратного звонка не включена:
{ "widgetFound":false "widgetData":null }
2. Виджет найден:
{ "widgetFound":true "widgetData": { "callCenterWorkingMode": "working_hours", "collectRequests": true, "workingSchedule": { "utcTimezone": "UTC+03:00", "hours": [ { "hour": 9, "dayOfWeek": 1 }, { "hour": 10, "dayOfWeek": 1 }, { "hour": 11, "dayOfWeek": 1 } // ... ] } } }
Формат данных в случае ошибки
/** * Данные в случае ошибки выполнения запроса * * @typedef {Object} ErrorResponse * * @property {string} type Тип ошибки * @property {string} message Текст ошибки * @property {Object} details Детали ошибки */
Возможные ошибки
Тип | Описание |
unknown_error | Различные ошибки на клиенте (таймаут ответа сервера, сброс соединения, некорректный json в ответе, ошибочный код ответа сервера) |
server_error | Ошибка сервера |
Создание заявки на обратный звонок - window.ctw.createRequest
Описание функции создание заявки на обратный звонок:
/** * Создание заявки на обратный звонок * * Идентификатор формы (длина от 1 до 255) * @param {string} routeKey * * Номер телефона с кодом страны и города, без плюса (11 символов) * @param {string} phone * * Дополнительные поля (не более 5 полей) или пустой массив, если нет дополнительных полей * @param {Object[]} fields[] * * Название поля (длина от 1 до 255) * @param {string} fields[].name * * Значение поля (длина от 1 до 255) * @param {string} fields[].value * * Функция обратного вызова для обработки результата запроса * @param {createRequestRequestCallback} requestCallback
*
* Время в формате Y-m-d H:i:s (например 2018-02-12 22:33:00), на которое
* нужно запланировать звонок, если null то звонок будет выполнен сразу
* @param {DateTime|null} scheduleTime
*
* Пользовательские теги (не более 10 тегов) или пустой массив, если нет пользовательских тегов
* @param {Object[]} tags[]
* Значение поля (длина от 1 до 100)
* @param {string} tag
*
* Идентификатор отдела
* @param {Integer} unitId
*/
function createRequest(routeKey, phone, fields, requestCallback, scheduleTime, tags, unitId) {}
Описание функции обратного вызова:
/** * Функция обратного вызова для обработки результата запроса создания заявки на обратный звонок * * @callback createRequestRequestCallback * * В случае успеха true иначе false * @param {bool} success * * Данные успешного ответа или ошибки * @param {createRequestSuccessResponse|ErrorResponse} responseData */
Данные успешного выполнения запроса создание заявки на обратный звонок:
/** * Данные успешного выполнения запроса создание заявки на обратный звонок * * @typedef {Object} createRequestSuccessResponse * * @property {number} callbackRequestId Идентификатор заявки на обратный звонок */
Формат данных в случае ошибки
/** * Данные в случае ошибки выполнения запроса * * @typedef {Object} ErrorResponse * * @property {string} type Тип ошибки * @property {string} message Текст ошибки * @property {Object} details Детали ошибки */
Возможные ошибки
Тип | Описание | |||||||||||||||
unknown_error | Различные ошибки на клиенте (таймаут ответа сервера, сброс соединения, некорректный json в ответе, ошибочный код ответа сервера) | |||||||||||||||
server_error | Ошибка сервера | |||||||||||||||
validation_error |
Ошибка при проверке корректности полей
|
|||||||||||||||
request_throttle_timeout | Превышен лимит на отправку заявок от данного пользователя | |||||||||||||||
request_throttle_count | Превышено кол-во запросов за период времени | |||||||||||||||
request_phone_blacklisted | Телефон в черном списке | |||||||||||||||
request_widget_not_found | Виджет для идентификатора формы не найден |
Примеры данных
1. В случае успешного создания заявки
{ "callbackRequestId ":231113 }
Примеры отображения обратного звонка
В данном примере рассмотрено создание заявки на обратный звонок с выбором отдела. Эта схема работы пригодится, если на Вашем сайте в форме есть выбор определенного дилерского центра, офиса или салона.
Для работы с отделами необходимо перейти в таб Отделы и выполнить необходимые настройки.
В скрипте, в зависимости от выбранного салона будет подставляться id соответствующего отдела.
Тогда при выборе "РТТ-Автомаркет Хошимина" скрипт будет иметь вид:
window.ctw.createRequest( 'test', '79000000000', [ {"name": "Имя", "value": "Иван"},
{"name": "Отчество", "value": "Иванович"}, {"name": "Фамилия", "value": "Иванов"}
], function(success, data)
{ console.log(success, data);
},
null,
[
'Форма заявки на тестдрайв','Nissan'
],
20256 /*id отдела*/
);
В личном кабинете Calltouch в "журнале звонков" звонок отобразиться так:
Отдел не отображается в "Журнале звонков", только соответствующий номер салона. Но вы можете настроить передачу тега, соответствующего отделу.
Система баллов API Calltouch
Система баллов API — механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch
Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).
- A/B тестирование (раздел «Подключение»)
- Email-трекинг (раздел «Подключение»)
- Отслеживание офлайн конверсии (раздел «Подключение»)
- Подключение к отслеживанию дополнительных доменов (раздел «Подключение»)
- Подмена номеров на AMP-страницах Google (раздел «Подключение»)