Basic Concepts

Let’s quickly familiarize with how mesibo works and then we swiftly move on to develop our first application. We will again look into these in more details in the “Reference guides” section.

Type of APIs

mesibo provides two type of APIs

  1. Client-side API - Real-time Messaging API for Android, iOS, & Web
    mesibo client API allows users to communicate in real-time by providing 1-to-1 messaging, group messaging, voice and video calls APIs. This is the API which you will integrate with your Android, iOS or Web based client application.
  2. Server-side REST API
    mesibo server-side API allows your servers to communicate with mesibo to perform various administrative tasks such as managing users & groups, managing apps, access statistics, and so on.

In subsequent sections, we will have a closer look at how these APIs work together.

How mesibo Works

mesibo is a high performance, high-availability, asynchronous real-time messaging platform that allows your users (endpoints) to communicate with each other in real-time.

There are broadly two categories of real-time communication:

1-to-1 communication, in which the communication is between two parties; for example, a chat or a call.

Group communication, in which the communication is between set of users; for example, a group chat or a conference call.

For mesibo to enable real-time communication between your users, you first have to let mesibo know about your users and groups. This is done by invoking mesibo server-side api.

mesibo-server-side-api

As shown in the diagram above

  1. You inform mesibo about every user (necessarily client apps) that wishes to use messaging, and mesibo will issue access token (link) for each of them.
  2. Your client uses access token to start using mesibo real-time messaging API.

A more elaborate real-life scenario,

mesibo-sample-authentication-and-message-sequence

The power of mesibo is that it makes extremely trivial to send and receive arbitrary real-time messages by using well thought-of design patterns. In short,

  1. To send a message, call one of the messaging APIs with destination (a user or a group), type of message, expiry if any, and your message. That’s about it! mesibo will send message and also inform you about the status of messages sent in real-time.
  2. To receive messages, implement mesibo listeners (delegates in iOS). mesibo will inform you whenever you receive any messages or calls.
  3. To send and receive files, just implement mesibo file transfer handler which will upload (to send) and download (on receive) file to or from your server.

That’s it. mesibo takes care of everything including connection handling, retries, error handling, flow control etc.

mesibo delivers messages instantly if the destination user is online. If not, messages will be delivered as soon as destination user comes online. This is automatic and transparent to applications, so applications sending messages do not need to worry if the receiving applications are up and running. Conversely, receiving applications do not need to worry about the status of ending application.

Key Elements

Now let’s look at key elements of mesibo messaging API.

Message

A message is the unit of data which is sent between two users or multiple users in case of a group message.

A core message in mesibo is a raw binary data, essentially an array of bytes. This allows you to send any arbitrary data in real-time, for example, a text message, a binary message, a webrtc SDP, a TLV message, a JSON message or anything limited only by your imagination.

mesibo also provides other type of messages like file Message, TLV (type-length-value) message etc, which all are build on top of the core message.

Message Properties

  • destination: represents the user or group a message is sent to. The messages are sent to destination in the order they are received on the server. Destination user is also referred to as peer in this document when the direction of message is unspecified.
  • expiry: represents the time within which a message has to be delivered. Expiry ranges from immediate (zero) to a few days and can be independently specified on per message basis at the time of sending. mesibo will not deliver messages past its expiry. You can also set the expiry to zero for the messages that need to be delivered in real-time and not later.
    All messages will be retained in the messaging system until delivered or until their expiry is reached.
  • type: messages can be assigned a type, default type is 0.
  • priority: represents the priority of the message. Value can range between 0 and 15. 0 represents the highest priority and 15 represents the lowest. mesibo will attempt to deliver higher priority messages before lower priority ones.
  • identifier: each message has a unique 64-bit identifier. You can assign your own identifier or it can be generated by the system. You can also set the identifier to be zero for messages that are of type fire-and-forget.
  • timestamp: represents the time the message was received.
  • status: every message has a status. Incoming messages can have status “New” or “Read”. Similarly, outgoing messages are assigned a status “OUTBOX” when sending them. It then cycles through “Sent”, “Delivered”, “Read” or one of the error conditions like invalid destination, expired etc.

Sending Messages

mesibo provide various functions to send messages in different format. Sending message is as simple as selecting a right function, call it with destination, expiries, flag.

Receiving Messages

Receiving messages is even simpler. Just implement mesibo listener in your code and this will be invoked every time you receive a message, listener will be invoked. You can also add multiple listeners.

Users (end-points)

Users are the endpoint who will send or receive messages. For mesibo to enable real-time communication between your users, you have to let mesibo know about your users. For every user you create, you will receive a token which will be used to log in using mesibo client API.

When you send a message to a user, only that particular user will receive the message and no one else.

Group

Group is a set of users. You can create a group of unlimited users for a group discussion.

mesibo supports various type of groups which you can specify at the time of group creation and modify at any point in time, for example,

  • Normal Group: any user can send and receive messages to group
  • Broadcast group: only admin can send messages to the group
  • Round-robin (hunt) Group: only one user from the group will receive the message in round robin fashion. This is quite useful for creating specialized groups; for example, in a group of support staff, only one of them will receive a message from customer.

However, instead of hardcoding group types, mesibo allows you to specify sending and receiving behavior of the group and individual group members for greater flexibility, for example,

  • Anyone can send
  • Members can send
  • Only selected members can send
  • Members can receive
  • Selected Members can receive
  • One of the active member can receive, etc

You can dynamically change the group or member behavior at any point in time.

Application

Application is a logical entity to partition your users and groups. All your users and groups are local and confined to an Application.

Suppose you are developing two Applications, one for ride-sharing and another for dating. You may want to keep users from both the applications separate even if a user is using same credentials (say a phone number) for both the apps. This is where creating separate Applications helps.

creating-separate-Applications

  • Application X and Y are completely disconnected and no communication is allowed between users and groups across Applications.
  • The user ‘A’ of Application ‘X’ is different from user ‘A’ of Application ‘Y’
  • You can create multiple Applications using server-side API or mesibo console.

hand-pointing-to-right-direction Don’t get confused between logical Application with mobile apps (Android, iOS) or web apps. For example, Facebook is a Social Application which is available on Android & iOS as mobile app and also on Desktop as web app. In this document, we will refer high level logical application as ‘Application’ and mobile or web apps as ‘apps’;

Also note that, you can create multiple mobile or web apps inside a logical Application as long as you can share users and groups among all the apps.

Access Token

An Access Token needs to be generated for every user who needs to access mesibo real-time messaging API. You can generate Access Token for every user of your application on demand and send it to the user. The user will then use this access token to initialize mesibo client-side API and start sending and receiving real-time messages.

Each Access Token can have an expiry ranging from seconds to numerous days which can be independently specified per user basis at the time of creating an access token. Depending on your application requirements, you can either generate a one-time access token for a longer duration or keep renewing access token at a reasonable interval. mesibo informs client side API in real-time when the token is about to expire and you can accordingly initiate renewal or the re-generation process.

Each Access Token has security attributes that restricts its usage only from the intended apps. For example, an access token created for an Android application com.mesibo.demo will only work with com.mesibo.demo app and will not work from any other Android, iOS or Web application. You can specify security attributes and other flags at the time of creating an access token.

Other Key Features

File Handling

Just like normal messages, mesibo allows you to send and receive any arbitrary file (image, video, doc, etc) in real-time. Sending and receiving file is no different from sending and receiving normal messages. All an application has to do is to first upload the file to a server and then send the URL and thumbnail [optional] using mesibo in real-time. The receiver then downloads it using that URL. This out-of-band mechanism ensures that no real-time messages are blocked waiting for a large files to be uploaded or downloaded.

mesibo offers you the flexibility to store all files on your own servers including private servers or cloud services like Amazon Web Services, Google Cloud Storage, Microsoft Azure etc.

Activities (Typing Indicator, gaming action etc)

Activity is a normal message but only delivered if the destination user is online. Activities are real-time and transient in nature and not stored in the database.

mesibo allows you to create any number of activities like typing indicator, join & left indicators, gaming actions as required by your applications.

Persistent Storage (Databases)

mesibo provides client-side and server-side database API for persistent storage and retrieval of messages. Simply enable this feature and mesibo takes care of everything. You can also set a flag per message to store or exclude it from getting stored, both in client and server databases.

WebHooks & Push Notifications

A WebHook is an HTTP/HTTPS URL callback. mesibo invokes it with data in real-time when something happens; for example, if a message was undelivered. A potential use of webhook could be to further send push notifications to users using say GCM or APN.

mesibo webhook allows you get valuable information about your users in real-time without polling for it, for example, when user comes online or goes offline, send and receive messages, messages are undelivered etc. Depending on your application logic, you can select only those events for which you would like to receive notification using WebHooks.

Delivery guarantee

A key feature of mesibo, and in fact any carrier grade messaging systems, is reliable messaging. With reliable messaging, the mesibo guarantees that the message will be delivered once and only once to each destination, even in the event of system failure. This is crucial for many businesses as you don't want your messages to be sent more than once or for your messages to be lost.

In some cases you may not care about delivery guarantee (fire-and-forget) and you may configure so. mesibo allows you to configure delivery guarantees as you require on per message basis.

High Availability

Server failures are catastrophic to your business operations. mesibo's highly redundant design has all the servers in M+N redundancy and hot swappable. This allows system to remain operational even after one or more server fails.

mesibo is build on a highly-resilient globally-distributed platform spread across three core sites, Asia, Europe and the United States. These core sites are and will be supported by local relay agents. In the event of failure, mesibo will automatically switch-over your client connection to another server so that your client sessions can continue as if nothing happened.