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
- A
Conversation
represents a message exchange between users - Each
Conversation
has one or moreParticipant
s - Each
Participant
represents a user and has a unique identity - Each
Message
belongs to aConversation
- Each
Message
has aParticipant
identity as a sender
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
id
- unique Conversation ID generated by the platformcreated
- creation timestamp (Unix epoch time in milliseconds)
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
id
- participant's authenticated identityrole
- role for permission control, e.g.user
,admin
etcseen
- timestamp of the last seen message (Unix epoch time in milliseconds)seenId
- id of the last seen message
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
id
- participant's authenticated identitycreated
- when the message was created - timestamp in millisecondsfrom
- identity of the Participant that sent the messagetext
- textual content of the messagedata
- any additional information, JSON object
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);
});