Introduction

This guide describes how to work with the TrueConf Room API. Additionally, this documentation can be used to manage using WebSocket commands (for example, if you are using Linux and cannot use the .NET MAUI component).

When installing on Windows OS, the .NET MAUI component is added to the system to integrate TrueConf video conferencing into a corporate application. In this case, development requires using MS Visual Studio.

TrueConf Room is a software endpoint designed for meeting rooms and conference halls of any size. It can be installed on Windows or Linux-based PCs and offers a user-friendly management interface via a web interface or an app for Android smartphones and tablets. For more details, refer to the documentation for TrueConf Room.

is a software solution for developing corporate applications with integrated TrueConf video conferencing. It can be used to provide video communication up to 4K UltraHD for self-service terminals, video kiosks, ATMs, etc.

All commands, notifications, and their usage principles in this guide are provided under different API versions: v.1, v.2, etc. Newer APIs introduce new features, and some parameters may change or be added; support for outdated functions or notifications may also be discontinued. Therefore, it's important to know which version your TrueConf Room API supports to use the API correctly.

Which API version to use

The newer the version of TrueConf Room API, the later the API version it supports. Below is the compatibility table:

5.0	v.1, v.2
4.3	v.1

Comparison of Products

The table below describes the features of each solution:

Features	TrueConf Room		TrueConf VideoSDK
		Free	PRO	Free
Web interface for managing application settings	V	V	V	V
Fully functional web interface for video conferencing management	V	V
Access rights differentiation for administrators and users				V
Selecting interface elements to display on the main screen				V
Changing the background of the main application window				V
Branding: Changing the logo on the main screen				V
No "Free" label over the video from the camera and in conferences				V
API Availability	V	V	V	V
NDI Protocol: Sending video via NDI protocol				V
NDI Protocol: Receiving video via the NDI protocol				V
TrueConf Room Service	V	V
Supported OS	Microsoft Windows 7 SP1 and later

API Working Principle

The management interface is a single WebSocket through which messages are exchanged in JSON format.

Each request can include the requestId parameter for unique identification. If specified, the JSON response to the request will contain the same value; otherwise, it will be empty. This is necessary for correlating the request with its response.

The WebSocket address used during connection determines the API version in use. The required version is indicated by the value following /v. For example, ws://192.168.0.100:8765/v2 will use version 2; ws://192.168.0.100:8765/v1 will use version 1. If no version is specified, such as in ws://192.168.0.100:8765, version 1 will be used by default.

WebSocket port

How to obtain

To send commands and receive notifications, it is necessary to know the TCP port number used by TrueConf Room API when working with the WebSocket protocol. This port, like that of the built-in HTTP server, is assigned automatically and defaults to 8765. If this port is already in use by the operating system, the next available free port will be used.

To find out the WebSocket port:

1. Make sure that TrueConf Room API is running.

2. Perform a GET request of the following type:

http://room_ip:port/public/default/config.json

where:

• room_ip – the IP address of the device where it's running TrueConf Room API

• port – HTTP port of the web server TrueConf Room API

The IP and port are specified during the TrueConf Room API installation and are displayed on the main screen upon launch.

In our example, you need to make the following request:

http://10.140.2.142:88/public/default/config.json

The resulting JSON will contain two objects with port numbers for the HTTP server and WebSocket management, for example:

{
    "config": {
        "websocket": {
            "hostname": null,
            "port": 8765
        },
        "http": {
            "hostname": null,
            "port": 8766
        }
    }
}

This JSON file is recreated every time TrueConf Room API is launched or either of the two ports is updated. It can be found on the machine where TrueConf Room API is installed. To locate it, navigate to the path:

• C:\ProgramData\TrueConf\VideoSDK\web\default on Windows

• /opt/trueconf/[product_name]/var/lib/room/default/ on Linux

replace [product_name] with room in case of TrueConf Room and with videosdk in case of .

How to set

You can manually set the WebSocket port by running TrueConf Room API with the parameter --wsport, for example:

C:\Program Files\TrueConf\Room\TrueConfRoom.exe --wsport 568

If the key -t [name] was also used (to launch a copy of TrueConf Room API with its own settings), then:

1. In the main window of TrueConf Room API, the parameter cfg=[name] will be added to the web URL.

2. The ports will be stored in the same config.json file, but the path will change:

• C:\ProgramData\TrueConf\VideoSDK\web\[name] on Windows

• /opt/trueconf/[product_name]/var/lib/room/[name]/ on Linux

Testing requests in Postman

For preliminary testing of various features and notifications, it is convenient to use the free Postman utility. It is capable of working with WebSocket and additionally offers the following capabilities:

• A user-friendly interface for tracking request and response history;

• authorization in Postman cloud with the ability to sync requests on any user device;

• availability of applications for various operating systems, as well as a web version;

• saving the request list as files, etc.

For convenience, you can test everything in Postman first and then transfer it to the programming language code.

Below is an example showing the Postman window after authorization and sending several commands:

Example

Below is an example of an HTML page where clicking the "Call" button will initiate a call to a subscriber using their TrueConf ID specified in the text field.

Important. Before opening the page in the browser, make sure that:

1. TrueConf Room API already running locally.

2. Unprotected login is used to manage TrueConf Room API.

<!DOCTYPE html>
<html lang="en">
<script>
    let ws;
    let inputPeerId;
    let submitButton;
    let resultH4;

    window.addEventListener('load', () => {
        inputPeerId = window.document.getElementById('peerIdInput');
        submitButton = window.document.getElementById('submitButton');
        resultH4 = window.document.getElementById('resultH4');

        submitButton.addEventListener('click', ()=> {
            const peerId = inputPeerId.value;
            sendMsg({ method : "call", peerId });
        });

        init();
    })

    function init(){
        ws = new WebSocket("ws://localhost:8765/");
        ws.addEventListener('message', onMsg);
        ws.addEventListener('error', onError);
        ws.addEventListener('open', onOpen);
    }

    function sendMsg(msg) {
        ws.send(JSON.stringify(msg));
    }

    function onMsg(e) {
        const data = JSON.parse(e.data);

        // Processing: Commands responses
        switch (data.method) {
            case "auth": {
                data.result ? console.log('authorization done') : console.error('authorization error', data.error);

                sendMsg({
                    method: 'login',
                    login: "1@someserver.name",
                    password: "123"
                });
            } 
            break;
        }

        // Processing: Events
        switch (data.event) {
            case "conferenceCreated": {
                resultH4.innerHTML = "confID: " + data.confId;
            }
            break;
        }
    }

    function onError(e) {
        console.error(e);
    }

    function onOpen(e) {
        sendMsg({
            method: 'setUsedApiVersion',
            requestId: "",
            version: "1"
        });

        sendMsg({
            method: 'auth',
            type : "unsecured"
        });
    }
</script>
<body>

<h3>Calling from TrueConf Room to any user by ID</h3>
<input id="peerIdInput" type="text" name="peerId" />
<input id="submitButton" type="submit" value="call" />
<h4 id="resultH4"></h4>

</body>
</html>

Access Levels

Working with TrueConf Room API can be done with different levels of access: Administrator and User. The former has access to the full set of management methods, while the latter has limited access. A comparison of capabilities:

Team	Administrator	User
connectToServer	V	X
login	V	X
logout	V	X
connectToService	V	X
getHardwareKey	V	X
activateLicense	V	X
shutdown	V	X
rebootSystem	V	X
shutdownSystem	V	X
clearTokens	V	X
setLogo	V	X
getInfoWodgetsState	V	X
setDefaultLogo	V	X
getLogo	V	X
All other commands	V	V
All other notifications	V	V

Terminology

User IDs

• PeerId is a unique user identifier (TrueConf ID) in its short form. It does not include the server address or the instance identifier. Its use implies interaction with the current server to which TrueConf Room API is connected. For example, if TrueConf Room API is connected to the server current.server, using the identifier user1 will automatically convert it internally to user1@current.server.

• CallId is a unique identifier for the user (TrueConf ID) including the server address and excluding the instance. Example: user@some.server

• InstanceId is a unique identifier for a user (TrueConf ID) that includes the server address and instance. For example - user1@some.server/INSTANCE_ID. It is used for precise identification because the same user might be logged in on the same server but through different applications: user1@some.server/INSTANCE_ID1, user1@some.server/INSTANCE_ID2.

Automatic take the podium by VAD

In a group conference with a video selector, there can be an additional feature - Automatic podium access via VAD. VAD (voice activity detection) refers to the voice volume level. In this mode, each speaker automatically takes the podium until the allowed number of speakers is reached. When a speaker finishes talking, they leave the podium. In this mode, all commands related to the podium will be inactive. Additionally, methods for pinning participants to the podium become available.