Наверх

JavaScript Callback API

Содержание

 

 

Общая информация

API - это программный интерфейс для внешних программных продуктов. Рассматриваемый в данном разделе API интерфейс позволяет отправлять заявки на обратный звонок, информация о которых будет загружена в журнал звонков.

Данный метод удобен тем, что не требует дополнительных действий для настройки. Нет необходимости настраивать обработчик на сервере и передавать отдельно идентификатор сессии Calltouch. ID сессии передается автоматически.

Ниже представлены функции Javascript API для получения данных о настройках виджета и отправки заявок на обратный звонок в Calltouch.

 

 

Подключение

Для подключения необходимо:

  1. Пополнить баланс минут и активировать услугу обратного звонка
  2. Создать специальный тип виджета "Форма на сайте" и настроить его.
  3. Включить виджет
  4. Добавить скрипт отправки заявок в наш сервис с помощью 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 )
 
Обратите внимание, что блок с параметрами "name" и "value" имеет ограничение по количеству передаваемых полей - их может быть максимум 5, а в блоке "tags" максимум 10. Значения можно передавать как на латинице, так и на кириллице.
Значения этих полей вы можете использовать для передачи дополнительной информации ко звонку в Журнале звонков или для оповещения операторов с помощью Синтеза речи (подробнее о настройке Синтеза речи в нашей инструкции). Порядок передачи параметров в данном скрипте будет влиять на то, в каком виде они будут отображены в Журнале звонков и в каком порядке они будут проигрываться при активации Синтеза речи.
 

 

 

Функции

 Получение данных виджета - 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

Ошибка при проверке корректности полей

Поле Тип Описание
fields object[] Список полей с ошибками
fields[].name string Название поля
fields[].errors object[] Список ошибок
fields[].errors[].message string Тест ошибки
request_throttle_timeout Превышен лимит на отправку заявок от данного пользователя
request_throttle_count Превышено кол-во запросов за период времени
request_phone_blacklisted Телефон в черном списке
request_widget_not_found Виджет для идентификатора формы не найден


Примеры данных

1. В случае успешного создания заявки

{
    "callbackRequestId ":231113
}

 

 

Примеры отображения обратного звонка 

В данном примере рассмотрено создание заявки на обратный звонок с выбором отдела. Эта схема работы пригодится, если на Вашем сайте в форме есть выбор определенного дилерского центра, офиса или салона.

Для работы с отделами необходимо перейти в таб Отделы и выполнить необходимые  настройки.

mceclip1.png

В скрипте, в зависимости от выбранного салона будет подставляться id соответствующего отдела.

Тогда при выборе "РТТ-Автомаркет Хошимина" скрипт будет иметь вид:

window.ctw.createRequest(
    'test',
    '74953333333',
    [
        {"name": "Имя", "value": "Иван"},
{"name": "Отчество", "value": "Иванович"}, {"name": "Фамилия", "value": "Иванов"}
], function(success, data)
{ console.log(success, data);
},
null,
[
'Форма заявки на тестдрайв','Nissan'
],
20256 /*id отдела*/
);

 В личном кабинете Calltouch в "журнале звонков" звонок отобразиться так:

mceclip0.png

 

Обратите внимание, отдел не отображается в "Журнале звонков", только соответствующий номер салона. Но вы можете настроить передачу тега, соответствующего отделу.