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.

To connect to the server, you need to establish a WebSocket connection at the following address: /weboscket/chat_bot/:

From localhost directly to the TrueConf Bridge service (port 4309) using WebSocket (ws):

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

From outside to the TrueConf Web service (port 443 or other) using WebSocket Secure (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.

# 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

# Successful authorization

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 authorizing a WebSocket connection.
token_type A constant string "JWT".
expires_in The token's lifespan is one year from the time of its creation. After this period, re-authorization will be necessary.

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

# Authorization Error

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 Authorization

After obtaining the identification token, you need to authorize your WebSocket connection.

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.

# Sending messages without authorization

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

← Basic Message Format →