Описание Ringostat API и общая информация
Ringostat API (Application Programming Interface) — это набор готовых средств (классов, процедур, функций) доступа, взаимодействия и управления, предоставляемых Ringostat для использования во внешних программных продуктах (CRM-системы, системы статистики и аналитики и т.п.).
Используя интеграцию с Ringostat по API у вас появляются возможности самостоятельно отправлять нужные запросы нам на сервер или вызывать определенные события.
- в любой удобный момент получить свыше 30 параметров по звонкам
- обращаться для проверки номера звонящего
при реализации собственной логики переадресации звонков; - инициациировать звонок между 2мя направлениями(простой метод)
используется для инициирования звонков из CRM-системы(если она позволяет и 1но из направлений это SIP-аккаунт или номер в проекте) -
инициациировать звонок между 2мя направлениями(расширенный метод)
используется при реализации собственного виджета обратного звонка - проверить доступность SIP-аккаунта(созданного в рамках проекта)
в ответ на запрос будет отправлен массив логинов SIP-аккаунтов, которые в сети(online) -
проверить активность SIP-аккаунта(созданного в рамках проекта)
в ответ на запрос будет отправлен массив логинов SIP-аккаунтов, которые сейчас разговаривают(входящий или исходящий звонок)
Доступ к API-методам Ringostat возможен при наличии project ID и user token:
project ID — унильканый идентификатор проекта в системе Ringostat;
user token — уникальный ключ-доступа пользователя в проекте, в системе Ringostat;
project ID и user token для авторизации, вы можете найти на странице Интеграции -> Alytics:
Экспорт журнала звонков
API-запрос экспорта журнала звонков, позволяет получить свыше 30 параметров в удобном для вас формате. Используя всего 1м запросом можно получить всю необходимую историю взаимодействия пользователя с сайтом и звонками.
В сочетании с функционалом переадресации с помощью Webhook перед звонком клиента, вы можете проверить его номер на предмет повторности его звонка и/или наличие исходящего звонка для переадресации на менеджера, с которым ранее общался звонящий.
Основные параметры запроса:
GET https://api.ringostat.com/calls/export
| Имя параметра | Описание | Значение по умолчанию |
|---|---|---|
project_id |
Уникальный идентификатор проекта в системе Ringostat | нет |
token |
Уникальный ключ-доступа пользователя в проекте, в системе Ringostat; | нет |
export_type |
Формат выгрузки данных: json или csv |
json |
from |
Начальные дата и время экспорта в формате YYYY-MM-DD HH:MM:SS |
значение to минус 24 часа |
to |
Конечные дата и время экспорта в формате YYYY-MM-DD HH:MM:SS |
текущие дата и время |
fields |
Список полей для выборки из журнала звонков, разделённых запятой; | calldate, caller, dst |
filters |
Фильтры, для выборки данных подпадающих под условие по значениям полей | нет |
merge |
Объединение выборки по номеру звонящего:0 – не объединять;1 – объединять за каждые 24 часа;2 – объединять за всё время; |
0 – не объединять; |
order |
Сортировка выборки | текущие дата и время |
- Пример AJAX запроса
- Результат
Поля для выборки
За основными параметрами следуют поля для выборки. Для добавления полей используется ключ fields. Он позволяет добавить одно или несколько значений разделённые запятыми.
| Параметр | Описание |
|---|---|
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
|
Категория звонка |
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) |
- Пример AJAX запроса
- Результат
Фильтры выборки
Фильтры необходимы для выборки звонков по заданным параметрам. Для добавления фильтра используется ключ filters, который позволяет добавлять один или несколько фильтров разделённых запятыми.
Фильтр состоит из имени поля, символа сравнения и значением в соответствующей последовательности.
| Фильтр | Описание фильтра |
|---|---|
>
|
больше |
<
|
меньше |
>=
|
больше, либо равно |
<=
|
меньше, либо равно |
=
|
равно |
<>
|
не равно |
~
|
регулярное выражение Литерал должен быть закодирован в base64 |
- Пример AJAX запроса
- Результат
Объединение и сортировка
Объединение звонков по номеру звонящего используется для группировки данных по звонкам и облегчения визуального восприятия выгруженных данных.
Для объединения звонков используется ключ merge и по умолчанию он равен 0
Сортировка это один из инструментов группировки выгруженных данных.
Для сортировки данных используется ключ order и по умолчанию равен calldate%20asc
| Имя параметра | значение параметра |
|---|---|
merge
|
|
0 – объединять за каждые сутки; |
|
1 – объединять за каждые сутки; |
|
2 – объединять за каждые сутки; |
|
order
|
|
asc – по возрастанию; |
|
desc – по убиванию; |
- Пример AJAX запроса
- Результат
API-запрос соединения 2х номеров(простой метод Callback)
Для оперативности обработки заявок от клиентов, вы можете настроить автоматический перезвон клиенту,
который отправляет заполненную форму регистрации или заказа на вашем сайте.
Аналогично можно инициировать звонок из карточки клиента в вашей CRM.
Одно из направлений звонка, должно быть SIP-аккаунтом или номером из проекта.
Описание параметров запроса
POST https://api.ringostat.com/callback/outbound_call
| Имя параметра | Описание |
|---|---|
project_id |
Уникальный ID проекта в системе Ringostat должен быть указан в URL-адресе запроса |
token |
Уникальный токен пользователя в проекте, в системе Ringostat должен быть указан в URL-адресе запроса |
extension |
Номер телефона или логин SIP-аккаунта, с которого звонить> (номер должен быть подключен в проект как "входящий", в разделе "Подключение номеров"); |
destination |
Номер телефона или логин SIP-аккаунта, на который звонить |
- Пример AJAX запроса
API-запрос соединения 2х номеров(расширенный метод Callback)
Расширенный метод универсален, позволяет инициировать звонок между любыми двумя сторонами, которых нет у нас в системе(например, одного из менеджеров и клиента), а так же зафиксировать источники перехода аналогично стандартному Callback.
Данный метод подойдёт для вызова звонка из CRM системы, обработки заявок от клиентов, которые отправляют заполненную форму регистрации или заказа на вашем сайте, или classified решений(досок объявлений).
Доступ к данному методу API возможен, только при наличие Auth-key*
*В целях безопасности ключ авторизации
предоставляется только по запросу для активных (действующих) проектов (не триал)
Описание параметров запроса
POST https://api.ringostat.net/a/v2
| Имя параметра | Описание | |
|---|---|---|
| headers запроса | ||
content-type |
application/json | |
auth-key |
"extended_callback_method_auth-key" | |
| body запроса | ||
jsonrpc |
Версия протокола. Значение 2.0 |
|
id |
Любое число, используется для установки соответствия между запросом и ответом | |
method |
Метод на сервере Ringostat. Значение Api\\V2\\Callback.external |
|
params |
||
callee_type |
Позволяет указать переадресацию на схему переадресацииdefault – номер телефонаscheme – схема переадресации
|
|
caller_type |
Позволяет указать переадресацию на схему переадресацииdefault – номер телефонаscheme – схема переадресации |
|
caller |
Номер телефона или SIP-аккаунт звонящего | |
callee |
Номер телефона или SIP-аккаунт, адресата звонка | |
projectId |
Уникальный ID проекта в системе Ringostat | |
manager_dst |
Направление 1го звонка:1 - менеджер0 - клиент |
|
clientIp |
IP-адрес посетителя | |
utmSource |
источник перехода | |
utmMedium |
канал перехода | |
utmCampaign |
Кампания | |
utmTerm |
ключевое слово | |
utmContent |
Содержимое | |
clientId |
Client ID Google Analytics | |
clientUserAgent |
Клиентское приложение | |
- Пример AJAX запроса
Обязательные параметры, расположены в объекте и не должны содержать пустое значение:
auth-key, caller, callee, projectId, clientIp
Остальные параметры объекта – могут быть переданы с пустым значением.
Для передачи данных о сессии посетителя – их нужно собирать самостоятельно и добавить в запрос.
Для примера, utm-метки перехода, можно извлечь из куки-файла rngst2(если установлен скрипт подмены), а ClientID Google Analytics из куки-файла _ga.
- 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). Возвращает массив в формате JSON sip-аккаунтов менеджеров проекта.
Описание параметров запроса
GET https://api.ringostat.com/sipstatus/siponline
Content-Type – application/json
- Пример AJAX запроса
- Результат
Проверка наличия активного звонка у SIP-аккаунта
Данный метод позволит определить какие sip-аккаунты не заняты. Возвращает массив в формате JSON sip-аккаунтов менеджеров проекта, которые в данный момент разговаривают.
Описание параметров запроса
GET https://api.ringostat.com/sipstatus/speakingNow
Content-Type – application/json
- Пример AJAX запроса
- Результат