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 | Ссылка на аудиозапись |
| call_card | Ссылка на карточку звонка для номера, с или на который звонили |
| additional_number | Добавочный номер, введенный при звонке на Голосовое меню IVR |
| has_recording | Значение 1 или 0, в зависимости от того, был ли записан разговор при звонке |
| scheme_name | Название схемы переадресации, на которую был направлен звонок |
| duration_ms | Длительность разговора в миллисекундах (duration*1000) |
Фильтры в запросе
Фильтры необходимы для выборки звонков по заданным параметрам. Для указания фильтра используется параметр 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;
- поля выборки – дата звонка, номер звонящего, куда звонили, статус, длительность разговора, источник/канал перехода, ссылка на аудиозапись;
- фильтр с регулярным выражением по статусам звонков – отвечен, целевой, повторный;
- объединение по номеру звонящего за сутки;
- сортировка даты звонка по возрастанию;
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.
Внимание! Пример условный и предоставлен для понимания принципа работы и его реализации!
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*
*В целях безопасности ключ авторизации предоставляется только по запросу для активных (действующих) проектов (не триал)
"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.
Внимание! Пример условный и предоставлен для понимания принципа работы и его реализации!
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
Узнать какие SIP aккаунты по проекту разговаривают
Данный метод позволит определить какие sip-аккаунты не заняты. Возвращает массив в формате JSON sip-аккаунтов менеджеров проекта, которые в данный момент разговаривают.
- Адрес отправки запроса – https://api.ringostat.com/sipstatus/speakingNow
- Content-Type – application/json
- Метод отправки данных – GET
