Connection and Authorization

Connecting and Authorization

Introduction

The TrueConf Server package 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 authenticate the connection using an identity token and an auth request.

If you start sending messages over a WebSocket without executing the auth command, any message will receive a response with error 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.

Access Token

Identification Token is required for authorizing a WebSocket connection. The token is obtained via an HTTP request to the address /bridge/api/client/v1/oauth/token following the OAuth 2.0 standard. However, the TrueConf Bridge service does not accept HTTPS requests. To learn how to obtain a token using an encrypted connection (HTTPS), read below.

Request for Token Retrieval

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 login (see here)
password	User password

Success (201 Created)

In the case of successful authentication, 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 has a lifespan of one month from the time of generation. After this period, reauthorization will be 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 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.

Read more about the returned 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. To use HTTPS, you need to send requests to the TrueConf web server, which is implemented by the TrueConf Web Manager service. The TrueConf Web Manager service proxies all HTTPS requests received at the /bridge/api/ address to the TrueConf Bridge service.

Thus, if it is necessary to use the HTTPS protocol, requests can be sent to port 443 or another port specified in the control panel, after ensuring that the 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.

Starting from version TrueConf Server 5.5.3, the number of simultaneous WebSocket connections is limited to 128. This means you can run up to 128 bots on a single server via the WebSocket protocol.

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

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.

Authorization of connection

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	The parameter responsible for retrieving unread messages when the bot was offline. Messages are returned one by one, from oldest to newest. The maximum number of messages that can be retrieved is `1000`. The default value 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@someTrueConfServeName/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.