Mesibo Backend APIs - Group Management

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.

Unless you have a specific need for creating groups using backend API, we recommend using real-time Group Management APIs to create groups and add members. It is real-time, powerful, and works across both cloud and on-premise deployment without any changes.

Note that, you will not be able to use mesibo hosted backend API for group management if you are using mesibo on-premise. This is because mesibo will NOT have any access to your on-premise setup or database, and hence it will not be able to create groups or add members. You should either use real-time Group Management APIs or host backend APIs in your own server. Refer to Using Backend APIs with On-Premise

Group Messaging and Group Management

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

1. Create a group
2. Add members
3. 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 of 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 (as per their member level permissions)
• Only Selected Members can receive (as per their member level permissions)
• Members can receive
• Members can Publish
• One of the active members can receive
• etc

You can dynamically change the group or the member behavior at any point in time by setting group level or member level permissions. It will be instantly applied to the group or group member(s).

Create a Group

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

To create a group, you need to send a group JSON request to the backend API, example below shows a minimal request:

{
  "op":"groupadd",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  
  "group": {
	"name":"My Group",
  }

}

If requires, you can add more parameters in the request. For example,

{
    "op": "groupadd",
    "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",

    "group": {
        "name": "group name",

        "members": {
            "m": "alice,bob,grace",
            "permissions": {
                "send": true,
                "recv": true,
                "pub": true,
                "sub": true,
                "list": true
            }
        },

        "call": {
            "audio": true,
            "video": true,
            "screen": true,
            "vad": true,
            "resolution": 1,
            "maxdur": 0,
            "default": false
        }
    }
}

Following are the request parameters, most of them are OPTIONAL unless the Default value is mentioned as Mandatory.

Group Validity

You can set the duration for which the group is valid.

Setting Group Permissions

Following permissions apply at the group level. You can use these permissions to set communication preferences for the group. Unless otherwise specified, the following are the valid values:

• 0 - All the members
• 1 - Only selected members as per their individual permissions (next section)
• 2 - Anyone (members and non-members). For recv, value 2 sets round-robin.

Setting Group Members, Member Permissions, and Admins

Following settings allow you to manage group members and admins. In addition to that, you can set the member-level permissions. The member level permissions are only applicable when the corresponding group permission setting (previous section) has value 1 (selected members).

Group Call Settings

Group Profile Parameters

You need to use the following parameters only if you are setting profile information from the backend. Generally, the profile information is set by the user/apps using real-time profile APIs.

If the request is successful, the response will be like,

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

where,

• gid = Group ID (GID)

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 groupadd operation.

{
  "op":"groupset",
  "token": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  
  "group": {
	"gid":123
	"name":"My Group",
  }

}

If requires, you can add more parameters in the request as described above in groupadd

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",
    "group": {
        "gid": 111
    },
    "token": "abc123"
}

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 groupadd operation. You MUST pass gid and members object as shown in groupadd operation.

The request and response are the same as 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": "ptlk9hdel1gqxf3p0s15f5f5gtusldej18tl794suzit",
  "count": 50
  "group": {
	"gid":123
  }

}

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.