Skip to main content

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.

tip

The mechanics of invites 💡 is given as an example. The SpellSync 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:

  • ss.channels.sendInvite - sending an invitation +1 Request
  • ss.channels.cancelInvite - cancel sending invitation +1 Request
  • ss.channels.acceptInvite - accepting an invitation +1 Request
  • ss.channels.rejectInvite - rejection of an invitation +1 Request
  • ss.channels.fetchInvites - get a list of invitations to the channel +1 Request
  • ss.channels.fetchMoreInvites - additionally load the list of invitations to the channel +1 Request
  • ss.channels.fetchChannelInvites - get a list of invitations sent from a channel +1 Request
  • ss.channels.fetchMoreChannelInvites - additionally load the list of invitations sent from the channel +1 Request
  • ss.channels.fetchSentInvites - get a list of invitations sent from current player +1 Request
  • ss.channels.fetchMoreSentInvites - additionally load the list of invitations sent from current player +1 Request

Sending an Invitation​

+1 Request

To send an invite to a player playerId: 123456 in a channel channelId: 123:

ss.channels.sendInvite({ channelId: 123, playerId: 123456 })

To get the result of a method call, you can subscribe to events:

ss.channels.on('sendInvite', () => {
  // Invitation sent
})

Execution with error:

ss.channels.on('error:sendInvite', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundnot_invited
project_not_foundempty_channel_id
origin_not_allowedchannel_not_found
player_bannedaccess_denied
internal_erroralready_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:

ss.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 === ss.player.id) {
    // Invited me to the channel
  } else {
    // In the channel, someone sent someone an invitation
  }
})

Cancel Sending an Invitation​

+1 Request

To cancel sending an invitation to a player playerId: 123456 in a channel channelId: 123:

ss.channels.cancelInvite({ channelId: 123, playerId: 123456 })

To get the result of a method call, you can subscribe to events:

ss.channels.on('cancelInvite', () => {
  // Invitation sent
})

Execution with error:

ss.channels.on('error:cancelInvite', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundnot_invited
project_not_foundempty_channel_id
origin_not_allowedchannel_not_found
player_bannedaccess_denied
internal_errornot_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:

ss.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 === ss.player.id) {
    // The invite sent to me was canceled
  } else {
    // In my channel, someone canceled the sent invite
  }
})

Accepting an Invitation​

+1 Request

The player can accept the invitation to the channel channelId: 123:

ss.channels.acceptInvite({ channelId: 123 })

After that, the player enters the channel. To get the result of a method call, you can subscribe to events:

ss.channels.on('acceptInvite', () => {
  // successfully accepted
})

Execution with error:

ss.channels.on('error:acceptInvite', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundnot_invited
project_not_foundempty_channel_id
origin_not_allowedchannel_not_found
player_bannedalready_in_channel
internal_errorchannel_capacity_reached

When joining a channel, the invited player and all players in the channel receive a notification about joining:

ss.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​

+1 Request

Player can decline invite from channelId: 123:

ss.channels.rejectInvite({ channelId: 123 })

To get the result of a method call, you can subscribe to events:

ss.channels.on('rejectInvite', () => {
  // successfully rejected
})

Execution with error:

ss.channels.on('error:rejectInvite', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundnot_invited
project_not_foundempty_channel_id
origin_not_allowedchannel_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:

ss.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 === ss.player.id) {
    // My invite was rejected
  } else {
    // Someone declined the sent invitation
  }
})

Get a List of Player Invitations to Channels​

+1 Request

With the ss.channels.fetchInvites method, you can get a list of all channels that a player has been invited to:

const response = await ss.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:

ss.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:

ss.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 ss.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:

ss.channels.on('fetchMoreInvites', (result) => {
  result.items // array of list of invites
  result.canLoadMore // is it possible to load more invites
})

Execution with error:

ss.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​

+1 Request

With the ss.channels.fetchChannelInvites method, you can get a list of all sent invitations in the selected channel:

const response = await ss.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
})
tip

Mandatory access rights Allow to invite other players

To get the result of a method call, you can subscribe to events:

ss.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:

ss.channels.on('error:fetchChannelInvites', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied
player_banned
internal_error

To load more invites for the same request, there is a convenient method:

const response = await ss.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:

ss.channels.on('fetchMoreChannelInvites', (result) => {
  result.items // array of list of invites
  result.canLoadMore // is it possible to load more invites
})

Execution with error:

ss.channels.on('error:fetchMoreChannelInvites', (err) => {
  // completed with an error
})

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied
player_banned
internal_error

Get a List of Sent Invitations to Players in Channels​

+1 Request

You can get a list of invitations sent to players in channels using the method ss.channels.fetchSentInvites:

const response = await ss.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:

ss.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:

ss.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 ss.channels.fetchMoreSentInvites:

const response = await ss.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:

ss.channels.on('fetchMoreSentInvites', (result) => {
  result.items // array of list of invites
  result.canLoadMore // is it possible to load more invites
})

Execution with error:

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

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!