Groups
A group or clan brings together a bunch of users into a small community or team.
A group is made up of a superadmin, admins, and members. It can be public or private, which determines whether anyone can join the group. Private groups (open=false) are similar to how WhatsApp groups work, a user can only be added when they’re invited to join by one of the group’s admins.
A group also has a maximum member count. This is set to 100 by default if the group is created by the client, or can be overridden if the group is created by the code runtime.
A group user has four states:
| Code | Purpose | |
|---|---|---|
| 0 | Superadmin | There must at least be 1 superadmin in any group. The superadmin has all the privileges of the admin and can additionally delete the group and promote admin members. |
| 0 | Admin | There can be one of more admins. Admins can update groups as well as accept, kick, promote, demote, ban or add members. |
| 0 | Member | Regular group member. They cannot accept join requests from new users. |
| 0 | Join request | A new join request from a new user. This does not count towards the maximum group member count. |
List and filter groups
Groups can be listed using a number of optional filters: name, lang_tag, open and (number of) members. If all filters are omitted, the operation will list all existing groups.
The name filter is case insensitive and mutually exclusive to the remainder filters. It can be useful to help the user look for a specific group by name, and it supports the % wildcard for partial matches as a suffix. As an example, looking for a group that is prefixed with the “Persian” word would be written as persian% name filter.
The remainder filters can be combined or omitted in any way, for instance, we could use the open and members filters to list all open groups with at most the specified amount of members.
The message response for a list of groups contains a cursor. The cursor can be used to quickly retrieve the next set of results.
Join groups
When a user has found a group to join they can request to become a member. A public group can be joined without any need for permission while a private group requires a superadmin or an admin to accept the user.
When a user joins or leaves a group event messages are added to chat history. This makes it easy for members to see what’s changed in the group.
A user who’s part of a group can join group chat and access it’s message history.
The user will receive an in-app notification when they’ve been added to the group. In a private group an admin or superadmin will receive a notification when a user has requested to join.
List a user’s groups
Each user can list groups they’ve joined as a member or an admin or a superadmin. The list also contains groups which they’ve requested to join but not been accepted into yet.
List group members
A user can list all members who’re part of their group. These include other users who’ve requested to join the private group but not been accepted into yet.
Create a group
A group can be created with a name and other optional fields. These optional fields are used when a user lists and filter groups. The user who creates the group becomes the owner and a superadmin for it.
You can also create a group with server-side code. This can be useful when the group must be created together with some other record or feature.
Group metadata
You can store additional fields for a group in group.metadata. This is useful to share data you want to be publicly available to users, and providing additional details usable for listing and filtering groups.
Metadata can also be used to create new functionality on top of existing groups features.
Metadata is limited to 16KB per group and can only be set via the script runtime.
The following example shows how you might use group metadata to extend LayerG’s group member permissions with added roles (as described in the best practices guide). Specifically, we will introduce the concept of a bouncer role which a group member must have in order to kick another member from the group.
Update a group
When a group has been created it’s admins can update optional fields.
Updating group size
Updating a group’s size is an action that can only be performed authoritatively via the server.
Leave a group
A user can leave a group and will no longer be able to join group chat or read message history. If the user is a superadmin they will only be able to leave when at least one other superadmin exists in the group.
Any user who leaves the group will generate an event message in group chat which other members can read.
Manage groups
Each group is managed by one or more superadmins or admins. These users are members with permission to make changes to optional fields, accept or reject new members, remove members or other admins, and promote other members as admins.
Accept new members
When a user joins a private group it will create a join request until an admin accepts or rejects the user. The superadmin or admin can accept the user into the group.
The user will receive an in-app notification when they’ve been added to the group. In a private group an admin will receive a notification about the join request.
To reject the user from joining the group you should kick them.
Promote a member
An admin can promote another member of the group as an admin. This grants the member the same privileges to manage the group. A group can have one or more admins.
Demote a member
An admin can demote another member of the group down a role. This revokes the member of his current privileges to and assigns member the privileges available in the demoted role. Members who are already at the lowest role in their group will not be affected by a demotion.
Kick a member
An admin or superadmin can kick a member from the group. The user is removed but can re-join again later unless the user is banned or the group is private in which case an admin must accept the re-join request.
If a user is removed from a group it does not prevent them from joining other groups. Sometimes a bad user needs to be kicked from the group and banned from re-joining either the group or the whole server. This will prevent the user from being able to connect to the server and interact at all.
Ban a group member
An admin or superadmin can ban a member from the group. The user is kicked from the group and prevented from re-joining or even requesting to re-join.
The user can be unbanned either via the LayerG Console or a runtime code function.
Remove a group
A group can only be removed by one of the superadmins which will disband all members. When a group is removed it’s name can be re-used to create a new group.