Mesibo Backend APIs - Legacy form-encoded Requests

This section is only for the mesibo users using old form-encoded requests.

Although, mesibo backend APIs are primarily JSON-based APIs, it also supports legacy form-encoded requests for backward compatibility. However, it is highly recommended that you use JSON-based APIs for all new developments.

Mesibo Backend API URL

If you are not using mesibo on-premise, the following is the backend API URL:

https://api.mesibo.com/backend/

For on-premise, refer to Using Backend APIs with On-Premise to learn how to download and host backend APIs on your own server.

Request Structure

The request is URL encoded GET request, for example,

https://api.mesibo.com/backend/?op=useradd&token=123434343xxxxxxxxx&addr=xyz&appid=com.mesibo.firstapp

Every API request will have minimum two parameters:

operation (op), identifies the operation requested.
Application token (token), unique app token for your application which your MUST not share with anyone including your users. You can get and change the app token from the mesibo Consoleopen_in_new.
[Optional] Request Identifier (id), any random integer value to identify request. It will be returned back in the response.

There can be more parameters depending on the operation.

Response Structure

The response is a JSON object with at least the following fields, and other fields depending on the operation as described below. Only use the documented fields below:

op, requested operation
result, true if successful, false otherwise
error, error code if the request failed

An example of a successful JSON response is as follows:

{ 
  "user": {
	"uid":123,
	"address":"xyz@example.com",
	"token":"79a818d76fe45fb5a3ac395a0a98251c3db2eetb7b0d4aa0"
	  },
  "op":"useradd",
  "result":true
}

An example of a failed JSON response is as follows:

{"op":"someop","result":false,"error":"BADOP"}

Playground

You may use Mesibo Backend API Playground to quickly familiarize yourself with syntax and parameters. The best way to use the playground is to use it when reading the reference section below.

Mesibo backend APIs Reference

Mesibo backend APIs is broadly categorized into two categories:

Following are the list of Mesibo REST APIs.

User Management APIs

Add a User / Regenerate a User Access Token

To enable real-time communication between your users, you need to let mesibo know about each of your users. Mesibo will create an access token for each user and give it to you which you can send it to your users. Your user can then use this access token in Mesibo Real-time APIs using setAccessToken function.

To add a user or to re-generate user access token, you need to invoke this API with the following parameters:

op = "useradd"
token = Application Token obtained from the mesibo console
addr = User Address (e.g phone number, email address, etc.)
appid = Android package name declared in the AndroidManifest.xml (and google-services.json), Or iOS Bundle id declared in the Xcode project. The generated token will be applicable for the app having this package name or Bundle id only. For all other platforms, you can pass any non-numeric, dotted string (for example, com.yourdomain.yourapp), and the same need to be passed to the setAppName function. Use lower case only.
expiry = in minutes, default 1 year [Optional]
active = enable user, default 1 (active) [Optional]
name = Name [Optional]
groups = Maximum Groups [Optional]

Response Fields

{ 
  "user": {
	"uid":123,
	"address":"xyz@example.com",
	"token":"79a818d76fe45fb5a3ac395a0a98251c3db2eetb7b0d4aa0"
	  },
  "op":"useradd",
  "result":true
}

where,

user.address = User address that was sent in the request
user.uid = Numerical unique user ID generated by the backend. You can use this UID instead of the address in other requests.
user.token = Access token which you should use in the real-time API

You should save user information (UID, Address, Access Token, etc.) from the response to your own database so that you can access them later.

Edit a User

Edit an existing user using the UID obtained from add user operation.

op = "userset"
token = Application Token obtained from the mesibo console
uid = User ID obtained in add user operation
flag = Flags
active = 1 to enable, 0 to disable

The response is the same as the one from the useradd operation.

Delete a User

Delete an existing user using UID obtained from add user operation.

op = "userdel"
token = Application Token obtained from the mesibo console
uid = User ID obtained in add user operation

{ 
  "user": { "uid":123 },
  "op":"userdel",
  "result":true
}

Delete a User Access Token

Delete an existing user access token without deleting a user. User will be logged-out but will continue to receive messages which will be delivered when user logs-in next time with a new token.

op = "deltoken"
token = Application Token obtained from mesibo console
uid = User ID obtained in add user operation

Get Users

Mesibo does not provide any APIs for getting users. The reason is that many mesibo customers have millions of users and it is not practical to retrieve them. If you are using mesibo on-premise, you will find all your users in the users table. If not, you are required to store your users locally in your own database.

Group Management APIs

mesibo allows you to create groups having a set of users as group members. Once you create a group, you can send messages to the group, and all the group members will receive the messages. You can create groups of any size without any restrictions.

If you are using mesibo on-premise, you should instead use real-time Group Management APIs or host backend APIs in your own server. Refer to Using Backend APIs with On-Premise

To use group messaging, you only need to perform the following:

Create a group
Add members
Start sending messages

There is various kind of group messaging possible with mesibo, to categorize a few:

Normal group: any group member can send and receive messages to a group.
Restricted group: only selected group members can send messages to a group and selected group members can receive messages from the group. Senders and receivers can be a disjoint set.
Broadcast group: only the admin can send messages to the group.
Public Rooms: anyone can message, even non-members.
Round-robin (hunt) group: only one group member from the group will receive the message in a 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 a 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
Only Selected Members can receive
Members can receive
One of the active members can receive, etc

You can dynamically change the group or the member behavior at any point in time and it will be instantly applied to the group or group member(s).

Create a Group

Create a group to enable real-time group communication between your users. Mesibo will create a group ID (GID) which you can use to add and remove members. Your users can use GID in various real-time API to send messages to the group.

To create a group, you need to invoke this API with the following parameters:

op = "groupadd"
token = Application Token obtained from mesibo console
name = Group Name [Optional]
flag = Group Flags (described below)
expiry = Expiry in seconds, default 1 year
expiryext = Auto-extend expiry on group activity, in seconds. Default disabled.
active = 1 to enable, 0 to disable

Group Flags can be a logical OR combination of one or more flags value below:

0 - normal group, only members can send
1 - only selected members can send (refer add members API below)
2 - anyone can send
0x10 - only selected members can receive (refer add members API below)
0x20 - received by one member in the round-robin fashion
0x40 - do no store group messages
0x80 - loop back to the sender

Response Fields

{
	"group":{"gid":123},
	"op":"groupadd",
	"result":true
}

You should save the created group information (GID, name, etc.) in your own database so that you can access them later.

Edit a Group

Edit an existing group using GID obtained in the group add operation.

op = "groupset"
token = Application Token obtained from mesibo console
gid = Group ID (GID)
type = [Optional] - refer to Group Permissions per message type section below
name = Group Name [Optional]
flag = Group Flags
expiry = Expiry in seconds, default 1 year
expiryext = Auto extend expiry on group activity, in seconds. Default disabled.
active = 1 to enable, 0 to disable

Response Fields

The response is the same as the one from the groupadd operation.

Delete a Group

Delete an existing group using GID obtained in the group add operation.

op = "groupdel"
token = Application Token obtained from mesibo console
gid = Group ID (GID)

The response is the same as the one from the groupadd operation.

Add or Remove Group Members

Add or Remove Group Members using GID obtained in the group add operation.

op = "groupeditmembers"
token = Application Token obtained from mesibo console
gid = Group ID (GID)
type = [Optional] - refer to Group Permissions per message type section below
m = comma-separated list of user addresses to add or remove in the group
cs = 1 if members being added can send messages to the group, 0 for not
cr = 1 if members being added can receive group messages, 0 for not
canpub = [group calling] 1 if members being added can make (publish) group voice or video calls, 0 for not
cansub = [group calling] 1 if members being added can subscribe to group voice or video calls, 0 for not
canlist = [group calling] 1 if members being added can get a list of active callers in the group, 0 for not
delete = 0 to add members, 1 to remove members

The response is the same as the one from the groupadd operation.

Get Group Members

Get Group Members using GID obtained in the groupadd operation.

On Cloud, this API is only for development purpose only and hence rate limited and maximum 20 members will be returned. You should store your group members locally instead of obtaining from the mesibo. You MUST not use this API in production and excessive use can be blocked. No such limitations apply for on-premise.

op = "groupgetmembers"
token = Application Token obtained from mesibo console
gid = Group ID (GID)
count = max number of users to get. Max 20

Response Fields

response[‘members’] = Group Members

Group Permissions per message type

By default, the group permissions apply to all the group messages. However, there are instances when you would like some group messages to send and received only by selected members within a group. For example, in a group collaboration or game scenarios, only active participants should be allowed to send messages so that they can participate, while passive viewers can only receive messages so that they can only view it. The whiteboard in the mesibo conference demo is one such example where only active publishers can draw on the board while others can only view.

To achieve this, mesibo allows you to further specify permissions per message type. When a group message is sent with a particular type, it is checked against additional permissions (if set) to see if a user is allowed to send or receive this message.

To set permissions for each message type, use Edit a group operation described above with an additional parameter type. You also need to use type while adding and removing members.

Message API

While your users can send messages to each-other or groups using Mesibo real-time APIs, you can also send messages to one of your users or group using backend API.

To send a message, you need to invoke this API with the following parameters:

op = "message"
token = Application Token obtained from mesibo console
from = From Address [MUST be a valid user]
to = To Address
gid = Group ID [Optional, either this or to field needs to be present]
type = Message Type
expiry = Expiry in seconds, default 1 year
when = Schedule after when seconds [Optional], default 0 (now)
msg = Message

The response could be true or false.