Skip to content

Main Websocket

Jump to bottom
Benjamin Eder edited this page Dec 22, 2020 · 5 revisions

Main Websocket communication

Most business objects are send and received over a single web socket connection to the so called "main websocket".

Connection

You'll be able to connect to the websocket by opening a new websocket to wss://<BBB_WEB_APP_HOST>/html5client/sockjs/<RANDOM_DIGITS_3>/<RANDOM_ALPHANUMERIC_8>/websocket where <BBB_WEB_APP_HOST> is the host under which the BBB web app is running, <RANDOM_DIGITS_3> are three random digits and <RANDOM_ALPHANUMERIC_8> is a random string of alphanumeric characters of length 8.

Sending/receiving messages

The messages sent and received over the websocket are simple JSON-formatted text.

There are some exceptions to this rule:

  • The first message incoming over the onMessage callback of the websocket is always just a single o character signalling that the websocket is ready -> we need to send a connect message to finally finish the connecting procedure (see section connect message)
  • All incoming message except the first o message are prefixed with a (we simply trim that part from the rest of the message to get a JSON list with all messages: for example a[{...}, {...}, ...]

Send messages

When sending a message you need to add an id attribute to each sent JSON with a counter as value that is incremented on each sent message. So when looking at the connect message example you'll need to append an id attribute with 1 (for example) as value. Afterwards increment the counter by 1 for the next message.

Connect message

When receiving the first o message over the websocket we need to send a connect message of the following format to complete the connection procedure:

{
  "msg": "connect",
  "version": "1",
  "support": ["1", "pre2", "pre1"],
}

Afterwards we'll be able to receive messages over the websocket.

Subscriptions

The main websocket works using the publish-subscribe pattern, so before receiving anything you'll need to subscribe to the topics you want to receive updates for. The following message is used to subscribe to a topic:

{
  "msg": "sub",
  "id": <RANDOM_ALPHANUMERIC_17>,
  "name": <TOPIC_NAME>,
  "params": <PARAMETER_LIST>,
}

where <RANDOM_ALPHANUMERIC_17> is a string of length 17 filled with random alphanumeric characters, <TOPIC_NAME> is the name of the topic to subscribe to (for example chat, presentation, voice, ...) and <PARAMETER_LIST> is a list of JSON formats that are rarely used to modify the subscription (for example when subscribing to a private chat using the chat topic to subscribe to a specific chat group ID only).

After subscribing you'll receive the object associated with the given topic. For example subscribing to chat would send all chat-related messages (chat messages, ...) over the web socket.

Where to find the topics, message format?

Since this is just a short documentation on how to work with the main websocket, we won't list all messages and all topics. Instead you should use the Chrome development tools to read the websocket messages when using the official BBB web app. That way you'll see all the messages and topics the web app subscribes to and receives.

Alternatively you may take a look into the source code of the main websocket that is located under lib/src/connect/meeting/main_websocket.

Clone this wiki locally