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

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

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

Адрес Ringostat API — https://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
формат взаимодействия с API – json или 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-Type – application/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-Type – application/json
Метод отправки данных – GET

https://api.ringostat.com/sipstatus/speakingNow?project_id=ID проекта&token=token авторизации