Have you explored the newest version of the OpenTok platform? Check out OpenTok 2.0, built on top of WebRTC. Learn more

ConnectionEvent class

The Session object dispatches a Connection event when a connection is created or destroyed.

ConnectionEvent properties

The ConnectionEvent object has the following properties::

connections (Array[Connection]) — An array of Connection objects for the connections that were created or deleted. You can compare the connectionId property to that of the connection property of the Session object to see if a connection refers to the local web page.

reason (String) — For a connectionDestroyed event, a description of why the connection ended. This property can have two values:

  • "clientDisconnected" — A client disconnected from the session by calling the disconnect() method of the Session object or by closing the browser. (See Session.disconnect().)
  • "forceDisconnected" — A moderator has disconnected the client from the session, by calling the forceDisconnect() method of the Session object. (See Session.forceDisconnect().)
  • "networkDisconnected" — The network connection terminated abruptly (for example, the client lost their internet connection).

Depending on the context, this description may allow the developer to refine the course of action they take in response to an event.

For a connectionCreated event, this string is undefined.

target (Object) — The object that dispatched the event.

type (String) — The type of event. There are two types of ConnectionEvent object:

  • "connectionCreated" — A new connection to the session has been created.
  • "connectionDestroyed" — A connection to this session has ended.


The following code keeps a running total of the number of connections to a session by monitoring the connections property of the sessionConnect, connectionCreated and connectionDestroyed events:

var apiKey = ""; // Replace with your API key. See https://dashboard.tokbox.com/projects
var sessionID = ""; // Replace with your own session ID.
                    // See https://dashboard.tokbox.com/projects/
var token = ""; // Replace with a generated token that has been assigned the moderator role.
                // See https://dashboard.tokbox.com/projects/
var connectionCount = 0;

var session = TB.initSession(sessionID);
session.addEventListener("sessionConnected", sessionConnectedHandler);
session.addEventListener("connectionCreated", connectionCreatedHandler);
session.addEventListener("connectionDestroyed", connectionDestroyedHandler);
session.connect(apiKey, token);

function sessionConnectedHandler(event) {
   connectionCount = event.connections.length; 

function connectionCreatedHandler(event) {
   connectionCount += event.connections.length;

function connectionDestroyedHandler(event) {
   connectionCount -= event.connections.length;

function displayConnectionCount() {
    document.getElementById("connectionCountField").value = connectionCount.toString(); 

This example assumes that there is an input text field in the HTML DOM with the id set to "connectionCountField":

<input type="text" id="connectionCountField" value="0"></input>

IRC Live Chat

Have a quick question? Chat with TokBox Support on IRC. Join chat