Sign In

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 adding 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 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 (as per the member permissions)
  • Only Selected Members can receive (as per the member permissions)
  • 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 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 GID in various real-time API to send messages to the group or making 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",
	"flags":0
  }

}

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

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

    "group": {
        "name": "group name",
        "flags": 0,

        "members": {
            "m": "a,b,c",
            "permissions": {
                "send": true,
                "recv": true,
                "pub": true,
                "sub": true,
                "list": true
            }
        },

        "call": {
            "flags": 0,
            "resolution": 1,
            "maxdur": 0,
            "default": true
        }
    }
}

Following are the request parameters, some of them are OPTIONAL.

  • op = "groupadd"
  • token = Application Token obtained from mesibo console
  • group.name = Group Name [Optional]
  • group.flags = Group Flags (described below) [Optional]
  • group.validity.start = Start time relative to the current time in seconds, default 0 (right now) [Optional]
  • group.validity.duration = Duration/Expiry in seconds, default 1 year [Optional]
  • group.validity.expiryext = Auto-extend expiry on group activity, in seconds. Default disabled. [Optional]
  • group.active = true to enable, false to disable [Optional]
  • group.type = Refer to the section below - Group Permissions per message type [Optional]

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 (refer to the next section)

  • 2 - anyone (members and non-members). For recv, value 2 sets round-robin.

  • group.permissions.send = who can send group messages, default 0 [Optional]

  • group.permissions.recv = who can receive group messages, default 0 [Optional]

  • group.permissions.pub = who can publish video/voice stream to group call, default 0 [Optional]

  • group.permissions.sub = who can subscribe/view video/voice stream of other members, default 0 [Optional]

  • group.permissions.list = who can list active callers in a group call, default 0 [Optional]

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 correspnding group permission setting (previous section) has value 1 (selected member).

  • group.members.m = members to add, comma separated addresses [Optional]

  • group.members.remove = true to remove members, false to add. default false [Optional]

  • group.members.permissions.send = members can send group messages, default true [Optional]

  • group.members.permissions.recv = members can receive group messages, default true [Optional]

  • group.members.permissions.pub = members can publish video/voice stream to group call, default true [Optional]

  • group.members.permissions.sub = members can subscribe/view video/voice stream of other members, default true [Optional]

  • group.members.permissions.list = members can list active callers in a group call, default true [Optional]

  • group.members.admin.owner = member will be owner of the group [Optional]

  • group.members.admin.admin = member will be admin of the group [Optional]

  • group.members.admin.modify = member can modify the group [Optional]

  • group.members.admin.remove = member can remove the group [Optional]

  • group.members.admin.adduser = member can add users to the group [Optional]

  • group.members.admin.remuser = member can remove users from the group [Optional]

  • group.members.admin.addadmin = member can add admins to the group [Optional]

  • group.members.admin.remadmin = member can remove admins from the group [Optional]

  • group.members.admin.remowner = member can remove owners from the group [Optional]

Group Call Settings

  • group.call.flags = Group call flags [Optional]
  • group.call.resolution = Group call video resolution [Optional]
  • group.call.maxdur = Maximum duration of a group Call, default unlimited [Optional]
  • group.call.default = Reset group call values to default [Optional]

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
  • 0x100, Selected can publish
  • 0x200, Anyone can publish
  • 0x1000, Selected can subscribe
  • 0x2000, Anyone can subscribe
  • 0x10000, Selected can get list of participants
  • 0x20000, Anyone can get list of participants

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",
	"flags":0
  }

}

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

  • op = "groupset"

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"
}
  • op = "groupdel"

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.

  • op = "groupeditmembers"

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.