JavaScript Callback API

Читать 10

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

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 до 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

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

Поле Тип Описание
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',
    '79000000000',
    [
        {"name": "Имя", "value": "Иван"},
        {"name": "Отчество", "value": "Иванович"},
        {"name": "Фамилия", "value": "Иванов"}
    ],
    function(success, data)
      {
        console.log(success, data); 
      },
        null,
    [ 
        'Форма заявки на тестдрайв','Nissan' 
    ], 
        20256 /*id отдела*/
);
В личном кабинете Calltouch в "журнале звонков" звонок отобразиться так:

mceclip0.png

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

Система баллов API Calltouch

Система баллов API - механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch

Количество запросов в секунду к API Calltouch ограничено – не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой.

Не нашли решение проблемы?
Заполните форму, и мы вам поможем.
х
Заполните форму
и мы поможем вам
Похожие статьи
Недавно просмoтренные