Suggestions

close search

Searching ...

Use the OpenTok signaling API to send text and data between clients connected to an OpenTok session.

For conceptual information on the OpenTok signaling API, see the Signaling overview developer guide.

This topic includes the following sections:

• Sending a signal to a specific client in a session
• Sending a signal to all clients in a session
• Receiving signals in a session
• Preventing signals from being sent during automatic reconnection

Sending a signal to a specific client in a session

To send a signal to a specific client in a session, call the signal() method of the Session object and set the to property of the signal parameter:

session.signal(
  {
    to: connection1,
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

The to property is a Connection object corresponding to clients connected to the session that you want to signal. You obtain references to Connection objects when the Session object dispatches sessionConnected and connectionCreated events. You can also obtain the Connection object corresponding to a stream by getting the connection property of the Stream object.

The data property of the signal parameter is the data string you send with the message. This property is optional. If you omit it, the message will be sent without a data payload. The limit to the size of data is 8KB.

The completerHandler parameter of the signal() method is called when the call the method succeeds or fails. The error parameter passed into the completion handler is set to null if the call succeeds. When the call the method fails, the error object has the following properties: code (a numeric error code), message (a string describing the error), and signal (an object corresponding to the signal parameter passed into the signal() method).

Additionally, you can pass in a type property of the signal parameter. This is a string value that clients can filter on when listening for signals:

session.signal(
  {
    data:"hello",
    type:"textMessage"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

The maximum length of the type string is 128 bytes, and it must contain only letters (A-Z and a-z), numbers (0-9), '-', '_', and '~'.

For more details, see the documentation for the Session.signal() method.

Sending a signal to all clients in a session

To send a signal to all clients in a session, call the signal() method of the Session object, but do not set a to property for the signal parameter:

session.signal(
  {
    data:"hello"
  },
  function(error) {
    if (error) {
      console.log("signal error ("
                   + error.name
                   + "): " + error.message);
    } else {
      console.log("signal sent.");
    }
  }
);

For details on the other options you pass into the signal() method, see the previous section.

Calling this method without limiting the set of recipient clients will result in multiple signals sent (one to each client in the session).

Receiving signals in a session

To start receiving all signals sent in a session, add an event listener for the signal event, dispatched by the Session object:

    session.on("signal", function(event) {
      console.log("Signal sent from connection " + event.from.id);
      // Process the event.data property, if there is any data.
    });

You can also listen for only signals set to a specific type. (You can set the type of a signal, optionally, when you send a signal.) Register an event listener for the signal:type event, replacing "type" with the type string. For example, the following listens for signals of type "foo":

session.on("signal:foo", function(event) {
 console.log("Signal sent from connection " + event.from.id);
 // Process the event.data property, if there is any data.
});

You can compare the from property of the event object with the connection property of the Session object to see if the signal was sent by your client or another:

session.on("signal:foo", function(event) {
  if (connection && event.from.connectionId != session.connection.id) {
    // Signal received from another client
  }
}

Note that you can use a REST API call to send a signal from your server, instead of from a client connected to the session. In this case, the from property of the event object is set to null.

Preventing signals from being sent during automatic reconnection

Clients will attempt to automatically reconnect to a session they disconnect unexpectedly (for example, due to a drop in network connectivity). By default, any signals you send while the client is temporarily disconnected from a session are queued and sent when (and if) it successfully reconnects. You can set the retryAfterReconnect property to false in the options you pass into the Session.signal() method to prevent signals from being queued while the client is disconnected. For more information, see Automatic reconnection.