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, которые будут вам полезны:

Выгрузка статистики по звонкам

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

  • формат взаимодействия с API: json или csv;
  • метод отправки данных к API: GET;

Список передаваемых параметров

Имя параметра Описание Формат Возможные значения Значение по умолчанию
project_id Идентификатор проекта в системе Ringostat число нет
token Авторизационный токен строка нет
export_type Формат выгрузки одно из возможных значений csv, json json
from Начальные дата и время экспорта дата и время в формате 'YYYY-MM-DD HH:MM:SS' значение параметра "to" минус 24 часа
to Конечные дата и время экспорта дата и время в формате 'YYYY-MM-DD HH:MM:SS' текущие дата и время
fields Перечень необходимых полей для выборки одно или несколько возможных значений, разделенных запятыми
caller Номер звонящего calldate,caller,dst
dst
Куда звонили
pool_name Имя пула номера
disposition Статус
calldate Дата
category_mark Ценность
duration Длительность
call_type Тип
waittime Ожидание
billsec Разговор
connected_with С кем соединен
call_counter Какой по счету звонок
proper_flag Целевой
repeated_flag Повторный
utm_source Источник
utm_medium Канал
utm_campaign Кампания
utm_content Содержание объявления
utm_term Ключевое слово
region Регион
uniqueid id звонка
category_number Категория звонка
caller_region Регион звонящего
employee_number Код сотрудника
employee_mark Оценка сотрудника
client_id UUID посетителя
remote_ip IP посетителя
refferrer Откуда пришел посетитель
landing На какую страницу пришел
recording Ссылка на аудиозапись
filters Фильтры один или несколько фильтров, разделенных запятыми. Фильтр состоит из имени поля, символа сравниния и значением в соответствующей последовательности. Литерал регулярного выражения должен быть закодирован в base64.
> больше нет
< меньше
>= больше, либо равно
<= меньше, либо равно
= равно
<> не равно
~ регулярное выражение
merge Объединение по номеру звонящего одно из возможных значений:
0 - не объединять
1 - объединять за каждые сутки
2 - объединить за все время экспорта
0, 1, 2 0
order Сортировка одна или несколько сортировок, разделенных запятыми.
Сортировка состоит из имени поля и направлению сортировки через пробел.
asc по возрастанию calldate asc
desc по убыванию

Давайте рассмотрим несколько примеров:

Запрос:

https://api.ringostat.com/calls/export?project_id=999&token=be6d748913ccb22f2bv555555555c
&export_type=json&from=2016-05-05%2010:00:00&to=2015-06-06%2010:00:00
&fields=caller,disposition,calldate,duration&merge=1&order=calldate%20asc

Результат:


Запрос:

https://api.ringostat.com/calls/export?project_id=999&token=be6d748913ccb22f2bv555555555c
&export_type=json&from=2016-06-02%2000:00:00&to=2016-06-08%2000:00:00
&fields=caller,dst,connected_with,utm_source,utm_medium,remote_ip,recording&merge=1
&order=calldate%20asc

Результат:


Запрос:

https://api.ringostat.com/calls/export?project_id=999&token=be6d748913ccb22f2bv555555555c
&export_type=json&from=2016-05-05%2000:00:00&to=2016-06-06%2010:00:00
&fields=disposition,calldate,refferrer&filters=duration<10

Результат:


Звонок клиенту после отправки
формы заказа (простой метод)

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

  • метод отправки данных к API:  POST;
  • project_id — это идентификатор проекта в системе Ringostat;
  • token — являются ключом для доступа к проекту в системе Ringostat;
  • extension — номер в международном формате или sip-аккаунт с которого звонить;
    (номер должен быть подключен в проект как "входящий", в раздел "Подключение номеров");
  • destination — номер в международном формате на который звонить.

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


Пример готового запроса

https://api.ringostat.com/callback/outbound_call?project_id=999&token=be6d748913ccb22f2bv555555555c
extension=380441111111
destination=380442222222

Звонок клиенту после отправки
формы заказа
(расширенный метод)

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

  • Метод отправки данных – POST;
  • Адрес Ringostat API — https://api.ringostat.net/a/v2
  • Доступ к Ringostat API — с помощью ключа авторизации(Auth-Key)*
    *В целях безопасности ключ авторизации предоставляется только по запросу для активных(действующих) проектов(не триал).

Описание запроса и параметров


  • Headers(заголовок запроса) – определяет тип передаваемых данных:
    content-type: application/json
    Auth-Key: <ключ авторизации>
  • Body(тело запроса) – содержит массив передаваемых параметров:
    { "jsonrpc": "2.0",
    указывает использование JsonRPC версии 2.0;
    "id": <любое число>,
    значение любого типа, которое используется для установки соответствия между запросом и ответом;
    "method": "Api\\V2\\Callback.external",
    название метода, который будет выполнен на сервере Ringostat;
    "params":
    Массив объектов, которые должны быть переданы методу, как параметры;
    {
    Обязательные параметры:
    "caller": "<номер в международном формате>",
    Номер клиента отправившего запрос.
    "callee": "<номер в международном формате>",
    Номер менеджера, который должен ответить на звонок.
    "projectId": "числовое значение",
    ID проекта в системе Ringostat;
    "clientIp": "ip-адрес посетителя",
    IP-адрес посетителя отправившего запрос звонка;
    Необязательные параметры:
    "utmSource": "источник перехода",
    "utmMedium": "канал перехода",
    "utmCampaign": "кампания",
    "utmTerm": "ключевое слово",
    "utmContent": "содержимое",
    "clientId": "Client ID Google Analytics",
    "clientUserAgent": "клиентское приложение, через которое выполнен доступ" }}

Как видно из описания, обязательными является ключ авторизации и 4 параметра, передаваемые в теле запроса – caller, callee, projectID, clientIP. Остальные параметры необязательные,Вы можете не передавать их(отправлять пустое значение), но тело запроса должно их содержать.
Если заголовки и тело запроса корректны, а параметры caller(номер клиента) и callee(номер менеджера) окажутся валидными номерами – состоится звонок.

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

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


Результат отображения в журнале звонков:




Возможные ошибки:


1. если основные параметры(caller, callee, Auth-Key, clientIP) не прошли проверку, в ответ поступит ошибка 403;

2. если caller или callee не валидны или отсутствует передача одного из параметров, в ответ поступит ошибка 400


Проверка доступности sip-аккаунтов менеджеров

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

Узнать какие SIP aккаунты по проекту онлайн

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

  • формат взаимодействия с API: json;
  • метод отправки данных к API: GET;

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

https://api.ringostat.com/sipstatus/siponline?project_id=999&token=be6d748913ccb22f2bv555555555c

Результат:



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

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

  • формат взаимодействия с API: json;
  • метод отправки данных к API: GET;

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

https://api.ringostat.com/sipstatus/speakingNow?project_id=999&token=be6d748913ccb22f2bv555555555c

Результат:



Будем рады ответить на ваши вопросы в чате или на email: Support Team

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