Invitations
Overview
With the help of invites, you can manage the addition of players to the channel. Since you can implement chats, guilds, lobbies and much more on the basis of channels, invites become an integral part of them and provide the mechanism for joining somewhere. For example, a player may be asked to join a:
- group or team
- raid
- guild or clan
- community and so on
The mechanics of invites 💡 may be as follows: when a player is going to be invited somewhere, a flashing icon appears in the center of the screen with a proposal to join a chat, group, or raid and basic information about this event. In this case, the player can accept the offer, refuse, ignore, etc.
The mechanics of invites 💡 is given as an example. The GamePush service does not visually display anything, but the developer can implement it on his own
The following is a complete list of methods implemented to manage invites in channels:
gp.channels.sendInvite
- sending an invitationgp.channels.cancelInvite
- cancel sending invitationgp.channels.acceptInvite
- accepting an invitationgp.channels.rejectInvite
- rejection of an invitationgp.channels.fetchInvites
- get a list of invitations to the channelgp.channels.fetchMoreInvites
- additionally load the list of invitations to the channelgp.channels.fetchChannelInvites
- get a list of invitations sent from a channelgp.channels.fetchMoreChannelInvites
- additionally load the list of invitations sent from the channelgp.channels.fetchSentInvites
- get a list of invitations sent from current playergp.channels.fetchMoreSentInvites
- additionally load the list of invitations sent from current player
Sending an Invitation
To send an invite to a player playerId: 123456
in a channel channelId: 123
:
gp.channels.sendInvite({ channelId: 123, playerId: 123456 });
To get the result of a method call, you can subscribe to events:
gp.channels.on('sendInvite', () => {
// Invitation sent
});
Execution with error:
gp.channels.on('error:sendInvite', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | not_invited |
project_not_found | empty_channel_id |
origin_not_allowed | channel_not_found |
player_banned | access_denied |
internal_error | already_in_channel |
already_invited |
The invited player receives an invitation. Other players (if they can invite other players) receive a notification that the player has been sent an invitation:
gp.channels.on('event:invite', (invite) => {
// Channel ID
invite.channelId;
// ID of the player who sent the invitation
invite.playerFromId;
// Player ID who was invited to
invite.playerToId;
// The date the invitation was sent in the format ISO 8601 UTC "2022-12-01T04:52:26+0000"
invite.date;
if (invite.playerToId === gp.player.id) {
// Invited me to the channel
} else {
// In the channel, someone sent someone an invitation
}
});
Cancel Sending an Invitation
To cancel sending an invitation to a player playerId: 123456
in a channel channelId: 123
:
gp.channels.cancelInvite({ channelId: 123, playerId: 123456 });
To get the result of a method call, you can subscribe to events:
gp.channels.on('cancelInvite', () => {
// Invitation sent
});
Execution with error:
gp.channels.on('error:cancelInvite', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | not_invited |
project_not_found | empty_channel_id |
origin_not_allowed | channel_not_found |
player_banned | access_denied |
internal_error | not_invited |
The invited player receives the cancellation of the invite. Other players (if they can invite other players) receive a notification that the invitation has been cancelled:
gp.channels.on('event:cancelInvite', (invite) => {
// Channel ID
invite.channelId;
// ID of the player who sent the invitation
invite.playerFromId;
// Player ID who was invited to
invite.playerToId;
if (invite.playerToId === gp.player.id) {
// The invite sent to me was canceled
} else {
// In my channel, someone canceled the sent invite
}
});
Accepting an Invitation
The player can accept the invitation to the channel channelId: 123
:
gp.channels.acceptInvite({ channelId: 123 });
After that, the player enters the channel. To get the result of a method call, you can subscribe to events:
gp.channels.on('acceptInvite', () => {
// successfully accepted
});
Execution with error:
gp.channels.on('error:acceptInvite', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | not_invited |
project_not_found | empty_channel_id |
origin_not_allowed | channel_not_found |
player_banned | already_in_channel |
internal_error | channel_capacity_reached |
When joining a channel, the invited player 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;
});
Rejecting an Invitation
Player can decline invite from channelId: 123
:
gp.channels.rejectInvite({ channelId: 123 });
To get the result of a method call, you can subscribe to events:
gp.channels.on('rejectInvite', () => {
// successfully rejected
});
Execution with error:
gp.channels.on('error:rejectInvite', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors | Script Errors |
---|---|
player_not_found | not_invited |
project_not_found | empty_channel_id |
origin_not_allowed | channel_not_found |
player_banned | |
internal_error |
All players in the channel (if they can invite other players) receive a notification that the invitation has been cancelled:
gp.channels.on('event:rejectInvite', (invite) => {
// Channel ID
invite.channelId;
// ID of the player who sent the invitation
invite.playerFromId;
// ID of the player who was invited
invite.playerToId;
if (invite.playerFromId === gp.player.id) {
// My invite was rejected
} else {
// Someone declined the sent invitation
}
});
Get a List of Player Invitations to Channels
With the gp.channels.fetchInvites
method, you can get a list of all channels that a player has been invited to:
const response = await gp.channels.fetchInvites({
// how much to request at a time, max. 100
limit: 100,
// how many entries to skip, max. 10000, 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('fetchInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to upload more invites
result.items.forEach((invite) => {
// all fields of the invite
// fields of the channel to which the player is invited
invite.channel
invite.channel.id
invite.channel.tags
invite.channel.projectId
invite.channel.capacity
invite.channel.ownerId
invite.channel.name
invite.channel.description
invite.channel.private
invite.channel.visible
invite.channel.hasPassword
invite.channel.membersCount
// Public fields of the player who invites
invite.playerFrom
invite.playerFrom.id
invite.playerFrom.name
invite.playerFrom.avatar
// and other public fields
// date the invitation was sent, ISO 8601
invite.date
});
});
Execution with error:
gp.channels.on('error:fetchInvites', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors |
---|
player_not_found |
project_not_found |
origin_not_allowed |
player_banned |
internal_error |
To load more invites for the same request, there is a convenient method:
const response = await gp.channels.fetchMoreInvites({
// how much to request at a time, max. 100
limit: 100,
});
To get the result of a method call, you can subscribe to events:
gp.channels.on('fetchMoreInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to load more invites
});
Execution with error:
gp.channels.on('error:fetchMoreInvites', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors |
---|
player_not_found |
project_not_found |
origin_not_allowed |
player_banned |
internal_error |
Get a List of Sent Invitations from a Channel
With the gp.channels.fetchChannelInvites
method, you can get a list of all sent invitations in the selected channel:
const response = await gp.channels.fetchChannelInvites({
// Channel ID
channelId: 123,
// how much to request at a time, max. 100
limit: 100,
// how many entries to skip, max. 10000, used for page navigation or "load more"
offset: 0
});
Mandatory access rights Allow to invite other players
To get the result of a method call, you can subscribe to events:
gp.channels.on('fetchChannelInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to load more invites
result.items.forEach((invite) => {
// all fields of the invite
// Public fields of the player who invites
invite.playerFrom
invite.playerFrom.id
invite.playerFrom.name
invite.playerFrom.avatar
// and other public fields
// Public fields of the player who is invited
invite.playerTo
invite.playerTo.id
invite.playerTo.name
invite.playerTo.avatar
// and other public fields
// date the invitation was sent, ISO 8601
invite.date
});
});
Execution with error:
gp.channels.on('error:fetchChannelInvites', (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 | |
internal_error |
To load more invites for the same request, there is a convenient method:
const response = await gp.channels.fetchMoreChannelInvites({
channelId: 123,
// how much to request at a time, max. 100
limit: 100,
});
To get the result of a method call, you can subscribe to events:
gp.channels.on('fetchMoreChannelInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to load more invites
});
Execution with error:
gp.channels.on('error:fetchMoreChannelInvites', (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 | |
internal_error |
Get a List of Sent Invitations to Players in Channels
You can get a list of invitations sent to players in channels using the method gp.channels.fetchSentInvites
:
const response = await gp.channels.fetchSentInvites({
// how much to request at a time, max. 100
limit: 100,
// how many entries to skip, max. 10000, 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('fetchSentInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to load more invites
result.items.forEach((invite) => {
// all fields of the invite
// fields of the channel to which the other player is invited
invite.channel
invite.channel.id
invite.channel.tags
invite.channel.projectId
invite.channel.capacity
invite.channel.ownerId
invite.channel.name
invite.channel.description
invite.channel.private
invite.channel.visible
invite.channel.hasPassword
invite.channel.membersCount
// Public fields of the player who is invited
invite.playerTo
invite.playerTo.id
invite.playerTo.name
invite.playerTo.avatar
// and other public fields
// date the invitation was sent, ISO 8601
invite.date
});
});
Execution with error:
gp.channels.on('error:fetchSentInvites', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors |
---|
player_not_found |
project_not_found |
origin_not_allowed |
player_banned |
internal_error |
To additionally load invites for the same request, use a convenient method gp.channels.fetchMoreSentInvites
:
const response = await gp.channels.fetchMoreSentInvites({
// how much to request at a time, max. 100
limit: 100,
});
To get the result of a method call, you can subscribe to events:
gp.channels.on('fetchMoreSentInvites', (result) => {
result.items // array of list of invites
result.canLoadMore // is it possible to load more invites
});
Execution with error:
gp.channels.on('error:fetchMoreSentInvites', (err) => {
// completed with an error
});
Possible errors are shown in the table below:
Basic Errors |
---|
player_not_found |
project_not_found |
origin_not_allowed |
player_banned |
internal_error |
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!