Introduction
Introduction
The TrueConf Bridge service is included with TrueConf Server. It enables API operations with chats over HTTP and WebSocket protocols and uses TCP port 4309.
To work with chat APIs, you must first:
Obtain an identification token using an HTTP request.
Connect to TrueConf Server using the WebSocket protocol.
Authorize the connection using an identification token and an auth request.
Before sending messages via WebSocket, the auth command must be executed. Otherwise, the server will return an error with code 200.
Bot deployment scheme
It is recommended to run bots on a separate TrueConf Server and connect it to the main server using the federation mechanism:
This scheme allows you to:
isolate bot credentials — bot accounts, OAuth 2.0 applications, and their associated secrets are hosted on a secondary server. Meanwhile, the primary server can maintain authorization only through NTLM, Kerberos, or MFA;
deploy bots in a secure perimeter (CSPD) — bots and their invoked local scripts can operate within a secure perimeter, even if the main server with users is located in an external network (DMZ). Interaction between servers is facilitated through federation;
use bot-supported password authentication — if NTLM is used on the main server, bot accounts can be created on a dedicated server where they will authenticate using a username and password. Bots interact with users of the main server through federation, so it is not necessary to create OAuth 2.0 applications for them on the main server;
scale the bot infrastructure — WebSocket connections for bots are established with a dedicated server and are counted against its own limit, which can support up to 128 simultaneous connections;
manage bot infrastructure independently — a dedicated server can be maintained, updated, and restarted separately. If necessary, it or the federated connection can be disabled without interrupting the main server operations with user accounts.
Secure connection: HTTPS and WSS
When the bot is in operation, sensitive data such as passwords, messages, and files are transmitted. Therefore, for remote connections, use HTTPS and WSS. Unencrypted HTTP and WebSocket connections are only permissible when connecting locally to TrueConf Bridge, for example, during development.
HTTP API is used for:
obtaining an identification token;
uploading files to a dedicated storage on the server.
The TrueConf Bridge service accepts unencrypted HTTP and WebSocket connections on port 4309. For secure connections, route the requests through the TrueConf web server implemented by the TrueConf Web Manager service. Ensure that this service is running beforehand.
Select an address depending on the connection method:
| Purpose | Local connection to TrueConf Bridge | Secure connection via 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/ |
The TrueConf Web Manager service proxies HTTPS requests to /bridge/api/ to the TrueConf Bridge service. By default, port 443 is used for HTTPS and WSS. If a different web port TrueConf Server is configured in the control panel , specify it in the connection address.
To learn how to configure HTTPS on TrueConf Server, refer to its documentation. You can obtain a free TLS certificate through the Let's Encrypt certificate authority—see the instructions for Linux and Windows.
Bot account
Only user accounts from the current TrueConf Server are supported for authentication. User accounts from other federated servers, as well as guest accounts, are not supported. Accounts can be used in both Registry mode and LDAP mode.
Supported login formats:
simple login — the user's login on the current server, for example:
userorjohn;specifying the TrueConf server — for example:
user@video.example.com;with the LDAP domain specified — for example:
department.mycompany\\john;specifying the server and LDAP domain — for example:
department.mycompany\\john@server.loc;
Identification token
Identification token is required for WebSocket connection authorization. The token is obtained via an HTTP request to /bridge/api/client/v1/oauth/token following the OAuth 2.0 standard. The server address depends on the connection method.
Token request
To obtain an identification token, use a supported account and execute a POST request:
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"
}| Parameter | Description |
|---|---|
| client_id | Constant string "chat_bot" |
| grant_type | Constant string "password" |
| username | User (bot) login |
| password | User (bot) password |
Success (201 Created)
In case of successful authorization, the HTTP server will respond with code 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
}| Parameter | Description |
|---|---|
| access_token | Identification token used for WebSocket connection authorization. |
| token_type | Constant string "JWT". |
| expires_at | The token's lifespan is one month from the time of creation. After this period, re-authorization will be required. |
For more details on the structure of the response body (payload), see the section OAuthTokenSuccessResponse.
Error (400 Bad Request)
In case of an authorization error, the HTTP server will respond with the code 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"
}| Parameter | Description |
|---|---|
| error | Value from OAUTH_ERROR enumeration. |
| error_description | Human-readable text for authorization error. |
Bot authorization using an OAuth application 5.5.3+
This method should be used if login and password authentication is disabled on the entire server or for the zone from which the bot connects. For instance, if only NTLM, Kerberos, or MFA (AD FS, Keycloak, Blitz, etc.) authentication is available. In such a configuration, obtaining an authentication token in the standard way is not possible, so OAuth 2.0 must be used to connect the bot.
To log in, use a supported account.
To configure bot connection:
- The administrator creates an OAuth 2.0 application in the API → OAuth2 section of the TrueConf Server control panel.
- The bot receives an access token for the TrueConf Server API API using the OAuth 2.0 standard, employing the Resource Owner Password Credentials method.
- The bot exchanges the access token for an identification token (JWT) required for authorizing the WebSocket connection.
To obtain an OAuth 2.0 access token, the application must be granted the version:read permission. Without it, the server will reject the request with an invalidScope error.
Stage 1. Obtaining a TrueConf Server API token
Make a POST request to /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"
}| Parameter | Description |
|---|---|
| client_id | OAuth 2.0 application ID created in the API → OAuth2 section of the control panel |
| grant_type | Constant string "password" |
| username | User (bot) login |
| password | User (bot) password |
Upon successful authorization, the server will return a JSON with the access token:
{
"access_token": "NTLIYTQWODUTNMFJMC0ZNTQ1LWFIZDCTN2UXZJIWZWIYNTY5",
"expires_in": 3600,
"refresh_token": "ZTBHYTKYODITNJC3YI01OTM3LTG3NJUTYZG1N2IYNDQ0MDC0",
"scope": "version:read",
"token_type": "bearer",
"user_id": "bot"
}| Parameter | Description |
|---|---|
| access_token | Token TrueConf Server API used at step 2 |
| expires_in | Token lifetime in seconds (1 hour) |
| refresh_token | Refresh token |
| scope | The token scope defined by the OAuth 2.0 application permissions (version:read) |
| token_type | Constant string "bearer" |
| user_id | User (bot) login for whom the token is issued |
Stage 2. Obtain authorization_code
Make a POST request to /bridge/api/client/v1/auth/web_rest_api_token, passing the token obtained in Step 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"
}| Parameter | Description |
|---|---|
| client_id | User (bot) login |
| token | The token TrueConf Server API obtained at step 1 |
If the request is successful, the server will return a JSON with the authorization code:
{
"authorization_code": "04934068530254b43fd12b932e713f518e6776dc",
"expires_in": 1790696252969
}| Parameter | Description |
|---|---|
| authorization_code | Authorization code used in step 3 |
| expires_in | Expiration time of the code — Unix time in milliseconds |
Stage 3. Obtaining the identification token
Execute a POST request to the /bridge/api/client/v1/auth/token endpoint:
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"
}| Parameter | Description |
|---|---|
| client_id | User (bot) login |
| grant_type | Constant string "authorization_code" |
| code | Authorization code obtained at step 2 |
In case of a successful request, the server will return a JSON with an identification token:
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "JWT",
"expires_in": 1793284714098
}| Parameter | Description |
|---|---|
| access_token | Identification token (JWT) used for WebSocket connection authorization. |
| token_type | Constant string "JWT". |
| expires_in | The expiration moment of the token is Unix time in milliseconds. The token's lifespan is one month from the moment of creation. |
The obtained identification token is used to authorize the WebSocket connection in the same way as the token obtained via the request above.
In case of an authorization error, the server may return a response with code 401 (invalid credentials or application ID) or 400 with an invalidScope error — please ensure that the OAuth 2.0 application has the version:read permission enabled.
WebSocket connection
After obtaining the identification token, you need to establish a connection with the WebSocket server and execute the auth authorization command.
Starting from version TrueConf Server 5.5.3, the number of simultaneous WebSocket connections is limited to 128. This means that you can run up to 128 bots using the WebSocket protocol on a single server.
Starting from version TrueConf Server 5.5.4, a single JWT token can be used in multiple WebSocket connections.
Connecting to the server
To connect to the server, establish a WebSocket connection at the path /websocket/chat_bot/. The full address depends on the selected connection method.
The server supports the json.v1 subprotocol, which is transmitted in the Sec-WebSocket-Protocol header. If the header is not specified, json.v1 is used by default.
Connection Authorization
Request:
{
"type": 1,
"id": 1,
"method": "auth",
"payload": {
"token": "someToken",
"tokenType" : "JWT",
"receiveUnread": false,
"receiveSystemMessageEnvelopes": true
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST |
| id | uint32 | Yes | Unique request identifier. An incremental value assigned by the sender, required in each request for subsequent association with the response. Read more here. |
| method | string | Yes | Type of command sent, default is auth |
| token | string | Yes | Authorization token obtained via an HTTP request |
| tokenType | string | Yes | By default, JWT |
| receiveUnread | boolean | No | A parameter responsible for retrieving unread messages when the bot was not connected to the server. Messages are returned one by one, from oldest to newest. The maximum number of messages retrieved is 1000. The default is false. |
| receiveSystemMessageEnvelopes | boolean | No | 5.5.3+ The parameter responsible for receiving system messages. Default is true. |
Response:
{
"type": 2,
"id": 1,
"payload": {
"userId": "someTrueConfUserId@someTrueConfServerName/someHash"
}
}| Parameter | Type | Mandatory | Description |
|---|---|---|---|
| type | uint32 | Yes | Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE |
| id | uint32 | Yes | An identifier matching the number sent in the original request, used to link the request and response. |
| userId | string | Yes | TrueConf ID of the authorized bot (server user) |
In the event of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the corresponding section of the documentation.