Читать 11

Серверное Callback API


Описание

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

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

Подключение

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

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

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

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

Запрос

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

https://api.calltouch.ru/widget-service/v1/api/widget-request/user-form/create
HTTP-заголовки:
  • Access-Token — API-ключ
  • SiteId — ID ЛК 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 Да, если указан параметр fields
Название поля. Любые символы, количеством от 1 до 255.
fields.value string Да, если передается параметр fields

Значение поля. Любые символы, количеством от 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 string
Нет

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

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

utmTerm

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

callUrl

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

tags

array Нет

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

Формат:

"tags": [ "Тег 1", "Тег 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.

Идентификатор сессии 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

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

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

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

Количество запросов в секунду к API Calltouch ограничено — не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой c кодом 429 (Too Many Requests).


Не нашли решение проблемы?
Заполните форму, и мы вам поможем.