Chat Service

Chat Service provides IP messaging capabilities for exchanging text and rich media messages between participants. The information about the the conversations, participants and messages is persisted in the Bit6 platform and is synchronized with the client endpoints.

Initialization

The only argument needed to initialize the Chat Service is an instance of Signal Service.

// Init Chat Service
var chatSvc = new bit6.Chat(signalSvc);

If you want the Chat service to automatically synchronize the data in real-time, add a sync option to the initialization code:

// Init Chat Service with automatic synchronization
var chatSvc = new bit6.Chat(signalSvc, {sync: true});

Concepts

Conversations

Get a map of all Conversations this client is participating in:

// Get all Conversations
console.log('All conversations:', chatSvc.conversations);

Get notified about the current client joining and leaving conversations.

// c - Conversation object
// op - operation performed: 1 - add, 0 - update, -1 - delete
chatSvc.on('conversation', function(c, op) {
  console.log('Chat Conversation', op, c);
});

Properties

Create / Join / Leave

A client can create a new Conversation. It is automatically added as a Participant.

// Create a conversation. Callback is optional.
chatSvc.create({}, function(err, c) {
  console.log('Conversation created', err, c.id);
});

To join an existing Conversation you need its id:

// Join a Conversation. Callback is optional.
var convId = '...';
chatSvc.join(convId, function(err, c) {
  console.log('Conversation joined', err, c.id);
});

To leave a Conversation this client is participating in:

conversation.leave();

Participants

Get a map of all the remote Participants of a Conversation:

console.log('All participants:', conversation.participants);

This client representation in the Conversation:

console.log('Me:', conversation.me);

Get notified about Participants joining and leaving a Conversation:

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

Properties

Add / Kick

Add a Participant to a Conversation:

// Add a participant. Callback is optional.
c.add('bob', function(err, p) {
  console.log('Participant added', err, p);
});

Kick a Participant from a Conversation:

// Kick a participant by id. Callback is optional.
c.kick('bob', function(err, p) {
  console.log('Participant kicked', err, p);
});
// Or you can call kick() direclty on the Participant object
participant.kick();

Messages

Get an array of Messages sorted in the chronological order:

console.log('Latest messages:', conversation.mesages);

Get notified about Messages arriving:

// m - Message object
// op - operation performed: 1 - add, 0 - update, -1 - delete
conversation.on('message', function(m, op) {
  console.log('Chat Message', op, m);
});

Properties

Send

Send a message with text payload:

conversation.send( {text: 'Hello World!'} );

History

By default the SDK will load latest 50 messages from a Conversation. If syncing is enabled SDK pre-loads 50 latest messages per conversation. The newer messages will appear automatically as they are being received. You can load previous conversation messages using fetchMessages() method. It supports cursor-based pagination.

If you have 1000 messages in a Conversation, and latest 50 are loaded, you can do:

// oldestMessage - is the oldest message loaded via SDK.
// Usually it will be in conversation.messages[0]
conversation.fetchMessages({before: oldestMessage.id, limit: 100})

SDK will load 100 older messages and the events for them will be emitted.

Messaging UI

Bit6 SDK automatically synchronizes the messages with the server and organizes them into conversations. It emits message and conversation data change events.

The app code should rely on these events to build and update the DOM elements in the UI.

This approach is implemented in the demo app included with the SDK. The demo displays a list of the chats and the messages of the currently selected chat. See a brief description below.

Conversations

The app code maintains a DOM representation for each conversation.

chatSvc.on('conversation', function(c, op) {
  // We have two elements per conversation:
  // 1. Tab - shows conversation's view: title, unread etc
  // 2. Msgs - container for all the messages for this conversation
  var tabId = tabIdFromConvId(c.id);
  var msgsId = msgsIdFromConvId(c.id);
  // DOM elements
  var tab = $(tabId);
  var msgs = $(msgsId);
  // Deleted conversation
  if (op < 0) {
    // Remove DOM elements
    tab.remove();
    msgs.remove();
    return;
  }
  // New conversation
  if (op > 0) {
    // Create DOM elements
    tab = $('<div />').attr('id', tabId);
    msgs = $('<div />').attr('id', msgsId);
    // Add them into the main DOM tree
  }
  // Update 'tab' element with Conversation data
  tab.text(c.id + ' ' + c.unread + ' ' + c.updated);
});

Note that if there is a new message that needs a new conversation, the SDK will create a corresponding Conversation object and emit conversation event before emitting the message event.

Messages

Similarly the app maintains a DOM represenation for each message.

conversation.on('message', function(m, op) {
  // Id for the DOM element showing this Message, based on m.id
  var divId = domIdFromMessageId(m.id);
  // DOM element
  var div = $(divId);
  // Deleted message
  if (op < 0) {
    // Remove DOM element
    div.remove();
    return;
  }
  // New message
  if (op > 0) {
    // Create the DOM element
    div = $('<div />').attr('id', divId);
    // Add it to the corresponding Conversation's
    // messages container
    var msgsId = msgsIdFromConvId( conversation.id );
    $(msgsId).append(div);
  }
  // Update 'div' with the Message data
  div.text(m.text);
});