Введение

Труконф02.10.2026Около 13 мин

Введение

В составе TrueConf Server поставляется служба TrueConf Bridge. Она обеспечивает работу API с чатами по протоколам HTTP и WebSocket и использует TCP-порт 4309.

Для работы с API чатов необходимо предварительно:

Получить идентификационный токен с помощью HTTP-запроса.
Подключиться к TrueConf Server по протоколу WebSocket.
Авторизовать подключение с помощью идентификационного токена и запроса auth.

Перед отправкой сообщений по WebSocket необходимо выполнить команду auth. В противном случае сервер будет возвращать ошибку с кодом 200.

Схема развёртывания ботов

Рекомендуется запускать ботов на отдельном TrueConf Server и связывать его с основным сервером посредством механизма федерации:

/docs/chatbot-connector/media/bots-deployed-scheme/ru.svg

Такая схема позволяет:

изолировать учётные данные ботов — учётные записи ботов, OAuth 2.0-приложения и связанные с ними секреты размещаются на второстепенном сервере. На основном сервере при этом можно сохранить авторизацию только по NTLM, Kerberos или MFA;
разместить ботов в защищённом контуре (КСПД) — боты и вызываемые ими локальные скрипты могут работать внутри защищённого контура, даже если основной сервер с пользователями находится во внешней сети (DMZ). Взаимодействие между серверами обеспечивается посредством федерации;
использовать поддерживаемую ботами парольную авторизацию — если на основном сервере используется NTLM, учётные записи ботов можно создать на выделенном сервере, где они будут авторизоваться по логину и паролю. С пользователями основного сервера боты взаимодействуют через федерацию, поэтому создавать для них OAuth 2.0-приложения на основном сервере не требуется;
масштабировать инфраструктуру ботов — WebSocket-соединения ботов устанавливаются с выделенным сервером и учитываются в его собственном лимите, составляющем до 128 одновременных соединений;
управлять инфраструктурой ботов независимо — выделенный сервер можно отдельно обслуживать, обновлять и перезапускать. При необходимости его или федеративное соединение можно отключить, не прерывая основную работу сервера с учётными записями пользователей.

Защищённое подключение: HTTPS и WSS

При работе бота передаются чувствительные данные: пароли, сообщения и файлы. Поэтому для удалённого подключения используйте HTTPS и WSS. Незашифрованные HTTP- и WebSocket-соединения допустимы только при локальном подключении к TrueConf Bridge, например во время разработки.

HTTP API используется для:

получения идентификационного токена;
загрузки файла в специальное хранилище на сервере.

Служба TrueConf Bridge принимает незашифрованные HTTP- и WebSocket-соединения на порту 4309. Для защищённого подключения направляйте запросы через веб-сервер TrueConf, реализуемый службой TrueConf Web Manager. Предварительно убедитесь, что эта служба запущена.

Выберите адрес в зависимости от способа подключения:

Назначение	Локальное подключение к TrueConf Bridge	Защищённое подключение через TrueConf Web Manager
HTTP API	`http://localhost:4309/bridge/api/`	`https://bot.example.net/bridge/api/`
WebSocket	`ws://localhost:4309/websocket/chat_bot/`	`wss://bot.example.net/websocket/chat_bot/`

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

О том, как настроить HTTPS на TrueConf Server, читайте в его документации. Получить бесплатный TLS-сертификат можно с помощью центра сертификации Let's Encrypt — см. инструкции для Linux и Windows.

Учётная запись бота

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

Поддерживаемые форматы логина:

простой логин — логин пользователя текущего сервера, например: user или john;
с указанием сервера TrueConf — например: user@video.example.com;
с указанием LDAP-домена — например: department.mycompany\\john;
с указанием сервера и LDAP-домена — например: department.mycompany\\john@server.loc;

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

Идентификационный токен необходим для авторизации WebSocket-соединения. Токен получают с помощью HTTP-запроса к /bridge/api/client/v1/oauth/token по стандарту OAuth 2.0. Адрес сервера зависит от способа подключения.

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

Для получения идентификационного токена используйте поддерживаемую учётную запись и выполните 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	Время жизни токена составляет один месяц с момента формирования. По истечении этого времени потребуется повторная авторизация.

Подробнее о структуре тела ответа (payload) см. в разделе OAuthTokenSuccessResponse.

Ошибка (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	Человекочитаемый текст ошибки авторизации.

Авторизация бота с помощью OAuth-приложения 5.5.3+

Данный способ необходимо использовать, если авторизация по логину и паролю отключена на всём сервере или для зоны, из которой подключается бот. Например, если доступна только авторизация по NTLM, Kerberos или с использованием MFA (AD FS, Keycloak, Blitz и т.д.). При такой конфигурации получить идентификационный токен стандартным способом невозможно, поэтому для подключения бота необходимо использовать OAuth 2.0.

Для авторизации используйте поддерживаемую учётную запись.

Чтобы настроить подключение бота:

Администратор создаёт OAuth 2.0-приложение в разделе API → OAuth2 панели управления TrueConf Server.
Бот получает токен доступа к TrueConf Server API API по стандарту OAuth 2.0, используя метод Resource Owner Password Credentials.
Бот обменивает токен доступа на идентификационный токен (JWT), необходимый для авторизации WebSocket-соединения.

Для получения токена доступа OAuth 2.0-приложению необходимо предоставить право version:read. Без него сервер отклонит запрос с ошибкой invalidScope.

Этап 1. Получение токена TrueConf Server API

Выполните POST-запрос на адрес /api/v4/oauth2/token:

POST /api/v4/oauth2/token HTTP/1.1
Host: video.example.net
Content-Type: application/json

{
    "client_id": "QuWJ9XWvT9otdy9RSAduGA",
    "grant_type": "password",
    "username": "bot",
    "password": "123tr"
}

Параметр	Описание
client_id	Идентификатор OAuth 2.0-приложения, созданного в разделе API → OAuth2 панели управления
grant_type	Константная строка `"password"`
username	Логин пользователя (бота)
password	Пароль пользователя (бота)

В случае успешной авторизации сервер вернёт JSON с токеном доступа:

{
    "access_token": "NTLIYTQWODUTNMFJMC0ZNTQ1LWFIZDCTN2UXZJIWZWIYNTY5",
    "expires_in": 3600,
    "refresh_token": "ZTBHYTKYODITNJC3YI01OTM3LTG3NJUTYZG1N2IYNDQ0MDC0",
    "scope": "version:read",
    "token_type": "bearer",
    "user_id": "bot"
}

Параметр	Описание
access_token	Токен TrueConf Server API, используемый на этапе 2
expires_in	Время жизни токена в секундах (1 час)
refresh_token	Токен продления доступа
scope	Область видимости токена, задаваемая правами OAuth 2.0-приложения (`version:read`)
token_type	Константная строка `"bearer"`
user_id	Логин пользователя (бота), от имени которого выдан токен

Этап 2. Получение `authorization_code`

Выполните POST-запрос на адрес /bridge/api/client/v1/auth/web_rest_api_token, передав токен, полученный на этапе 1 :

POST /bridge/api/client/v1/auth/web_rest_api_token HTTP/1.1
Host: video.example.net
Content-Type: application/json

{
    "client_id": "bot",
    "token": "NTLIYTQWODUTNMFJMC0ZNTQ1LWFIZDCTN2UXZJIWZWIYNTY5"
}

Параметр	Описание
client_id	Логин пользователя (бота)
token	Токен TrueConf Server API, полученный на этапе 1

В случае успешного запроса сервер вернёт JSON с кодом авторизации:

{
    "authorization_code": "04934068530254b43fd12b932e713f518e6776dc",
    "expires_in": 1790696252969
}

Параметр	Описание
authorization_code	Код авторизации, используемый на этапе 3
expires_in	Момент истечения кода — Unix-время в миллисекундах

Этап 3. Получение идентификационного токена

Выполните POST-запрос на адрес /bridge/api/client/v1/auth/token:

POST /bridge/api/client/v1/auth/token HTTP/1.1
Host: video.example.net
Content-Type: application/json

{
    "client_id": "bot",
    "grant_type": "authorization_code",
    "code": "04934068530254b43fd12b932e713f518e6776dc"
}

Параметр	Описание
client_id	Логин пользователя (бота)
grant_type	Константная строка `"authorization_code"`
code	Код авторизации, полученный на этапе 2

В случае успешного запроса сервер вернёт JSON с идентификационным токеном:

{
    "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "JWT",
    "expires_in": 1793284714098
}

Параметр	Описание
access_token	Идентификационный токен (JWT), используемый для авторизации WebSocket-соединения.
token_type	Константная строка `"JWT"`.
expires_in	Момент истечения токена — Unix-время в миллисекундах. Время жизни токена составляет один месяц с момента формирования.

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

В случае ошибки авторизации сервер может вернуть ответ с кодом 401 (неверные учётные данные или идентификатор приложения) либо 400 с ошибкой invalidScope — проверьте, что у OAuth 2.0-приложения отмечено право version:read.

WebSocket-соединение

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

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

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

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

Для подключения к серверу установите WebSocket-соединение по пути /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@someTrueConfServerName/someHash"
  }
}

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

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