3.411.0 Приложение Ц Подписки на события вызовов и системы через API

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

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

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

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

• Убедиться, что API сервер включен;
• Настроить интерфейсы событий "Вызовы" и "Система":
  • Выбрать сетевой интерфейс;
  • Указать порт.
• При необходимости включить TLS. В этом случае запросы будут выполняться по протоколу HTTPS.

API → Сервер

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-абонент

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

• Включенный доступ к API;
• Заданный пароль.

Абоненты → 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"}}

Типы токенов

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

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

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

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

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

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

Connected

Подписки

Ограничение:

• Максимальное количество подписок – 4096;
• Дубликаты запрещены (проверяются сервером);
• Подписки событий системы и вызовов должны использовать разные WebSocket-соединения.

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

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

• unsubscribe выполняется с теми же параметрами, что и subscribe.

Параметры

Типы событий

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

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

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

Подписка

Запрос:

{
  "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:

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

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

При разрыве соединения клиент должен выполнить переподключение. После переподключения необходимо повторно создать все подписки.