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)
}
});
Создание заявки
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
)
Значения этих полей вы можете использовать для передачи дополнительной информации ко звонку в Журнале звонков или для оповещения операторов с помощью Синтеза речи (подробнее о настройке Синтеза речи в нашей инструкции). Порядок передачи параметров в данном скрипте будет влиять на то, в каком виде они будут отображены в Журнале звонков и в каком порядке они будут проигрываться при активации Синтеза речи.
Функции
Получение данных виджета - 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 до 15)
* @param {string} fields[].name
*
* Значение поля (длина от 1 до 35)
* @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 в "журнале звонков" звонок отобразиться так:
Обратите внимание: отдел не отображается в "Журнале звонков", только соответствующий номер салона. Но вы можете настроить передачу тега, соответствующего отделу.