Mesibo Real-time Chat APIs - Messaging

Estimated reading time: 17 minutes

Sending 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 the groupid 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 to null and the groupid to 0 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 the onMessage 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);

File Transfer APIs >>

messaging api, android messaging api, real-time chat api, messaging api for ios