Mesibo Real-time Chat APIs - Messaging
Estimated reading time: 17 minutesSending messages using Mesibo only requires initializing a MesssageParams
object with needed parameters and invoke one of the messaging API with params, Message-ID, and the message.
Each message has essentially two parts:
- Message properties, for example, type of message, expiry, Message-ID, etc. Refer to Getting Started Guide for more information. You can specify message properties using MessageParams
- Message
You should use a unique Message-ID for sending each message so that you can identify the message when the message status is received. Message-ID is a 32-bit unique id. It will be converted into a 64-bit globally unique ID by the system. The ID which you have originally passed will be preserved in the lower 32-bit of the globally unique ID. For example, if you send a message with id 0x12345678, it will be converted into global id 0xXXXXXXXX12345678 when delivering your message to the receiver. If you use zero Message-ID, the message will be delivered only if the recipient is online, it will be discarded otherwise. You should use zero message-ID only for cases where storage is not required, for example, presence information like typing indicators, online status, etc.
sendMessage
Send a message. There are overloaded functions to send messages in different formats, for example, string, byte array, etc.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID. For sending messages, Message-ID should be specified in the function parameters instead of using it from params. This enables using the same
MessageParams
object from different threads. - message, Message
sendFile
Send a file. This API is described in more detail in the File Transfer API. Note that this API is deprecated and will soon be replaced by a common API.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID. For sending messages, Message-ID should be specified in the function parameters instead of using it from params. This enables using the same
MessageParams
object from different threads. - file,
FileInfo
object initialized with file information like path, type, etc.
sendLocation
Send a location. This API is deprecated and will soon be replaced by a common API.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID. For sending messages, Message-ID should be specified in the function parameters instead of using it from params. This enables using the same
MessageParams
object from different threads. - location,
LocationInfo
object initialized with location information like latitude, longitude, address, etc.
forwardMessage
Forward an existing message to a user or a group. A FORWARD flag will be set at the recipient end to indicate it as a forwarded message.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID of an existing message to be forwarded
You must enable local database using
setDatabase
API for this API to work.
resendMessage
Resend a failed message.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID of an existing message to be resent
You must enable local database using
setDatabase
API for this API to work.
cancel
Cancel a message. Message can not be canceled if already sent & delivered. Use deleteMessage
API if you like to recall a delivered message.
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters - mid, Message-ID of an existing message to be cancel
deleteMessage
Delete a message.
It takes the following parameters:
- mid, Message-ID of an existing message to be deleted
deleteMessages
Delete messages matching criteria in MessageParams
object. For example, if you pass MessageParams
with address
set, it will delete all the messages from an address
It takes the following parameters:
- params,
MessageParams
object initialized with required parameters
random
Returns a new unique message ID that you can use to send messages.
It does not take any parameters.
Messaging APIs Example
Android Example
In Java,
Mesibo.MessageParams p = new Mesibo.MessageParams(to, Mesibo.FLAG_DEFAULT);
int rv = Mesibo.sendMessage(p, Mesibo.random(), "A Test Message");
if(Mesibo.RESULT_OK == rv) {
Log.d(TAG, "Message sent");
} else {
Log.d(TAG, "Message failed: " + rv);
}
In Kotlin,
val p: Mesibo.MessageParams = Mesibo.MessageParams()
p.peer = mRemoteUser!!.address
p.flag = Mesibo.FLAG_READRECEIPT or Mesibo.FLAG_DELIVERYRECEIPT
read-session-apis-exampleMesibo.sendMessage(p, Mesibo.random(), "A Test Message");
iOS Example
In Objective-C,
MesiboParams *p = [MesiboParams new];
[p setPeer:to];
[p setFlag:MESIBO_FLAG_READRECEIPT|MESIBO_FLAG_DELIVERYRECEIPT];
[p setExpiry:3600*24*7];
uint32_t mid = [MesiboInstance random];
[MesiboInstance sendMessage:params msgid:mid string:@"A Test Message"];
In Swift,
let params = MesiboParams()
params.peer = mRemoteUser
params.flag = (UInt32)(MESIBO_FLAG_READRECEIPT | MESIBO_FLAG_DELIVERYRECEIPT)
let mid = Mesibo.getInstance()!.random()
Mesibo.getInstance()!.sendMessage(params, msgid: mid, string: "A Test Messages")
Javascript Example
var p = {};
p.peer = to;
p.flag = MESIBO_FLAG_DEFAULT;
api.sendMessage(p, api.random(), message);
Reading Stored Messages and Sending Read Receipts
This set of APIs deal with stored messages in the database and sending read receipts.
To read stored messages from the database, you need to create a read session and set the criteria to read messages; for example,
- read all messages
- read messages from a sender
- read messages for a particular group
- read messages matching a search query
- etc.
Reading Modes
You can set a read session for a user or a group using a method with the following syntax:
Mesibo.ReadDbSession(peer, groupid, query, listener)
There are two modes of operation:
- Read Messages and call logs. This mode is enabled by default. To create a read session in this mode set the
peer
with the address of the user when you are reading messages for a user or thegroupid
in case of a group. - Read Summary, read the latest message from each user and group. This allows you to get a snapshot of all the communicating users and groups. You can then create another read session to read messages for any of those users or groups. Set the
address
tonull
and thegroupid
to0
while setting a read session in summary mode.
See examples
Reading Order
Once you set a read session, you can start reading messages by calling read
API. You can read messages in the first-in-first-out (FIFO) mode or the last-in-first-out (LIFO) mode. In the first-in-first-out mode, the oldest messages are read first. By default, the first-in-first-out mode is disabled.
Read Receipts
You can enable the automatic sending of read-receipts every time you read a message. This can be achieved by enabling read-receipt for the read session. On reading or receiving a message, read receipts will be automatically sent if
- Sending Read Receipt is enabled for the reading session, AND
- Read receipt requested by the sender, AND
- A new real-time or database message matches the read session.
Following are the various read session
APIs followed by examples. Unless specified, all the read session APIs takes only one parameter:
- enable, Enable or Disable a particular mode
enableSummary
Enable or disable Summary mode. Refer to Reading Modes
above for the details.
enableFifo
Enable or disable the first-in-first-out mode. Refer to Reading Order
above for the details.
enableFiles
Enable reading messages having files. Messages without files will not be read.
enableIncomingCalls
Enable or disable reading incoming call logs along with other messages.
enableOutgoingCalls
Enable or disable reading outgoing call logs along with other messages.
enableMissedCalls
Enable or disable reading missed call logs along with other messages.
enableCalls
Enable or disable reading all the call logs along with other messages.
enableReadReceipt
Enable or disable sending read receipts
read
Read the requested number of messages. Any subsequent invocations will read more messages till all the messages have been read.
It takes the following parameters:
- count, number of messages to read
sync
Sync the requested number of messages from server to the local database. Sync is an asychronous operation, Mesibo_OnSync() listener will be called when sync completes.
It takes the following parameters:
- count, number of messages to sync
- Sync Listener The listener context that implements
Mesibo_onSync
.
Read APIs Example
Android Example
To read messages from a user, in Java
// Read receipts are enabled only when App is set to be in foreground
Mesibo.setAppInForeground(this, 0, true);
Mesibo.ReadDbSession mReadSession = new Mesibo.ReadDbSession(from, 0, null, this);
mReadSession.enableReadReceipt(true);
mReadSession.enableMissedCalls(mShowMissedCalls);
mReadSession.read(100);
To read last message from each user (summary), in Java
Mesibo.ReadDbSession mReadSession = new Mesibo.ReadDbSession(null, 0, null, this);
mDbSession.enableSummary(true);
mReadSession.enableReadReceipt(false);
mReadSession.enableMissedCalls(mShowMissedCalls);
mReadSession.read(100);
To read messages from a user, in Kotlin
// Read receipts are enabled only when App is set to be in foreground
Mesibo.setAppInForeground(this, 0, true)
mReadSession = Mesibo.ReadDbSession(mRemoteUser!!.address, this)
mReadSession?.enableReadReceipt(true)
mReadSession?.read(100)
To read last message from each user (summary), in Kotlin
mReadSession = Mesibo.ReadDbSession(null, this)
mReadSession?.enableReadReceipt(true)
mReadSession?.enableMissedCalls(true)
mReadSession?.read(100)
iOS Example
To read messages from a user, In Objective-C,
MesiboReadSession *mReadSession = [MesiboReadSession new];
[mReadSession initSession:mRemoteUser groupid:0 query:nil delegate:self];
[mReadSession enableReadReceipt:YES];
[mReadSession read:100];
To read last message from each user (summary), In Objective-C,
MesiboReadSession *mReadSession = [MesiboReadSession new];
[mReadSession initSession:nil groupid:0 query:nil delegate:self];
[mReadSession enableSummary:YES];
[mReadSession read:100];
To read messages from a user, In Swift,
mReadSession = MesiboReadSession()
mReadSession.initSession(mRemoteUser, groupid: 0, query: nil, delegate: self)
mReadSession.enableReadReceipt(true)
mReadSession.read(100)
To read last message from each user (summary), In Swift,
mReadSession = MesiboReadSession()
mReadSession.initSession(nil, groupid: 0, query: nil, delegate: self)
mReadSession.enableSummary(true)
mReadSession.read(100)
Javascript Example
The way
read
works in the mesibo Javascript API differs slightly from Android/iOS APIs. This is mainly because of how the local database(IndexDB) operates. In Android/iOS read messages are received in theonMessage
callback. In Javascript, you get the number of messages through the read handler that you set while creating the read session.
Here is an example in Javascript, to read all messages of an example user, with the address testuser
. Replace it with the user address you have. Set the groupid
parameter to 0, while reading user messages.
var messageSession = api.readDbSession('testuser', 0, null,
function on_read(count) {
console.log("Read "+ count + " number of messages");
var messages = messageSession.getMessages();
});
messageSession.enableReadReceipt(true);
messageSession.read(100);
To read message summary,
var summarySession = api.readDbSession(null, 0, null,
function on_read(count) {
var messages = summarySession.getMessages();
//Here you will get a message summary which contains a list of each user who was sent/received message, their last message, etc.
});
summarySession.enableSummary(true);
summarySession.read(100);
Synchronization
mesibo provides sync() APIs so that you can download all the messages from the server to the local database and then use normal mesibo read APIs to read messages as required.
It is recommended to use synchronization API on-demand when you run out of messages in the local database. A typical usage would be to use it along with the read() API. The read() API returns the number of messages that were read. If the number of messages is less than you requested, use the sync()
API to synchronize the local database with the server. The onSync()
function is called with the number of messages synced when sync()
is completed.
The sync
method available through read Session, takes two parameters:
- count The number of messages you want to synchronize
- OnSync Listener that will be called when sync completes (Listener in case of Android/iOS. In case of Javascript, you need to pass an
on_sync
handler. See Javascript Example).
Note that a call to read()
is synchronous while the call to sync()
is asynchronous. The result of your sync
the request will be available through the listener OnSync
. The call to sync
checks messages stored on the mesibo server and transfers those messages to your local database. The number of messages that have been synced will be available as a parameter count
in the OnSync
listener. You can read count
number of messages using read()
.
Synchronization APIs example
Android Example
Mesibo.ReadDbSession mReadSession = new Mesibo.ReadDbSession(mRemoteUser, 0, null, this);
int readCount = 10;
int result = mReadSession.read(readCount);
if(result < readCount){
mReadSession.sync(readCount - result, this);
}
@Override
public void Mesibo_onSync(int count) {
// count number of messages have been synced
// You can now read these messages
if(count <= 0) return;
mReadSession.read(count);
}
iOS Example
mReadSession = [MesiboReadSession new];
[mReadSession initSession:mRemoteUser groupid:0 query:nil delegate:self];
int readCount = 10;
int result = [mReadSession read:readCount];
if(result < readCount) {
[mReadSession.sync:readCount - result SyncListener:self];
}
-(void) Mesibo_OnSync:(int)count {
// count number of messages have been synced
// You can now read these messages
if(count <= 0) return;
[mReadSession read:count]
}
Javascript Example
In the case of Javascript, you need to pass an on_sync
handler as a parameter to sync()
, which will be called when sync completes. You can then call read()
inside the sync handler.
let rSession = mesibo.readDbSession(peer, groupid, null,
function on_read(count) {
if(count < this.readCount){
//Run out of messages
this.sync(this.readCount - count,
function on_sync(i){
if(i > 0){
this.read(i);
let msgs = this.getMessages();
// Display messages
}
});
return;
}
let msgs = this.getMessages();
//Display Messages if you have sufficient messages
});
rSession.readCount = 10;
rSession.read(10);