# Подключение и авторизация

В составе TrueConf Server поставляется служба TrueConf Bridge. Данная служба содержит HTTP и WebSocket сервер, используемый для реализации функционала API по работе с чатами. Служба TrueConf Bridge использует TCP порт 4309.

Для отправки запросов (команд) API необходимо предварительно подключиться к WebSocket-серверу и авторизовать подключение с помощью идентификационного токена и запроса auth.

Для подключения к серверу необходимо установить WebSocket-соединение по следующему адресу /weboscket/chat_bot/:

C localhost напрямую к службе TrueConf Bridge (порт 4309) c использованием WebSocket (ws):

ws://localhost:4309/websocket/chat_bot/

Извне к службе TrueConf Web (порт 443 или иной) с использованием WebSocket Secure (wss):

wss://video.example.net/websocket/chat_bot/

Сервер поддерживает подпротокол json.v1, который передаётся в заголовке Sec-WebSocket-Protocol. Если заголовок не указан, то json.v1 будет использоваться по умолчанию.

# Поддерживаемые учетные записи

Поддерживаются учетные записи пользователей только текущего сервера TrueConf. Авторизация посредством учетных записей серверов подключенных по федерации или гостевыми аккаунтами не поддерживается. Поддерживаются учетные записи как в режиме Registry так и в режиме LDAP.

# Идентификационный токен

Идентификационный токен необходим для авторизации веб-сокет соединения. Получение токена происходит через HTTP запрос на адрес /bridge/api/client/v1/oauth/token по стандарту OAuth 2.0 (opens new window). При этом, служба TrueConf Bridge не принимает HTTPS запросы. О том, как получить токен используя зашифрованное соединение (HTTPS) читайте ниже.

# Запрос на получение токена

Для получения идентификационного токена выполните POST-запрос:

POST /bridge/api/client/v1/oauth/token HTTP/1.1
Host: localhost:4309
Content-Type: application/json
Content-Length: 114

{
    "client_id": "chat_bot",
    "grant_type": "password",
    "username": "user",
    "password": "qwerty"
}
Параметр Описание
client_id Константная строка "chat_bot"
grant_type Константная строка "password"
username Логин пользователя (см. тут)
password Пароль пользователя

# Успешная авторизация

В случае успешной авторизации, HTTP-сервер ответит кодом 201 Created:

HTTP/1.1 201 Created
Content-Type:application/json
Access-Control-Allow-Origin:*
Date:Mon, 09 Sep 2024 22:42:50 GMT

{
    "access_token": "eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ",
    "token_type": "JWE",
    "expires_in": 31536000
}
Параметр Описание
access_token Идентификационный токен, используемый для авторизации WebSocket-соединения.
token_type Константная строка "JWE".
expires_in Время жизни токена в секундах с момента формирования токена составляет один год. По истечении этого времени потребуется повторная авторизация.

Подробнее про возвращаемую структуру в теле ответа (payload) читайте тут.

# Ошибка авторизации

В случае ошибки авторизации, HTTP-сервер ответит кодом 400 Bad Request:

HTTP/1.1 400 Bad Request
Content-Type:application/json
Access-Control-Allow-Origin:*
Date: Mon, 09 Sep 2024 22:42:50 GMT

{
"error": "invalid_grant",
"error_description": "Invalid username or password"
}
Параметр Описание
error Значение из перечисления OAUTH_ERROR.
error_description Человекочитаемый текст ошибки авторизации.

Подробнее про возвращаемую структуру в теле ответа (payload) читайте тут.

# Использование HTTPS

HTTP-протокол используется для:

  • получения идентификационного токена;

  • загрузки файла в специальное хранилище на сервере.

При этом служба TrueConf Bridge не поддерживает протокол HTTPS. Если требуется использовать HTTPS, необходимо направлять запросы на веб-сервер TrueConf, реализуемый службой TrueConf Web Manager. Служба TrueConf Web Manager проксирует все HTTPS-запросы, поступающие по адресу /bridge/api/, в службу TrueConf Bridge.

Таким образом, при необходимости использовать протокол HTTPS, запросы можно отправлять на порт 443 или иной порт, указанный в панели управления TrueConf Server, предварительно убедившись, что служба TrueConf Web Manager запущена:

https://video.example.net/bridge/api/client/v1/oauth/token

# Авторизация WebSocket соединения

После получения идентификационного токена, вам необходимо авторизовать ваше WebSocket подключение.

Запрос:

{
  "type": 1,
  "id": 1,
  "method": "auth",
  "payload": {
    "token": "someToken",
    "tokenType" : "JWE"
  }
}
Параметр Тип Обяз. Описание
type uint32 Да Тип сообщения (по умолчанию 1). Соответствует MESSAGE_TYPE.REQUEST
id uint32 Да Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут
method string Да Тип отправляемой команды, по умолчанию auth
token string Да Авторизационный токен, полученный посредством HTTP-запроса
tokenType string Да По умолчанию JWE

Ответ:

{
  "type": 2,
  "id": 1,
  "payload": {
    "userId": "someTrueConfUserId@someTrueConfServeName/someHash"
  }
}
Параметр Тип Обяз. Описание
type uint32 Да Тип сообщения (по умолчанию 2). Соответствует MESSAGE_TYPE.RESPONSE
id uint32 Да Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа
userId string Да TrueConf ID авторизованного бота (пользователя сервера)

В случае возникновения ошибки возвращается сообщение, содержащее параметр errorCode. Список возможных значений доступен в соответствующем разделе документации.

# Отправка сообщений без авторизации

В том случае, если не выполнив команды auth начать отправлять сообщения по веб-сокету, на любое сообщение будет приходить ошибка c кодом 200.

Обновлено: 19.07.2025