Серверное Callback API

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

Благодаря этому API методу можно автоматизировать прозвоны колл-центром поступающих заявок, а также настроить автоматический прозвон базы клиентов с регулированием времени звонка и выбором нужного оператора колл-центра.
Важным преимуществом данного метода в том, что для передачи заявок на обратный звонок не обязательно наличие скрипта Calltouch на сайте.

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

1. Пополнить баланс минут и активировать услугу обратного звонка
2. Создать специальный тип виджета "Форма на сайте" и настроить его.
3. Включить виджет
4. Настроить передачу заявок с сервера с помощью серверного API.

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

Запрос

Поддерживаемые методы отправки: POST.

       
POST /widget-service/v1/api/widget-request/user-form/create HTTP/1.1
   

HTTP-заголовки:

• Host: api.calltouch.ru
• Access-Token: <API-токен Calltouch>

Тело запроса в формате JSON:

{
    "routeKey": "Ключ виджета "Форма на сайте", к которому будет привязана заявка",
    "phone": "Номер телефона клиента",
    "fields": [
    {"name": "Название произвольного поля",
     "value": "Значение произвольного поля"}
    ],
    "sessionId": "ID сессии Calltouch",
    "scheduleTime": "Время, на которое заказали обратный звонок, в формате
      yyyy-mm-dd hh:mm:ss 2020-10-01 02:10:00",
    "utmSource": "Произвольный источник",
    "utmMedium": "Произвольный канал",
    "utmCampaign": "Произвольная кампания",
    "utmContent": "Произвольное объявление",
    "utmTerm": "Произвольная ключевая фраза",
    "callUrl": "URL-адрес страницы, с которой была отправлена заявка",
    "tags": [
      "Тег 1"
    ],
    "unitId": Идентификатор отдела в виджете "Форма на сайте"
}
   

Параметры запроса

"tags": [
{
"Тег 1",
"Тег 2",
}]

Пример запроса

HTTP-заголовки:

POST /widget-service/v1/api/widget-request/user-form/create HTTP/1.1
Host: api.calltouch.ru
Access-Token: <token>
...
   

{"routeKey": "routekey_1", "phone": "79992223344"}
   

{
   "routeKey": "routekey_1",
   "phone": "79992223344",
   "fields": [
      {"name": "Имя", "value": "Иван"},
      {"name": "Фамилия", "value": "Иванов"},
      {"name": "Отчество", "value": "Иванович"},
      {"name": "Город", "value": "Москва"},
      {"name": "Тема", "value": "Заявка на консультацию"}
      ],
    "sessionId": "11223344", 
    "scheduleTime": "2021-02-01 17:10:00",
    "utmMedium": "medium",
    "utmSource": "source",
    "utmCampaign": "campaign",
    "utmContent": "content",
    "utmTerm": "term",
    "tags": [
      "tag1","tag2","tag3","tag10"
    ],
    "unitId": 112233
}
   

Обратите внимание, что если указаны одновременно utmSource, utmMedium, utmCampaign, utmContent, utmTerm и sessionId, то sessionId имеет более высокий приоритет и источник будет взят из сессии.

Для работы с API необходимо в заголовке запроса указать токен, который можно получить в разделе личного кабинета Интеграции -> API и Webhooks -> API.

Для получении id сессии необходимо воспользоваться одним из способов:

1. Получение id сессии из скрипта подмены.

Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Чтобы получить ID сессии скрипта Calltouch или проверить отработал ли он или нет, используйте JS-функцию calltracking_params, например:

window.ct('calltracking_params','mod_id').sessionId
   

2. Получение id сессии из cookies.

Приведем пример реализации скрипта на PHP с использованием CURL:

$sessionId = $_COOKIE['_ct_session_id'];
   

В обоих случаях определившийся источник заявки на обратный звонок (с помощью переданного значения сессии) будет отображен в журнале звонков:

Более полное описание метода /api/widget-request/user-form/create представлено по ссылке http://api.calltouch.ru/widget-service/v1/

Данная документация отображает технические параметры запроса, а также предоставляет возможность отправки тестовых заявок на прозвон виджетом "Форма на сайте".
Для просмотра необходимо перейти в параметры заявки:

Чтобы отправить тестовую заявку необходимо авторизоваться, используя API-токен проекта, к которому вы планируете подключиться по API:

Для ознакомления с описанием метода и просмотра массива можно открыть каждый метод отдельно (строки кликабельны):

Для просмотра примера воспользуйтесь блоком "Example Value" и кнопкой Try it out + Execute.

Вы увидите ответ с описание кода:

Через данный блок, при использовании рабочего токена и routeKey, можно создать боевую заявку, которая будет обработана через сервис обратного звонка:

Для просмотра списка полей перейдите в блок Model.
Ниже список полей для создания заявки на обратный звонок:

Список ошибок

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

В данном примере будет рассмотрен прозвон клиентской базы, хранящейся в Google Sheets. Заявки на прозвон будут отправляться автоматически через сервис Альбато.

Подготовка таблицы Google Sheets

Для корректного прозвона списка клиентов и дальнейшей проверки необходимо подготовить данные к отправке.
На примере ниже подготовлена таблица с данными клиента (ФИО и телефон), произвольными значениями источников, заданным тегом и выбранным отделом.

Обратите внимание, что для корректной обработки полей таблицы на стороне Альбато, не должно быть пустых строк.

Настройка подключения и связок в Альбато

Для настройки связки необходимо будет создать следующие подключения:

• Google Sheets
• Calltouch
• Webhooks

Подробное описание настройки подключения к Google Sheets и дальнейшей настройке связки можно найти в базе знаний Альбато.

Для настройки подключения к Calltouch потребуется id сайта и ключ API (токен).

В настройках подключения Webhooks необходимо будет указать:

• адрес сервера API Calltouch - https://api.calltouch.ru/widget-service/v1/api/widget-request/user-form/create
• параметры запроса:

     utmSource
     utmMedium
     utmCampaign
     utmContent
     utmTerm
     routeKey
     phone
     fields.0.name
     fields.0.value
     tags.0
     unitId

В настроенном виде связка выглядит так:

В настройке отправки вебхука необходимо задать соответствие столбцов таблицы и полей запроса:

Отображение результатов в журнале звонков

После запуска связки звонки начнут обрабатываться. В журнале звонков будут отображены звонки с полем ФИО, заданными источниками и тегом.

Таким образом был получен инструмент автоматического обзвона клиенткой базы.
При необходимости, можно обогатить передаваемую информацию дополнительными полями, что позволит передавать оператору колл-центра более полные данные о клиенте через синтез речи.