Skip to main content

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.

tip

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:

  • ss.channels.join - request for the introduction +1 Request
  • ss.channels.cancelJoin - cancellation of the request to enter +1 Request
  • ss.channels.leave - the exit of the participant from the channel +1 Request
  • ss.channels.kick - exclusion of the participant from the channel +1 Request
  • ss.channels.mute - mute player in channel +1 Request
  • ss.channels.unmute - unmute a player +1 Request

Join a Channel​

To join a channel, you must create a request to join. In this case, there can be two development scenarios:

  • Channel is public. Anyone interested can join. Then the player automatically becomes a participant.
  • Channel is private. A request to join is created, which must be accepted by the channel owner or any participant with proper permissions.

Request to Join a Channel​

+1 Request

To create a request to join a channel with the identifier channelId: 123, use the ss.channels.join method:

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

If a password is installed in the channel, then it should be transferred along with the identifier:

ss.channels.join({ channelId: 123, password: 'qwerty' })

You can find out if a channel has a password using the ss.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:

ss.channels.on('join', () => {
  // Successfully entered or applied for the entry
})

Execution with an error:

ss.channels.on('error:join', (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_allowedalready_in_channel
player_bannedalready_requested 💡
internal_errorchannel_capacity_reached
invalid_password 💡
already_in_channel
info

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:

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
})

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:

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

+1 Request

To cancel a request to join a channel with identifier channelId: 123, use the ss.channels.cancelJoin method:

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

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

ss.channels.on('cancelJoin', () => {
  // Successfully canceled the application for membership
})

Execution with an error:

ss.channels.on('error:cancelJoin', (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_allowedjoin_request_not_found 💡
player_banned
internal_error
info

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:

ss.channels.on('event:cancelJoin', (joinRequest) => {
  // Channel ID
  joinRequest.channelId
  // ID of the player who applied to join
  joinRequest.playerId
})

Channel Leave​

+1 Request

To leave a channel with channelId: 123:

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

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

ss.channels.on('leave', () => {
  // Successfully left the channel
})

Execution with an error:

ss.channels.on('error:leave', (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_allowedplayer_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:

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

+1 Request
tip

The owner of the channel cannot be remove from the channel

To exclude member playerId: 123456 from channel channelId: 123:

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

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

ss.channels.on('kick', () => {
  // Successfully excluded
})

Execution with an error:

ss.channels.on('error:kick', (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_bannedplayer_not_in_channel
internal_error

The player leaves the channel and all players in the channel are notified of this event:leave event:

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

+1 Request

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

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

ss.channels.on('error:fetchMembers', (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_allowed
player_banned
internal_error

To additionally load the participants for the same request, there is a convenient method:

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

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

ss.channels.on('error:fetchMoreMembers', (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_allowed
player_banned
internal_error

Mute Player 🔇​

+1 Request
tip

/mute. The owner of the channel cannot be mute

To mute the player playerId: 123456 in the channel channelId: 123 use the ss.channels.mute method:

ss.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
ss.channels.mute({ channelId: 123, playerId: 123456, seconds: 5 * 60 })
info

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:

ss.channels.on('mute', () => {
  // Successfully muted
})

Execution with an error:

ss.channels.on('error:mute', (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_bannedwrong_time_format 💡
internal_error
info

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:

ss.channels.on('event:mute', (mute) => {
  // Channel ID
  mute.channelId
  // ID of mute player
  mute.playerId
  // Date of unmute
  mute.unmuteAt
})

Unmute a Player 🔉​

+1 Request
tip

/unmute

You can re-allow the player playerId: 123456 to write a message in the channel channelId: 123 using the ss.channels.unmute method:

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

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

ss.channels.on('unmute', () => {
  // Successfully unmuted
})

Execution with an error:

ss.channels.on('error:unmute', (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_bannednot_muted
internal_error

At the same time, all members in the channel receive a notification:

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

SpellSync Community Telegram: @spellsync.

For your suggestions e-mail: [email protected]

We Wish you Success!