TrueConf VideoSDK Guide

# Overview

This guide describes the API for both solutions: TrueConf VideoSDK and TrueConf Room

# Product comparison

The table below describes the features of each solution:

Features TrueConf Room TrueConf VideoSDK
Free PRO Free PRO
Web interface for managing app settings V V V V
Meeting management via web interface V V
Different access rights for administrators and users V V
Selection of UI widgets to be displayed on the main screen V V
Custom background for the main screen V V
Branding: your corporate logo on the main screen V V
No “Free” caption in self-view video and in conferences V V
Availability of API V V V V
NDI protocol: send video via NDI V V
NDI protocol: receive video via NDI V V
TrueConf Room Service V V
Supported operating systems Microsoft Windows 7 SP1 or above
Debian 10 / 11
Ubuntu 20.04 / 22.04
Astra Linux SE 1.6 / 1.7
Raspberry Pi OS 11

# Introduction

The management interface represents a single WebSocket that enables message exchange in the JSON format.

In each request for its unambiguous identification, the parameter requestId can be specified. If it is set, then the JSON response to the request will contain the same value, otherwise it will be empty. Needed to match the request and its response.

# WebSocket port

# How to obtain

To send commands and receive notifications, you need to know the TCP port number used by VideoSDK/Room when working with the WebSocket protocol. This port, like for the built-in HTTP server, is automatically set to 8765 by default. If this port is already in use by the operating system, the nearest available port will be used instead.

To find the WebSocket port:

  1. Make sure that VideoSDK/Room is launched.

  2. Translate: Perform a GET request of the following format:

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

Where:

  • room_ip - device's IP address where VideoSDK/Room is running.

  • port- HTTP port of the web server VideoSDK/Room

The IP and port are set during VideoSDK/Room installation and displayed on the main screen after launch:

/videosdk/media/home_screen/en.png

In our example, we need to execute the following query:

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

msgid: В полученном JSON будет два объекта, содержащие номера портов для HTTP сервера и для управления по WebSocket, например:

translation: The received JSON will contain two objects, containing the ports numbers for the HTTP server and for WebSocket management, for example:

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

This JSON file is recreated every time VideoSDK/Room is launched or either of its two ports is updated. It can be found on a machine with VideoSDK/Room installed. To access it, follow this path:

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

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

Where [product_name] must be replaced with room in case of TrueConf Room and with videosdk in case of TrueConf VideoSDK.

# How to set up

The WebSocket port can be set manually by launching VideoSDK/Room with the command-line parameter --wsport, for example:

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

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

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

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

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

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

# Example

The example html-page below shows how clicking the "Call" button will initiate a call to a subscriber using their TrueConf ID indicated in the text field.

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

  1. VideoSDK/Room has already been started locally.

  2. Unsecured authorization is used to control VideoSDK/Room.

<!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 VideoSDK/Room can be done at different access levels: Administrator and User. The first has access to the entire set of management methods, the second is restricted. Comparison of abilities:

Command 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 - unique user identifier (TrueConf ID) in short form. Does not contain server address and ID instance. When used, it is assumed to be working with the current server to which VideoSDK/Room is connected. For example, if VideoSDK/Room is connected to the current.server, when using the user1 identifier, it will be automatically converted inside to user1@current.server.

  • CallId - unique identifier of the user (TrueConf ID) with server address and without an instance. Example - user@some.server

  • InstanceId - a unique identifier of a user (TrueConf ID) with a server address and an instance. Example - user1@some.server/INSTANCE_ID. It is used for unambiguous identification as, for example, the same user can be authorized on one server but from different applications: user1@some.server/INSTANCE_ID1, user1@some.server/INSTANCE_ID2.