Signal Service

Signal Service provides core signaling capabilities. The messages sent through it are not persisted and are meant for sending various real-time notifications like call invites, WebRTC negotiation exchanges, typing notifications etc. These capabilities can be used independently from other services.

Initialization

The only argument needed to initialize a connection to the Signal Service is an AccessToken instance.

// Init Signal Service
var signalSvc = new bit6.Signal(accessToken);

Direct Messages

The Signal Service allows a client to send a signal message to another client. The destination address can be:

The third option is an internal representation of the user endpoint address. When a client gets a message from somebody, the from address will be in this format. And for the response to reach exactly the same endpoint that sent the original message, the response message must be sent to this address.

signalSvc.send( {to: 'alice', text: 'Hello from bob'} );

To receive direct messages via Signal Service you need to register an event handler.

signalSvc.on('message', function(msg) {
  console.log('Received direct signal', msg);
});

Channels

Channels provide a very lightweight pub/sub messaging capabilites. A channel can have an arbitrary name. Information about participants and messages is not persisted.

You can get a map of all Channels this client is participating in:

// Get all channels
console.log('All channels:', signalSvc.channels);

To join a channel:

// Join a channel named 'cha'
var ch = signalSvc.join('cha');
// Leave the channel
ch.leave();

Messages

You can publish a message to the Channel. It will be delivered to all channel participants.

// Publish a message to the channel
ch.publish( {text: 'hey everybody'} );

To receive signal signal messages published to the Channel, you need to register a handler for the channel:

// Received a signal
ch.on('message', function(msg) {
  console.log('Received channel signal', msg);
});

Presence

Channel Service can broadcast the information about the connected Participants to all the other Participants in the channel. By default this function is switched off. You need to enable when joing a channel.

// Join channel and get notified about other participants
var ch = signalSvc.join('cha', {presence: true});

You can access all the current Channel Participants:

console.log('Current participants', ch.participants);

Get notified about participants joining and leaving:

// p - Participant object
// op - operation performed: 1 - add, 0 - update, -1 - delete
ch.on('participant', function(p, op) {
  console.log('Participant', op, p);
});

State

A Channel Participant can share own state by specifying its local state object which is automatically published to all the other Channel Participants.

// Update own state
ch.me.updateState( { iam: 'bob' } );
// Get notifications about state updates to this participant
participant.on('state', function(state) {
  console.log('Participant', participant.id, 'state updated', state);
});