TrueConf

# Connection and Authorization

TrueConf Server includes the TrueConf Bridge service. This service contains an HTTP and WebSocket server used to implement API functionality for chat operations. The TrueConf Bridge service uses TCP port 4309.

To send API requests (commands), you must first connect to the WebSocket server and authorize the connection using an access token and the auth request.

If you start sending messages over a WebSocket without executing the auth command, any message will receive an error with code 200.

# Supported Accounts

Only user accounts from the current TrueConf server are supported. Authorization through accounts from federated servers or guest accounts is not supported. Accounts are supported in both Registry and LDAP modes.

# Identification token

Identification token is required for authorizing a WebSocket connection. The token is obtained via an HTTP request to the /bridge/api/client/v1/oauth/token endpoint following the OAuth 2.0 (opens new window) standard. Note that the TrueConf Bridge service does not accept HTTPS requests. For information on how to obtain a token using an encrypted connection (HTTPS), see below.

# Token request

To obtain an identification token, 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's login (see here)
password User's password

# Success (201 Created)

If the authorization is successful, the HTTP server will respond with the 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_in": 31536000
}
Parameter Description
access_token An identification token used for WebSocket connection authorization.
token_type A constant string "JWT".
expires_in The token's lifespan is one month from issuance. After this period, re-authorization is required.

Read more about the returned structure in the response body (payload) here.

# Error (400 Bad Request)

In case of an authorization error, the HTTP server will respond with a 400 Bad Request code:

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 the OAUTH_ERROR enumeration.
error_description Human-readable text of the authorization error.

Read more about the return structure in the response body (payload) here.

# Using HTTPS

HTTP protocol is used for:

  • obtaining an identification token;

  • uploading files to a dedicated storage on the server.

The TrueConf Bridge service does not support the HTTPS protocol. If you need to use HTTPS, requests must be directed to the TrueConf web server implemented by the TrueConf Web Manager service. The TrueConf Web Manager service proxies all HTTPS requests received at the /bridge/api/ endpoint to the TrueConf Bridge service.

Thus, when it is necessary to use the HTTPS protocol, requests can be sent to port 443 or another port, as specified in the control panel of TrueConf Server, after ensuring that the TrueConf Web Manager service is running:

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

# WebSocket connection

After obtaining the identification token, you need to establish a connection with the WebSocket server and execute the auth authorization command.

# Connecting to the server

To connect to the server, establish a WebSocket connection at /weboscket/chat_bot/:

From a local machine to the TrueConf Bridge service (port 4309, protocol ws):

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

Via TrueConf Web (port 443 or another, protocol wss):

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

The server supports the json.v1 subprotocol, which is transmitted in the Sec-WebSocket-Protocol header. If the header is not specified, json.v1 will be used by default.

# Connection Authorization

Request:

{
  "type": 1,
  "id": 1,
  "method": "auth",
  "payload": {
    "token": "someToken",
    "tokenType" : "JWT",
    "receiveUnread": true
  }
}
Parameter Type Req. Description
type uint32 Yes Message type (default is 1). Corresponds to MESSAGE_TYPE.REQUEST
id uint32 Yes Unique request identifier. An incremented value assigned by the sender, mandatory in each request for subsequent binding to the response. More details can be found here
method string Yes Type of command being sent, default is auth
token string Yes Authorization token, obtained via HTTP request
tokenType string Yes Default is JWT
receiveUnread boolean No A parameter that enables the bot to receive unread messages accumulated while it was offline. Messages are returned one by one — from oldest to newest. The maximum number of messages that can be retrieved is 1000. Default value: false.

Answer:

{
  "type": 2,
  "id": 1,
  "payload": {
    "userId": "someTrueConfUserId@someTrueConfServeName/someHash"
  }
}
Parameter Type Required Description
type uint32 Yes Message type (default is 2). Corresponds to MESSAGE_TYPE.RESPONSE
id uint32 Yes Identifier matching the number sent in the original request, used to match the request and response
userId string Yes TrueConf ID of the authorized bot (server user)

In case of an error, a message containing the errorCode parameter is returned. A list of possible values is available in the relevant section of the documentation.

← Basic Message Format →