Members
Overview
When a player joins a guild, group chat or lobby, they become a channel member. The gameplay can be designed in such a way that the player will need to independently initiate or cancel the request to join the channel. A channel member can be excluded, muted, and so on.
The interaction of the member with the channel is, for example, a mechanism for submitting an application for entry into the clan
Below is a complete list of methods implemented to manage the channel participants:
gp.channels.join
- request for the introductiongp.channels.cancelJoin
- cancellation of the request to entergp.channels.leave
- the exit of the participant from the channelgp.channels.kick
- exclusion of the participant from the channelgp.channels.mute
- mute player in channelgp.channels.unmute
- unmute a player
Channel Entry
To join a channel, you must create a request to join. In this case, there can be two development scenarios:
- request for the entry into public channel
gp.channels.on('event:join')
- request for the entry into private channel
gp.channels.on('event:joinRequest')
Request to Enter the Public Channel
To create a request to join a channel with the identifier channelId: 123
, use the gp.channels.join
method:
gp.channels.join({ channelId: 123 });
If a password is installed in the channel, then it should be transferred along with the identifier:
gp.channels.join({ channelId: 123, password: "qwerty" });
You can find out if a channel has a password using the gp.channels.fetchChannel({ channelId: 123 })
method and look at the channel.hasPassword field.
After calling the method, the player automatically joins the channel if the channel was public. If the channel is private, then a request to join is sent and must be accepted. To find out if a channel is private or not, you can look at the channel.private field.
To get the result of the method call, you can subscribe to events:
gp.channels.on("join", () => {
// Successfully entered or applied for the entry
});
Execution with an error:
gp.channels.on("error:join", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | already_in_channel |
player_banned | already_requested 💡 |
internal_error | channel_capacity_reached |
invalid_password 💡 | |
already_in_channel |
already_requested 💡 - already applied for membership. invalid_password 💡 - an error occurs if a password is set for the public channel and the password is incorrect. If the channel is private, then the password is ignored, since the request confirmation mechanism is used by the owner.
Having made a request to join a public channel, the player automatically becomes a member of it and all players in the channel receive a notification about joining:
gp.channels.on("event:join", (member) => {
// Channel ID
member.channelId;
// Joined Player ID
member.id;
// Player fields (avatar, name, custom fields)
member.state;
// Player Mute Information
member.mute;
});
Request to Join a Private Channel
All players in the channel (if they can accept join requests) are notified that a new player is trying to join the channel:
gp.channels.on("event:joinRequest", (joinRequest) => {
// Channel ID
joinRequest.channelId;
// The ID of the player who applied to join
joinRequest.playerId;
// Player fields (avatar, name, custom fields)
joinRequest.player;
// Date of the request to join in the format ISO 8601 UTC "2022-12-01T04:52:26+0000"
joinRequest.date;
});
Players can accept the request using the acceptJoinRequest
method or reject it via rejectJoinRequest
(see the Requests section for more details)).
Cancel Request to Join
To cancel a request to join a channel with identifier channelId: 123
, use the gp.channels.cancelJoin
method:
gp.channels.cancelJoin({ channelId: 123 });
To get the result of a method call, you can subscribe to events:
gp.channels.on("cancelJoin", () => {
// Successfully canceled the application for membership
});
Execution with an error:
gp.channels.on("error:cancelJoin", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | join_request_not_found 💡 |
player_banned | |
internal_error |
join_request_not_found 💡 - the player did not apply for membership or canceled it
If a player cancels a channel join request, all players in the channel (if they can accept join requests) are notified that the join request has been cancelled:
gp.channels.on("event:cancelJoin", (joinRequest) => {
// Channel ID
joinRequest.channelId;
// ID of the player who applied to join
joinRequest.playerId;
});
Channel Leave
To leave a channel with channelId: 123
:
gp.channels.leave({ channelId: 123 });
To get the result of a method call, you can subscribe to events:
gp.channels.on("leave", () => {
// Successfully left the channel
});
Execution with an error:
gp.channels.on("error:leave", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | player_not_in_channel |
player_banned | |
internal_error |
The player leaves the channel, and all players in the channel are notified about this event:leave
event:
gp.channels.on("event:leave", (memberLeave) => {
// Channel ID
memberLeave.channelId;
// ID of the leave player
memberLeave.playerId;
// The reason for the exit: "leave"
memberLeave.reason;
});
Remove a Member from a Channel
The owner of the channel cannot be remove from the channel
To exclude member playerId: 123456
from channel channelId: 123
:
gp.channels.kick({ channelId: 123, playerId: 123456 });
To get the result of the method call, you can subscribe to events:
gp.channels.on("kick", () => {
// Successfully excluded
});
Execution with an error:
gp.channels.on("error:kick", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | player_not_in_channel |
internal_error |
The player leaves the channel and all players in the channel are notified of this event:leave
event:
gp.channels.on("event:leave", (memberLeave) => {
// Channel ID
memberLeave.channelId;
// ID of the leave player
memberLeave.playerId;
// The reason for the leave: "Kick"
memberLeave.reason;
});
Fetch Members
You can see all the players (members) in the desired channel and get all their public data. By joining the chat, the player will see all its participants:
const response = await gp.channels.fetchMembers({
channelId: 10,
// Optional
// Search by ID or name or ID on the site
search: "",
// Search only those on the network
onlyOnline: true,
// How much to request at a time, Max.100
limit: 100,
// How many records can be missed, Max.10,000, used for page navigation or "load more"
offset: 0,
});
To get the result of a method call, you can subscribe to events:
gp.channels.on("fetchMembers", (result) => {
result.items; // An array of the list of participants
result.canLoadMore; // Is it possible to load more participants
result.items.forEach((member) => {
// All fields of the participant
// ID player
member.id;
// Now online
member.isOnline;
// Public fields of the player
member.state;
// For example, name, avatar and score
member.state.name;
member.state.avatar;
member.state.score;
// Information about the player's MUT
member.mute;
// Depressed or not
member.mute.isMuted;
// Meta removal time - Date in ISO 8601, if an empty line is eternal
member.mute.unmuteAt;
});
});
Execution with an error:
gp.channels.on("error:fetchMembers", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | |
player_banned | |
internal_error |
To additionally load the participants for the same request, there is a convenient method:
const response = await gp.channels.fetchMoreMembers({
channelId: 10,
// Optional
// Search by ID or name or ID on the site
search: "",
// Search only those on the network
onlyOnline: true,
// How much to request at a time, Max.100
limit: 100,
});
To get the result of the method call, you can subscribe to events:
gp.channels.on("fetchMoreMembers", (result) => {
result.items; // An array of the list of participants
result.canLoadMore; // Is it possible to load more participants
});
Execution with an error:
gp.channels.on("error:fetchMoreMembers", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | |
player_banned | |
internal_error |
Mute Player 🔇
/mute. The owner of the channel cannot be mute
To mute the player playerId: 123456
in the channel channelId: 123
use the gp.channels.mute
method:
gp.channels.mute({
channelId: 123,
playerId: 123456,
unmuteAt: "2022-12-01T04:52:26+0000",
});
An alternative option with the ability to set the number of seconds for which you want to mute the player:
// mute on 5 minutes
gp.channels.mute({ channelId: 123, playerId: 123456, seconds: 5 * 60 });
The developer independently sets the time for which the player should be muted using unmuteAt
. If no unmuteAt
value is passed, the player is muted indefinitely.
To get the result of the method call, you can subscribe to events:
gp.channels.on("mute", () => {
// Successfully muted
});
Execution with an error:
gp.channels.on("error:mute", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | wrong_time_format 💡 |
internal_error |
wrong_time_format 💡 - the incorrect format of the release of the lock
When a player is muted, all members in the channel receive a notification:
gp.channels.on("event:mute", (mute) => {
// Channel ID
mute.channelId;
// ID of mute player
mute.playerId;
// Date of unmute
mute.unmuteAt;
});
Unmute a Player 🔉
/unmute
You can re-allow the player playerId: 123456
to write a message in the channel channelId: 123
using the gp.channels.unmute
method:
gp.channels.unmute({ channelId: 123, playerId: 123456 });
To get the result of the method call, you can subscribe to events:
gp.channels.on("unmute", () => {
// Successfully unmuted
});
Execution with an error:
gp.channels.on("error:unmute", (err) => {
// Completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | empty_channel_id |
project_not_found | channel_not_found |
origin_not_allowed | access_denied |
player_banned | not_muted |
internal_error |
At the same time, all members in the channel receive a notification:
gp.channels.on("event:unmute", (mute) => {
// Channel ID
mute.channelId;
// ID of unmute player
mute.playerId;
});
Stay in Touch
Other documents of this chapter available Here. To get started, welcome to the Tutorials chapter.
GamePush Community Telegram
: @gs_community.
For your suggestions e-mail
: [email protected]
We Wish you Success!