Ringostat API: описание, настройка и интеграция

Ringostat API (Application Programming Interface) — это набор готовых средств (классов, процедур, функций) доступа, взаимодействия и управления, предоставляемых Ringostat для использования во внешних программных продуктах (CRM-системы, системы статистики и аналитики и т.п.).
Используя интеграцию с Ringostat по API у вас появляются возможности самостоятельно отправлять нужные запросы нам на сервер или вызывать определенные события.


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

  • Адрес Ringostat APIhttps://api.ringostat.com
  • Доступ к Ringostat API — с помощью Project ID и token.
    Project ID — это идентификатор проекта в системе Ringostat;
    token — электронный ключ для доступа к проекту в системе Ringostat;
Где найти Project ID и token

Project ID и token авторизации, вы можете взять из раздела "Интеграции" - "Alytics":


Давайте рассмотрим несколько реализаций API-интеграции с CRM, которые будут вам полезны:

API-запрос экспорта данных по звонкам

Экспорт журнала звонков удобный способ получить свыше 30 параметров в удобном для вас формате. Данную выгрузку можно использовать для дальнейшего импорта в стороннюю систему

  • Адрес отправки запросаhttps://api.ringostat.com/calls/export
  • Метод отправки данныхGET
  • формат взаимодействия с APIjson или csv

Основные параметры

Основные параметры предназначены для доступа к Ringostat API(project_id и token), а так же указания даты выборки и формата выгрузки данных.

Имя параметра Описание Формат / тип данных Возможные значения Значение по умолчанию
project_id Идентификатор проекта в системе Ringostat Int нет
token Ключ авторизации в проекте string нет
export_type Формат выгрузки одно из возможных значений csv, json json
from Начальные дата и время экспорта дата и время в формате
'YYYY-MM-DD HH:MM:SS'
значение параметра "to" минус 24 часа
to Конечные дата и время экспорта дата и время в формате
'YYYY-MM-DD HH:MM:SS'
текущие дата и время
fields Поля для выборки данных из журнала звонков одно или несколько возможных значений разделенных запятыми Список полей и их описание в отдельной таблице calldate, caller, dst
filters Фильтры один или несколько фильтров, разделенных запятыми Список фильтров в отдельной таблице
merge Объединение по номеру звонящего Int одно из возможных значений:
0 - не объединять
1 - объединять за каждые сутки
2 - объединить за все время экспорта
0 - не объединять
order Сортировка String текущие дата и время

Поля для выборки

За основными параметрами следуют поля для выборки. Для указания полей используется параметр fields. Он позволяет указать одно или несколько значений разделённые запятыми.

Если в запросе отсутствуют поля выборки – в ответ поступят поля по умолчанию: calldate / caller / dst

Имя поля Описание
caller Номер звонящего
dst Куда звонили
pool_name Имя пула, в котором расположен номер
disposition Статус звонка
calldate Дата и время звонка
category_mark Ценность звонка
duration Длительность звонка(ожидание + разговор)
call_type Тип звонка( входящий / исходящий / callback)
waittime Время ожидания ответа на звонок
billsec Длительность разговора
connected_with С кем соединен
call_counter Какой по счету звонок
proper_flag Статус звонка: Целевой
repeated_flag Статус звонка: Повторный
utm_source Источник перехода
utm_medium Канал перехода
utm_campaign Кампания объявления
utm_content Содержание объявления
utm_term Ключевое слово объявления
uniqueid id звонка в системе Ringostat
category_number Категория звонка
caller_region Регион номера звонящего
employee_number Код сотрудника
employee_mark Оценка сотруднику за звонок
client_id UUID посетителя
remote_ip IP посетителя
refferrer URL адрес страницы, с которой посетитель перешёл на сайт
landing Страница входа посетителя
recording Ссылка на аудиозапись
&fields=caller,dst,connected_with,utm_source,utm_medium,remote_ip,recording

Фильтры в запросе

Фильтры необходимы для выборки звонков по заданным параметрам. Для указания фильтра используется параметр filters.

Он позволяет указать один или несколько фильтров разделённых запятыми. Фильтр состоит из имени поля, символа сравниния и значением в соответствующей последовательности.

Особое внимание стоит уделить фильтру по регулярному выражению.

Литерал регулярного выражения должен быть закодирован в base64

Фильтр Описание фильтра
> больше
< меньше
>= больше, либо равно
<= меньше, либо равно
= равно
<> не равно
~ регулярное выражение
//фильтр по статусу звонка "Отвечен"
&filters=disposition=answered

//фильтр с регулярным выражением по статусам звонков "Отвечен / Целевой / Повторный"
&filters=disposition~YW5zd2VyZWR8cHJvcGVyfHJlcGVhdGVk

//Пример кодировки литерала регулярного выражения в base64 используя метод JS – btoa
var encodedStatus = window.btoa('answered|proper|repeated');

Объединение по номеру звонящего

Объединение звонков по номеру звонящего используется для группировки данных по звонкам и облегчения визуального восприятия выгруженных данных.

Для объединения звонков используется параметр merge. По умолчанию параметр равен 0.

  • 0 – не объединять;
  • 1 – объединять за каждые сутки;
  • 2 – объединить за все время экспорта.

Сортировка

Сортировка это один из инструментов группировки выгруженных данных. Для сортировки данных используется параметр order.

Он позволяет одну или несколько сортировок разделённых запятыми. Сортировка состоит из имени поля и направлению сортировки через пробел.
По умолчанию параметр равен calldate asc.

  • asc – по возрастанию;
  • desc – по убыванию.
//Объединение полей за каждые сутки
&merge=1

//Сортировка по возрастанию даты звонка
&order=calldate%20asc


Пример полного API-запроса на экспорт звонков

  • выгрузка звонков за неделю;
  • формат выгрузки – json;
  • поля выборки – дата звонка, номер звонящего, куда звонили, статус, длительность разговора, источник/канал перехода, ссылка на аудиозапись;
  • фильтр с регулярным выражением по статусам звонков – отвечен, целевой, повторный;
  • объединение по номеру звонящего за сутки;
  • сортировка даты звонка по возрастанию;
https://api.ringostat.com/calls/export?
project_id=ID проекта
&token=token авторизации
&export_type=json
&from=2018-09-24%2000:00:00
&to=2018-10-01%2023:59:59
&fields=calldate,caller,dst,disposition,billsec,utm_source,utm_medium,recording
&filters=disposition~YW5zd2VyZWR8cHJvcGVyfHJlcGVhdGVk
&merge=1
&order=calldate%20asc

API-запрос Callback
(простой метод)

Для оперативности обработки заявок от клиентов, вы можете настроить автоматический перезвон клиенту, который отправляет заполненную форму регистрации или заказа на вашем сайте.
Аналогично можно инициировать звонок из карточки клиента в вашей CRM.

Параметры project_id и token должны быть в URL-е, остальные в теле POST запроса

  • Адрес отправки запросаhttps://api.ringostat.com/callback/outbound_call
  • Метод отправки данныхPOST
  • Идентификатор проектаproject_id
  • Ключ авторизации в проектеtoken
  • Номер в международном формате / логин SIP-аккаунта, с которого звонить – extension
    (номер должен быть подключен в проект как "входящий", в раздел "Подключение номеров");
  • Номер клиента в международном форматеdestination

Давайте рассмотрим пример реализации запроса на Ajax.

Внимание! Пример условный и предоставлен для понимания принципа работы и его реализации!

$.ajax({
url: "https://api.ringostat.com/callback/outbound_call?project_id=ID проекта&token=token",
type: "POST",
headers: {
"Content-Type":"application/json"
},
data: JSON.stringify({
"extension": "380441112233", //Номер из проекта в международном формате или логин SIP-акканта
"destination": "380442223344" //Номер клиента в международном формате
})
});

API-запрос Callback
(расширенный метод)

Расширенный метод универсален, позволяет инициировать звонок между любыми двумя сторонами, которых нет у нас в системе(например, одного из менеджеров и клиента), а так же зафиксировать источники перехода аналогично стандартному Callback.
Данный метод подойдёт для вызова звонка из CRM системы, обработки заявок от клиентов, которые отправляют заполненную форму регистрации или заказа на вашем сайте, или classified решений(досок объявлений).

  • Адрес отправки запросаhttps://api.ringostat.net/a/v2
  • Метод отправки данныхPOST
  • Доступ к Ringostat API – с помощью ключа авторизации auth-key*

*В целях безопасности ключ авторизации предоставляется только по запросу для активных (действующих) проектов (не триал)

//Response headers
"content-type": "application/json" //MIME тип ресурса. Тип – string
"auth-key": "Ключ авторизации" //Ключ авторизации для доступа к Ringostat API. Тип – string

//Request body
{
"jsonrpc": "2.0", //Версия протокола. Тип – string
"id": 777, //Любое число, используется для установки соответствия между запросом и ответом. Тип – int "method": "Api\\V2\\Callback.external", //Метод на сервере Ringostat. Тип – string
"params": //Объект с параметрами, который будет передан методу
{
"caller": "380441112233", //Номер клиента в международном формате. Тип – string
"callee": "380441112233", //Номер менеджера в международном формате. Тип – string
"projectId": "77777", //ID проекта в системе Ringostat. Тип – string
"manager_dst": 1, //Направление 1го звонка: 1 - менеджер, 0 - клиент. Тип – int
"clientIp": "ip-адрес посетителя", //IP-адрес посетителя. Тип – string
"utmSource": "источник перехода", //Источник перехода. Тип – string
"utmMedium": "канал перехода", //Канал перехода. Тип – string
"utmCampaign": "кампания", //Кампания перехода. Тип – string
"utmTerm": "ключевое слово", //Ключевое слово перехода. Тип – string
"utmContent": "содержимое", //Содержимое объявления. Тип – string
"clientId": "Client ID Google Analytics", //GA Client ID посетителя. Тип – string
"clientUserAgent": "Клиентское приложение" //Клиентское приложение посетителя. Тип – string
}
}

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

Обязательные параметры, расположены в объекте и не должны содержать пустое значение:
auth-key – Ключ авторизации для доступа к Ringostat API. В целях безопасности, нужно добавлять в заголовок запроса;
caller – Номер клиента в международном формате;
callee – Номер менеджера в международном формате
projectId – ID проекта в системе Ringostat
clientIp – IP-адрес посетителя

Остальные параметры объекта – могут быть переданы с пустым значением.

Для передачи данных о сессии посетителя – их нужно собирать самостоятельно и добавить в запрос.
Для примера, utm-метки перехода, можно извлечь из куки-файла rngst2(если установлен скрипт подмены), а ClientID Google Analytics из куки-файла _ga.

Давайте рассмотрим пример реализации запроса на Ajax.

Внимание! Пример условный и предоставлен для понимания принципа работы и его реализации!

$.ajax({
url: "https://api.ringostat.net/a/v2",
type: "POST",
headers: {
"Content-Type":"application/json",
"auth-key":"Ключ авторизации"
},
data:JSON.stringify ({
"jsonrpc": "2.0",
"id": 777,
"method": "Api\\V2\\Callback.external",
"params": {
"caller": "380441112233",
"callee": "380442223344",
"projectId": "77777",
"manager_dst": 1,
"clientIp": "10.10.10.10",
"utmSource": "google",
"utmMedium": "cpc",
"utmCampaign": "API Callback",
"utmTerm": "call test",
"utmContent": "API Callback request test",
"clientId": "576047607.1537442595",
"clientUserAgent": "Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
}
})
});
  • 400 Bad Request – отсутствует передача одного из параметров / caller или callee не валидны / значение объекта JavaScript не преобразовано в строку JSON
  • 401 Unauthorized – некорректно добавлен auth-key или ошибка Cross-Origin Resource Sharing (CORS)
  • 403 Forbidden – отказано в доступе из-за некорректного значения auth-key или он не добавлен в Access List

Проверка активности SIP-аккаунтов

Данный метод позволяет в крупном отделе продаж контролировать менеджеров в системе и проверять кто из них недоступен или разговаривает. Эту информацию можно использовать для маршрутизации звонков между менеджерами.

Узнать какие SIP-аккаунты проекта в статусе Online

Данный метод позволит определить какие sip-аккаунты активны. Возвращает массив в формате JSON sip-аккаунтов менеджеров проекта, которые в данный момент on-line.

  • Адрес отправки запросаhttps://api.ringostat.com/sipstatus/siponline
  • Content-Typeapplication/json
  • Метод отправки данныхGET
https://api.ringostat.com/sipstatus/siponline?project_id=ID проекта&token=token авторизации

Узнать какие SIP aккаунты по проекту разговаривают

Данный метод позволит определить какие sip-аккаунты не заняты. Возвращает массив в формате JSON sip-аккаунтов менеджеров проекта, которые в данный момент разговаривают.

  • Адрес отправки запросаhttps://api.ringostat.com/sipstatus/speakingNow
  • Content-Typeapplication/json
  • Метод отправки данныхGET
https://api.ringostat.com/sipstatus/speakingNow?project_id=ID проекта&token=token авторизации


Была ли статья полезной?