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

Труконф04.07.2026Около 7 мин

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

Введение

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

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

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

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

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

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

Идентификационный токен необходим для авторизации веб-сокет соединения. Получение токена происходит через HTTP запрос на адрес /bridge/api/client/v1/oauth/token по стандарту OAuth 2.0. При этом, служба 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	Пароль пользователя

Успех (201 Created)

В случае успешной авторизации, 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": "JWT",
    "expires_at": 1761121632
}

Параметр	Описание
access_token	Идентификационный токен, используемый для авторизации WebSocket-соединения.
token_type	Константная строка `"JWT"`.
expires_at	Время жизни токена составляет один месяц c момента формирования. По истечении этого времени потребуется повторная авторизация.

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

Ошибка (400 Bad Request)

В случае ошибки авторизации, 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-сервером и выполнить команду авторизации auth.

Начиная с версии TrueConf Server 5.5.3, количество одновременных веб-сокет соединений ограничено до 128. Это значит, что на одном сервере вы сможете запустить до 128 ботов через протокол WebSocket.

Начиная с версии TrueConf Server 5.5.4 вы можете использовать один JWT-токен в нескольких веб-сокет соединениях.

Подключение к серверу

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

С локальной машины к службе TrueConf Bridge (порт 4309, протокол ws):

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

Через TrueConf Web (порт 443 или другой, протокол wss):

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

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

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

Запрос:

{
  "type": 1,
  "id": 1,
  "method": "auth",
  "payload": {
    "token": "someToken",
    "tokenType" : "JWT",
    "receiveUnread": false,
    "receiveSystemMessageEnvelopes": true
  }
}

Параметр	Тип	Обяз.	Описание
type	uint32	Да	Тип сообщения (по умолчанию `1`). Соответствует MESSAGE_TYPE.REQUEST
id	uint32	Да	Уникальный идентификатор запроса. Инкрементируемое значение, назначаемое отправляющей стороной, обязательное в каждом запросе для последующего связывания с ответом. Подробнее читайте тут
method	string	Да	Тип отправляемой команды, по умолчанию `auth`
token	string	Да	Авторизационный токен, полученный посредством HTTP-запроса
tokenType	string	Да	По умолчанию `JWT`
receiveUnread	boolean	Нет	Параметр, отвечающий за получение непрочитанных сообщений, когда бот находился в оффлайне. Сообщения возвращаются по одному — от старых к новым. Максимальное количество получаемых сообщений — `1000`. По умолчанию — `false`.
receiveSystemMessageEnvelopes	boolean	Нет	5.5.3+ Параметр, отвечающий за получение системных сообщений. По умолчанию — `true`.

Ответ:

{
  "type": 2,
  "id": 1,
  "payload": {
    "userId": "someTrueConfUserId@someTrueConfServeName/someHash"
  }
}

Параметр	Тип	Обяз.	Описание
type	uint32	Да	Тип сообщения (по умолчанию `2`). Соответствует MESSAGE_TYPE.RESPONSE
id	uint32	Да	Идентификатор, совпадающий с числом, отправленным в исходном запросе, используемый для связывания запроса и ответа
userId	string	Да	TrueConf ID авторизованного бота (пользователя сервера)

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