Функционал доступен при наличии лицензии SMG-API.

Введение

Назначение

WebSocket API шлюза SMG предоставляет доступ к событиям системы и вызовов в режиме реального времени. Клиенты могут подписываться на события и получать уведомления через постоянное WebSocket-соединение.

Предварительная настройка

Перед началом работы необходимо выполнить следующие шаги.

1. Настроить API сервер шлюза

API → Сервер

При включении интерфейса событий вызовов автоматически открывается дополнительный фиксированный порт 3999, который используется для WebSocket-подключений.

Порт 3999 используется для WebSocket и не может быть изменён.

2. Получение токена авторизации

API ключ

API → Ключи

API аккаунт

Аккаунт должен иметь:

API → Аккаунты

Авторизация происходит по имени пользователя и паролю

curl -X POST http://<IP>:<port>/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"login":"<login>","password":"<password>"}'

Ответ:

{"status":"ok","version":"v1","payload":{"token":"Y3CupaVwSpDcmK83kxzSlymZhEIeib"}}


SIP абонент

Абонент должен иметь:

Абоненты → SIP абоненты

Авторизация происходит по номеру абонента и паролю

curl -X POST http://<IP>:<port>/api/v1/login \
  -H "Content-Type: application/json" \
  -d '{"login":"<number>","password":"<password>"}'

Ответ:

{"status":"ok","version":"v1","payload":{"token":"UjovsML3mIAzIs66zevqnQGElCjwrU"}}


Типы токенов

ТипГде используется
Токен API КлючаСобытия вызова
Токен абонентаСобытия вызова
Токен API аккаунтаСобытия вызова и системы (при включенном доступе)

Токены API аккаунта и SIP-абонента истекают через 20 минут неактивности. API ключ не имеет ограничения по времени действия.

Подключение к WebSocket

Для открытия WebSocket-соединения нужен токен полученный одним из способов, после этого посредством инструментов взаимодействия с WebSocket-серверами (например, wscat) нужно подключиться к серверу

События вызова (фиксированный порт 3999):

wscat -c "ws://<ip>:3999/websocket" -H "Authorization: Bearer <token>"

События системы:

wscat -c "ws://<ip>:<system_port>/websocket" -H "Authorization: Bearer <token>"

После успешного подключения сервер отправляет сообщение:

Connected

Порт на котором открывается WebSocket-соединение для событий вызова имеет значение по умолчанию 3999 и он не изменяется, для событий системы порт настраивается в WEB-интерфейсе.

Подписки

Ограничение

Формат запроса

{
  "action": "subscribe | unsubscribe | list",
  "type": 0 | 1,
  "subtype": 1,
  "data": "string"
}


Подписки существуют только в рамках WebSocket-соединения. После разрыва соединения подписки очищаются.

Параметры

ПолеТипОписание
actionstringДействие
typeintТип события
subtypeintПодтип события
datastringНомер абонента (для событий вызова)

Типы событий

Системные события (type = 0)

subtypeОписание
0Запуск ПО
1Авария
2Все

События вызовов (type = 1)

subtypeОписание
0Входящий вызов
1Исходящий вызов
2Ответ
3Завершение вызова
4Ошибка вызова
5DTMF
6Все

Запросы и ответы

Подписка

Запрос:

{
  "action":"subscribe",
  "type":1,
  "subtype":1,
  "data":"3005"
}

Успешный ответ:

{
  "version": "v1",
  "status": "ok",
  "payload": {
    "subID": 1
  }
}

Отписка

Запрос:

{
  "action":"unsubscribe",
  "type":1,
  "subtype":1,
  "data":"3005"
}

Успешный ответ:

{
  "version": "v1",
  "status": "ok",
  "payload": {
    "subID": 0
  }
}

subID:

Получение списка подписок

Запрос:

{
  "action": "list"
}

Ответ:

{
  "version": "v1",
  "status": "ok",
  "payload": {
    "subscriptions": [
      {
        "subID": 2,
        "type": 1,
        "subtype": 1,
        "subscriber": "admin",
        "data": "3005"
      },
       {
        "subID": 1,
        "type": 1,
        "subtype": 1,
        "subscriber": "admin", 
        "data": "3000"
      } 
    ]
  }
}

События

Формат события:

{
  "version": "v1",
  "action": "event",
  "payload": {}
}

Пример: авария

{
  "version": "v1",
  "action": "event",
  "payload": {
    "type": 0,
    "subtype": 1,
    "description": "13/04/26 15:30:31. state CRITICAL ALERT. E1 stream #01 signal loss"
  }
}

Пример: исходящий вызов

{
  "version": "v1",
  "action": "event",
  "payload": {
    "type": 1,
    "subtype": 1,
    "digit": 64,
    "cld": "3000",
    "clg": "3005"
  }
}

Обработка ошибок

{
  "version": "v1",
  "status": "error",
  "payload": {
    "code": 401,
    "message": "Unauthorized"
  }
}

Основные коды ошибок

Ошибки API:

204No Content
215Invalid input
217Not found
219Failed to parse json object
220Subscription/unsubscription process error
223Invalid format data
225Invalid data only digit

Ошибки протокола:

КодОписание
401Unauthorized
404Not Found
405Method Not Allowed

Жизненный цикл соединения