Mesibo Backend APIs - Group Management

Estimated reading time: 11 minutes

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": {
            "flags": 0,
            "resolution": 1,
            "maxdur": 0,
            "default": true
        }
    }
}

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

Parameter Description Default
op MUST have the value - “groupadd” (see example above) Mandatory
token Application Token obtained from the mesibo console Mandatory
group.name Group Name Empty
group.active true to enable, false to disable true
group.type Refer to the section below - Group Permissions per message type  

Group Validity

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

Parameter Description Default
group.validity.start Start time relative to the current time in seconds 0 (right now)
group.validity.duration Duration/Expiry in seconds 1 year
group.validity.expiryext Auto-extend expiry on group activity, in seconds disabled

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.
Parameter Description Default
group.permissions.send who can send group messages 0
group.permissions.recv who can receive group messages 0
group.permissions.pub who can publish video/voice stream to group call 0
group.permissions.sub who can subscribe/view video/voice stream of other members 0
group.permissions.list who can list active callers in a group call 0

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).

Parameter Description Default
group.members.m members to add, comma separated addresses  
group.members.remove true to remove members, false to add false
group.members.permissions.send members can send group messages true
group.members.permissions.recv members can receive group messages true
group.members.permissions.pub members can publish video/voice stream to group call true
group.members.permissions.sub members can subscribe/view video/voice stream of other members true
group.members.permissions.list members can list active callers in a group call true
group.members.admin.owner member will be owner of the group false
group.members.admin.admin member will be admin of the group false
group.members.admin.modify member can modify the group false
group.members.admin.remove member can remove the group false
group.members.admin.adduser member can add users to the group false
group.members.admin.remuser member can remove users from the group false
group.members.admin.addadmin member can add admins to the group false
group.members.admin.remadmin member can remove admins from the group false
group.members.admin.remowner member can remove owners from the group false

Group Call Settings

Parameter Description Default
group.call.flags Group call flags false
group.call.resolution Group call video resolution 0
group.call.maxdur Maximum duration of a group Call 0 - unlimited
group.call.default Reset group call values to default false

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.

Parameter Description Default
group.profile.name Name of the group  
group.profile.image Image URL of the group  
group.profile.tn base64 thumbnail of the group image  
group.profile.status Status text of the group  
group.profile.description Description text of the group  

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

Parameter Description Default
op MUST have the value - “groupset” (see example above) Mandatory
token Application Token obtained from the mesibo console Mandatory
group.gid Group ID of the group to be modified Mandatory

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"
}
Parameter Description Default
op MUST have the value - “groupdel” (see example above) Mandatory
token Application Token obtained from the mesibo console Mandatory
group.gid Group ID of the group to be deleted Mandatory

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.

Parameter Description Default
op MUST have the value - “groupeditmembers” Mandatory
token Application Token obtained from the mesibo console Mandatory
group.gid Group ID of the group Mandatory

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.

chat api backend, server-side api guide, chat app backend references, mesibo backend api, php, rest api