Mesibo Group Management APIs

Estimated reading time: 19 minutes

Mesibo group management APIs allow you to create and manage groups for enabling group chat, group calls, and conferencing between group members. It is highly recommended that you are familiar with messaging and profile APIs before reading this section.

A group has 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. Similarly, you can initiate a video or voice conference between group members. You can create groups of any size without any restrictions.

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

  • Normal group: any group member can send and receive messages to a group or participate in the conference.

  • 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 or publish a live stream to the conference.

  • 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 messages or make group calls
  • Members can send messages or make group calls
  • Only selected members can send messages or make group calls
  • Only Selected Members can receive messages or group calls
  • Members can receive messages or group calls
  • Members can list other conference publishers
  • 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).

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

  1. Create a group

  2. Add members (or allow usres to add themselves by using a PIN)

  3. Start sending messages or make group calls

Let’s learn more about creating group and adding members in the next section. You can refer to messaging or conferencing section to learn more about how to create group chat or conferencing between group members.

Group Management APIs

There are mainly three types of group operations

  1. Creating a Group
  2. Group members Managements (adding, removing, leaving)
  3. Group Administration - changing settings, profile information (name, description, picture, etc), permissions, pins, etc.

Creating a Group

You can create a new group by calling createGroup API. It will send a request to the server to create a new group. When a group is created, Mesibo_onGroupCreated callback function in the listener will be called with the group profile. You can then add members to the group using group profile APIs. Note that, you will be already added as the owner and the member of the group and hence you should not add yourself again.

boolean createGroup(MesiboGroupSettings settings, GroupListener listener)

boolean createGroup(String name, long flags, GroupListener listener)

createGroup takes the following parameters:

Parameter Description
settings Group settings object
name Name of the group
flags Group flags, you can pass 0 unless you have specific requirements as mentioned below
listener listener which will be called when group is created (explained later). Note that, if you are using Javascript, you can pass listener or a callback function. For all other platforms, it is the listener.

Group settings class MesiboGroupSettings has following members:

Member Description
name Name of the group
flags Group flags, you can pass 0 unless you have specific requirements as mentioned below
callFlags Group Call Flags, default 0
videoResolution Group Call video resolution, default MESIBO_RESOLUTION_DEFAULT
callDuration Maximum call duration, default 0 for no restrictions on the call duration
listener listener which will be called when group is created (explained later). Note that, if you are using Javascript, you can pass listener or a callback function. For all other platforms, it is the listener.

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

Flag Description
0 Normal group, only members can send and receive, and participate in the conference
MESIBO_GROUPFLAG_SENDBYSELECTED Only selected members can send (refer add members API below)
MESIBO_GROUPFLAG_SENDBYANYONE Anyone can send
MESIBO_GROUPFLAG_RECVBYSELECTED Only selected members can receive (refer add members API below)
MESIBO_GROUPFLAG_RECVROUNDROBIN Received by one member in the round-robin fashion
MESIBO_GROUPFLAG_NOSTORAGE Do no store group messages
MESIBO_GROUPFLAG_PUBBYSELECTED Only selected members can publish their streams (video/audio) to the conference (refer to the conference APIs to learn more)
MESIBO_GROUPFLAG_PUBBYANYONE Anyone can publish their streams to the conference (refer to the conference APIs to learn more)
MESIBO_GROUPFLAG_SUBBYSELECTED Only selected members can subscribe (view/listen) to streams in the conference (refer to the conference APIs to learn more)
MESIBO_GROUPFLAG_SUBBYANYONE Anyone can subscribe (view/listen) to streams in the conference (refer to the conference APIs to learn more)
MESIBO_GROUPFLAG_LISTBYSELECTED Only selected members can get the list of streams in the conference (refer to the conference APIs to learn more)
MESIBO_GROUPFLAG_LISTBYANYONE Anyone can get the list of streams in the conference (refer to the conference APIs to learn more)

In Java,

MesiboGroupProfile.GroupSettings settings = new MesiboGroupProfile.GroupSettings();
settings.name = "My Group";
settings.flags = 0;

Mesibo.createGroup(settings, this);

In Kotlin

var settings:MesiboGroupProfile.GroupSettings = MesiboGroupProfile.GroupSettings()
settings.name = "My Group"
settings.flags = 0

Mesibo.createGroup(settings, this)

In Objective-C,

MesiboGroupSettings *settings = [MesiboGroupSettings new];
settings.name = @"My Group";
settings.flags = 0;

[MesiboInstance createGroup:settings listener:self];

In Swift,

let settings:MesiboGroupSettings = MesiboGroupSettings();
settings.name = "My Group";
settings.flags = 0;

Mesibo.getInstance().createGroup(settings, listener: self)

In Javascript

var settings = {};
settings.name = "My Group";
settings.flags = 0;

Mesibo.createGroup(settings, function(p) {
});

Adding Group Members and Admins

You can add members, and admins to the group by calling addMembers API of the group profile. You need to pass the addresses of the users to be added as group members, permissions to be granted and admin permissions if you are adding them as group admins.

You call the same API for adding members or modifying their member and admin permissions.

When you add members or make them admin, they will be immediately notified by a listener function (explained later).

int addMembers(String[] addresses, MesiboMemberPermissions permissions)

int addMember(String address, MesiboMemberPermissions permissions)

addMembers takes the following parameters:

Parameter Description
addresses Array of User addresses to be added as group members
address A User address to be added as group members
permissions Member Permissions object describing permissions to grant to the member (refer below)

Member permissions class MesiboMemberPermissions has following members:

Member Description
flags Member Permissions (refer to the table below)
adminFlags Admin Permissions (refer to the table below) if you are adding members as admin, pass 0 otherwise. You need to have the necessary admin permissions to add other users as admin
callFlags Group Call Flags overriding the one set in the Group Settings, default 0
videoResolution Group Call video resolution overriding the one set in the Group Settings, default MESIBO_RESOLUTION_DEFAULT
callDuration Maximum call duration overriding the one set in the Group Settings

Permissions can be a logical OR combination of one or more permission values below:

Flag Description
MESIBO_MEMBERFLAG_SEND Member(s) can send messages to the group
MESIBO_MEMBERFLAG_RECV Member(s) can recv messages from the group
MESIBO_MEMBERFLAG_PUBL Member(s) can publish video/voice to the group conference
MESIBO_MEMBERFLAG_SUBS Member(s) can subscribe to video/voice from the group conference
MESIBO_MEMBERFLAG_LIST Member(s) can get list of publishers from the group conference
MESIBO_MEMBERFLAG_RECORD Member(s) can record the group conference
MESIBO_MEMBERFLAG_ALL All permissions

Admin Permissions can be a logical OR combination of one or more permission values below:

Flag Description
MESIBO_ADMINFLAG_MODIFY Member(s) can modify the group profile
MESIBO_ADMINFLAG_ADDUSER Member(s) can add other users to the group
MESIBO_ADMINFLAG_REMUSER Member(s) can remove other users from the group
MESIBO_ADMINFLAG_ADDADMIN Member(s) can add other users as admin to the group
MESIBO_ADMINFLAG_REMADMIN Member(s) can remove other admins from the group
MESIBO_ADMINFLAG_REMOWNER Member(s) can remove owner from the group
MESIBO_ADMINFLAG_REMGROUP Member(s) can remove the group
MESIBO_OWNERFLAG_ALL Member(s) have all the permissions
MESIBO_ADMINFLAG_ALL Member(s) have all the permissions except removing owner

For example, use the following code to add members to a group. The profile in the code below is the MesiboProfile object for a group obtained by calling getProfile or createGroup APIs. Refer to the Profile APIs for more information.

In Java,

MesiboGroupProfile gp = profile.getGroupProfile();

MesiboGroupProfile.MemberPermissions permissions = new MesiboGroupProfile.MemberPermissions();
permissions.flags = MesiboGroupProfile.MEMBERFLAG_ALL;
permissions.adminFlags = 0;
gp.addMember(address, permissions);

In Kotlin

val gp = profile.groupProfile

var permissions: MesiboGroupProfile.MemberPermissions = MesiboGroupProfile.MemberPermissions();
permissions.flags = MesiboGroupProfile.MEMBERFLAG_ALL.toLong()
permissions.adminFlags = 0;
gp.addMembers(members, permissions)

In Objective-C,

MesiboGroupProfile *gp = [profile getGroupProfile];

MesiboMemberPermissions *permissions = [MesiboMemberPermissions new];
permissions.flags = MESIBO_MEMBERFLAG_ALL;
permissions.adminFlags = 0;
[gp addMembers:members permissions:mp];

In Swift,

let gp = profile?.getGroupProfile()

let permissions:MesiboMemberPermissions = MesiboMemberPermissions();
permissions.flags = UInt32(MESIBO_MEMBERFLAG_ALL);
permissions.adminFlags = 0;
gp?.addMembers(members, permissions:mp)

In Javascript

var gp = profile.getGroupProfile();

var permissions = {};
permissions.flags = MESIBO_MEMBERFLAG_ALL;

gp.addMember(address, permissions);

Removing Group Members and Admins

You can remove members, and admins from the group by calling removeMembers API of the group profile. You need to have the necessary admin permissions as described above to remove other users and admins from the group.

When you remove members, they will be immediately notified by a listener function (explained later).

int removeMembers(String[] addresses)

int removeMember(String address)

removeMembers takes the following parameters:

Parameter Description
addresses Array of User addresses to be removed from the group
address Address of the User to be removed from the group

Get Group Members

You can get group members and admins by calling getMembers API of the group profile. When you call getMembers API, Mesibo_onGroupMembers callback function in the listener will be called with the array of Group Members.

int getMembers(int count, boolean restart, GroupListener listener);

getMembers takes the following parameters:

Parameter Description
count Number of members to get from the group
restart Get members from the beginning
listener Group listener instance which will be called when group members are retrived. Note that, if you are using Javascript, you can pass listener or a callback function. For all other platforms, it is the listener.

Get Group Settings and Permissions

You can get group settings, permissions and PINs (only if admin) getSettings API of the group profile. When you call getSettings API, Mesibo_onGroupSettings callback function in the listener will be called with settings, permissions and PINs. If you are not a member, Mesibo_onGroupError callback function in the listener will be called with an error code.

void getSettings(GroupListener listener);

getSettings takes the following parameters:

Parameter Description
listener Group listener instance which will be called when group settings are retrived. Note that, if you are using Javascript, you can pass listener or a callback function. For all other platforms, it is the listener.

Delete Group

You can delete the group by calling deleteGroup API of the group profile. You need to have the necessary admin permissions to delete a group.

void deleteGroup();

deleteGroup does not take any parameters.

Get Admin for the last admin action

You can get the admin who has performed the last admin action like modifying the group, adding/removing members, etc. by calling getLastAdmin API of the group profile. You can call getLastAdmin API from any listener function to know who initiated the action.

MesiboProfile getLastAdmin();

getLastAdmin does not take any parameters.

PIN-based Group Management

The PINs based group management allows users to add themselves to a group by using a numerical PIN. The group admin can create a PIN with the necessary permissions and publish it to users so that they can join the group. The group admin can create multiple PINs with a different set of permissions. For example, the group admin can create a PIN that only allows limited functionality (say only to receive messages or group calls), while another PIN gives full functionalities like sending and receiving messages, making groups calls, etc.

Creating a PIN

The group owner or an admin with the necessary permissions can add a PIN for the group by calling the addPin API of the group profile. If the PIN is successfully added, Mesibo_onGroupSettings callback function in the listener will be called with settings, permissions, and PINs. If not, Mesibo_onGroupError callback function in the listener will be called with an error code.

void addPin(MesiboMemberPermissions permissions, GroupListener listener, long expiry, long count)

void addPin(MesiboMemberPermissions permissions, GroupListener listener)

addPin takes the following parameters:

Parameter Description
permissions Member Permissions object describing permissions to grant to the member using this PIN (refer adding members description above)
listener Group listener instance which will be called when group settings are retrived. Note that, if you are using Javascript, you can pass listener or a callback function. For all other platforms, it is the listener.
expiry Expiry in seconds, default 0 for unlimited
count Maximum number of times this PIN can be used, default 0 for unlimited

Joing a group using a PIN

Users can add themselves to a group by calling the join API of the group profile with the PIN. If successful, Mesibo_onGroupJoined callback function in the listener will be called. If not, Mesibo_onGroupError callback function in the listener will be called with an error code.

void join(long pin, GroupListener listener)

Modifying a PIN

The group owner or an admin with the necessary permissions can modify a PIN by calling the editPin API of the group profile.

void editPin(long pin, MesiboMemberPermissions permissions, GroupListener listener, long expiry, long count)

Refer to the addPin description above for the description of the parameters.

Removing a PIN

The group owner or an admin with the necessary permissions can remove a PIN by calling the removePin API of the group profile.

void removePin(long pin)

Modifying a Group Profile

You also modify a group profile by calling profile setters as explained in Profiles API section.

Group Listeners

Your app can implement the Mesibo.GroupListener to be notified of group events. The following listeners are a part of Mesibo.GroupListener:

Mesibo_onGroupCreated

Mesibo_onGroupCreated is called with the group profile when you create a group by calling createGroup API.

Mesibo_onGroupJoined

Mesibo_onGroupJoined is called with the group profile when you are added to the group

Mesibo_onGroupLeft

Mesibo_onGroupLeft is called with the group profile when you leave or removed from the group

Mesibo_onGroupMembers

Mesibo_onGroupMembers is called with the group profile and an array of members when you call getMembers API of group profile

Mesibo_onGroupMembersJoined

Mesibo_onGroupMembersJoined is called with the group profile and an array of members when new members or admins are added to the group

Mesibo_onGroupMembersRemoved

Mesibo_onGroupMembersRemoved is called with the group profile and an array of members when members or admins are removed from the group

Mesibo_onGroupSettings

Mesibo_onGroupMembersSettings is called with the group settings, permissions and pins when you call getSettings or addPin of group profile

Mesibo_onGroupError

Mesibo_onGroupMembersError is called with the error code when if any error in the group operations

Once you implement Mesibo.GroupListener, add that as a global group listener as follow. You can also pass listener to individual functions as required:

Mesibo.addListener(this);

Special Groups

In addition to groups you have created, mesibo provides a few special groups which always exist for each app you create. These groups make it easy to reach the different combinations of contacts and subscribers.

For example, you can send messages to all users who have subscribed to your profile update by sending messages to MESIBO_GROUP_SUBSCRIBERS without any additional coding. The members of these special groups are dynamically updated in real-time depending on the type of the group, and you don’t need to do any coding to reach these special audiences.

Following are the special groups.

Group ID Description
MESIBO_GROUP_SUBSCRIBERS All Profile Subscribers (refer to the profile APIs to known more about contacts and subscribers)
MESIBO_GROUP_KNOWNSUBSCRIBERS All Contacts who have subscribed to the profile updates (refer to the profile APIs to known more about contacts and subscribers)
MESIBO_GROUP_PROVSUBSCRIBERS All Transient (Provisional) Subscribers
MESIBO_GROUP_KNOWNPROVSUBSCRIBERS All Contacts who are also Transient (Provisional) Subscribers
MESIBO_GROUP_SUBSCRIBERSALL All Subscribers (profile and transient)
MESIBO_GROUP_KNOWNSUBSCRIBERSALL All Contacts who are also Subscribers (profile and transient)
MESIBO_GROUP_CONTACTS All Contacts
MESIBO_GROUP_CONTACTSUBSCRIBERS All Contacts and Subscribers
MESIBO_GROUP_SUBSCRIBED All users you have subscribed to
MESIBO_GROUP_PROSUBSCRIBED All users you have provisionally subscribed to
group messaging, api