Suggestions

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

Sending a signal to a specific client in a session

To send a signal to a specific client in a session, set the signal prop of the OTSession component and set the to property of the signal object to the connection ID:

<OTSession
  signal={{
    to: 'connection-id',
    data: 'hello',
  }}
/>

The to property is a connection ID for a client connected to the session that you want to signal. You obtain connection IDs for clients when the the OTSession object dispatches connectionCreated events.

The data property of the signal prop 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.

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

<OTSession
  signal={{
    to: 'connection-id',
    data: 'hello',
    type: 'textMessage',
  }}
/>

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 '~'.

Sending a signal to all clients in a session

To send a signal to a specific client in a session, set the signal prop of the OTSession component, but do not set the to property of the signal object to the connection ID:

<OTSession
  signal={{
    data: 'hello',
  }}
/>

For details on the other options you pass into the signal prop, see the previous section.

Receiving signals in a session

To start receiving all signals sent in a session, add an event handler for the signal event, dispatched by the OTSession component:

<OTSession
  apiKey="your-api-key"
  sessionId="your-session-id"
  token="your-session-token"
  eventHandlers={{
    signal: event => {
      console.log('signal received from connection ID:', event.connectionId);
      console.log('signal data:', event.data);
      console.log('signal type:', event.type);
    },
  }}
>
  { /* ... */ }
</OTSession>

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 handler for the signal:type event, replacing "type" with the type string. For example, the following listens for signals of type "foo":

<OTSession
  apiKey="your-api-key"
  sessionId="your-session-id"
  token="your-session-token"
  eventHandlers={{
    'signal:foo': event => {
      console.log('foo signal received from connection ID:', event.connectionId);
      console.log('signal data:', event.data);
    },
  }}
>
  { /* ... */ }
</OTSession>

You can compare the connectionId property of the event object with the connectionId property of the sessionConnected event dispatched by the Session object to see if the signal was sent by your client or another.

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 connectionId property of the event object is set to null.