Наверх

Серверное Callback API

Содержание

 

 

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

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

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

 

 

Подключение

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

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

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

 

 

API-метод для создания заявок на обратный звонок

Запрос

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

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

  • POST /widget-service/v1/api/widget-request/user-form/create HTTP/1.1
  • 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": Идентификатор отдела в виджете "Форма на сайте"
}

 

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

 

Параметр Формат Обязательный Описание
routeKey string Да Ключ виджета "Форма на сайте", к которому будет привязана заявка. Любые символы, количеством от 1 до 255. Обязательное.
phone string Да

Номер в 11-значном формате 7xxxxxxxxxx, с которым нужно соединить колл-центр. Могут быть использованы мобильные и городские номера РФ, кроме 8800 и 8804. Обязательное.

fields array Нет Массив полей с произвольными данными. Можно перечислить до 5 дополнительных полей. Данные поля будут отображаться в журнале звонков в карточке клиента, а также доступны для подключения к синтезу речи.
fields.name string Нет Название поля. Любые символы, количеством от 1 до 255.
fields.value string Нет

Значение поля. Любые символы, количеством от 1 до 255.

sessionId integer Нет

ID сессии Calltouch. Любые символы, максимум 100. ID сессии должен принадлежать сайту, токен которого используется в запросе.
Если ID сессии не указан и не заданы произвольные источники, то звонку будет присвоен источник по умолчанию:
utm_source=Callback
utm_medium=<не указано>
utm_campaign=<не заполнено>
utm_content=<не указано>
utm_term=<не указано>

Обратите внимание, что источники повторных звонков присваиваются согласно правилу присвоения источника повторным звонкам и заявкам.

Подробнее о получении sessionId в статье: Получение id сессии Calltouch

scheduleTime string Нет

Дата и время отправки заявки. Формат: dd-mm-yyyy hh:mm:ss.

utmSource string Нет Произвольный источник
utmMedium string Нет Произвольный канал
utmCampaign array Нет

Произвольная кампания

utmContent object Нет Произвольное объявление

utmTerm

string Нет Произвольная ключевая фраза

callUrl

string Нет URL-адрес страницы, с которой была отправлена заявка

tags

array Нет

Добавление тегов к звонку. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 10 тегов.

Формат:

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

unitId

integer Нет Идентификатор отдела виджета "Форма на сайте", к которому будет привязана заявка. 

 

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

 

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.


mceclip0.png

____________.png

 

Идентификатор сессии Calltouch

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

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

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

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

Где вместо mod_id нужно указать идентификатор скрипта Calltouch.

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

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

$sessionId = $_COOKIE['_ct_session_id'];

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

mceclip011.png

 

 

Техническая документация

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

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

mceclip3.png

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

mceclip4.png

mceclip5.png 

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

mceclip6.png

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

mceclip9.png

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

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

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

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

Код Описание
1 Синтаксическая ошибка JSON в запросе или запрос пустой
10001 Невозможно создать заявку виджета, недостаточно минут обратного звонка
10002 Невозможно создать заявку виджета, услуга обратного звонка не включена
10003 Невозможно создать заявку виджета, не найдено включенных виджетов с указанным ключом
10004 Невозможно создать заявку виджета, указанная сессия не найдена
10005 Превышен лимит отправки заявок в рамках сессии, если передан sessionId
10006 Превышен лимит отправки заявок на один и тот же номер телефона, если не передан sessionId
10007

Превышен лимит минимального интервала между отправкой заявок по номеру телефону или сессии

 

 

Пример реализации

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

 

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

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

mceclip1.png

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

 

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

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

  • Google Sheets
  • Calltouch
  • Webhooks