Skip to main content

Channel Management

Overview​

Methods for managing channels are considered:

  • ss.channels.createChannel - channel creation +1 Request
  • ss.channels.updateChannel - channel update +1 Request
  • ss.channels.deleteChannel - deleting a channel +1 Request
  • ss.channels.fetchChannel - get channel information by ID +1 Request
  • ss.channels.fetchChannels - get channel list by id +1 Request
  • ss.channels.fetchMoreChannels - additionally load the list of channels +1 Request
info

In real time, you can track any actions of other players in the channel: they wrote a message, joined or invited to the channel, etc.

Create a Channel​

+1 Request

The player can create channels only from templates preinstalled by the developer. When creating a channel, the player automatically joins it.

The ss.channels.createChannel method is used to create a channel. As an example, we will show the creation of a channel - a group for passing the Demons Lord Castle dungeon for 5 people x5 in the heroic difficulty heroic.

tip

Channel fields are editable if editable in template

ss.channels.createChannel({
  // required ID or channel template tag
  template: 'DUNGEON_5',
  // optional tags by which you can find the channel
  tags: ['dungeon', 'x5', 'demons_lord_castle', 'heroic'],
  // maximum number of people in the channel
  capacity: 5,
  // channel name
  name: 'Dungeon Demons Lord Castle',
  // channel description
  description: 'fast, need all',
  // entrance by invitation only or free
  private: true,
  // the channel is visible in the search or is available only by direct request
  visible: true,
  // login password
  password: '',
  // channel owner access
  ownerAcl: {
    // can read messages
    canViewMessages: true,
    // can create messages
    canAddMessage: true,
    // can change messages
    canEditMessage: true,
    // can delete messages
    canDeleteMessage: true,
    // can view members
    canViewMembers: true,
    // can invite other players
    canInvitePlayer: true,
    // can remove players
    canKickPlayer: true,
    // can accept requests to join
    canAcceptJoinRequest: true,
    // can mute players
    canMutePlayer: true
  },
  // channel member access
  memberAcl: {
    // can read messages
    canViewMessages: true,
    // can create messages
    canAddMessage: true,
    // can change messages
    canEditMessage: true,
    // can delete messages
    canDeleteMessage: true,
    // can view members
    canViewMembers: true,
    // can invite other players
    canInvitePlayer: false,
    // can remove players
    canKickPlayer: false,
    // can accept requests to join
    canAcceptJoinRequest: false,
    // can mute players
    canMutePlayer: false
  },
  // channel guest access
  guestAcl: {
    // can read messages
    canViewMessages: false,
    // can create messages
    canAddMessage: false,
    // can change messages
    canEditMessage: false,
    // can delete messages
    canDeleteMessage: false,
    // can view members
    canViewMembers: false,
    // can invite other players
    canInvitePlayer: false,
    // can remove players
    canKickPlayer: false,
    // can accept requests to join
    canAcceptJoinRequest: false,
    // can mute players
    canMutePlayer: false
  }
})

Install the password of the channel by passing the line with a password, for example, password: '123'. You can remove the password by passing the empty line password: ''.

info

Flexibly use the capabilities of the channels allow tags and templates channels.

All Fields of the Channel​

To get the result of the call of the method ss.channels.createChannel, you can subscribe to events:

ss.channels.on('createChannel', (channel) => {
  // all fields of the channel
  channel.id
  channel.tags
  channel.messageTags
  channel.templateId
  channel.capacity
  channel.ownerId
  channel.name
  channel.description
  channel.private
  channel.visible
  channel.permanent
  channel.hasPassword
  channel.isJoined
  channel.isRequestSent
  channel.isInvited
  channel.isMuted
  channel.password
  channel.membersCount
  channel.ownerAcl
  channel.memberAcl
  channel.guestAcl
})

Example of execution with an error:

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

Possible errors are given in the table below:

Basic ErrorsScenario Errors
player_not_foundempty_channel_template_id
project_not_foundchannel_template_not_found
origin_not_allowedchannel_tag_forbidden 💡
player_banned
internal_error
tip

channel_tag_forbidden 💡 - channel tags contain reserved system tags. System tags begin with @, for example @feed: 123456

Create a Channel from the Control Panel​

To create a channel from the SpellSync control panel, go to the Channels and press the Add channel button:

The names of the fields available for editing in the channel are given in the table below:

Field NameComments
📝 Channel TemplateSee more in section Template
📝 TagsChannel tags are used to simplify the search player in the in-game events.For example, a group for going to a dungeon for 5 people can have dungeon and x5 tags.See more in the section Tags of Channels and Messages
📝 Tags of messagesMessages tags allow you to display logs or specified types of chat messages.For example, all messages with log tags can return information about the level of level. See more in the section Tags of Channels and Messages
📝 Channel nameClicking on the Edit translations button opens the entire list of languages available for translation
📝 Channel descriptionClicking on the Edit translations button opens the entire list of languages available for translation
📝 The maximum number of membersInteger, maximum number of channel members is unlimited
📝 PasswordBy default, the channel is created without a password
🔘 PrivateAllows you to join the channel only through Request or Invites
🔘 Keep historyAllows you to store your message history (only available on subscription plans). By default, messages are stored for 24 hours
🔘 Visible in searchShows the channel in the search results
🔘 Visible only in test version 💡The channel is not visible to players in the production version
🔘 Leave the channel when he leaves the game
🔘 Delete channel when last member leaves
🔘 Permissions for the player - owner to edit channel optionsBy default, channel owner can edit: title, description, tags, change owner, channel capacity, privacy, visibility, owner ACL, guest ACL
🔘 Owner, member, guest accessFor a complete list of permissions and their default values, see table
info

If you leave the default settings, then the created channel can be used as a player chat

Access of Roles in Channel​

MethodAllow toownerAcl ownermemberAcl memberguestAcl guest
canViewMessagesread messagestrue 🔘true 🔘false ⚪
canAddMessagecreate messagestrue 🔘true 🔘false ⚪
canEditMessagechange messagestrue 🔘true 🔘false ⚪
canDeleteMessagedelete messagestrue 🔘true 🔘false ⚪
canViewMembersview participantstrue 🔘true 🔘false ⚪
canInvitePlayerinvite other playerstrue 🔘false ⚪false ⚪
canKickPlayerdelete playerstrue 🔘false ⚪false ⚪
canAcceptJoinRequestaccept join requeststrue 🔘false ⚪false ⚪
canMutePlayermute playerstrue 🔘false ⚪false ⚪

To manage the rights of players in the channel, select the control panels Channels - Change - Accesses of the player - owner / member / guest:

Channel Update​

+1 Request

To update the channel with the channelId: 123 using the method ss.channels.updateChannel:

ss.channels.updateChannel({ channelId: 123, visible: false })

Transfer the channel to another player:

ss.channels.updateChannel({ channelId: 123, ownerId: 123456 })

Full list of options:

ss.channels.updateChannel({
  // required channel ID to update
  channelId: 123,
  // tags by which you can find the channel
  tags: ['dungeon', 'x5', 'demons_lord_castle', 'heroic'],
  // maximum number of people in the channel
  capacity: 5,
  // channel name
  name: 'Dungeon Demons Lord Castle',
  // channel description
  description: 'fast, need all',
  // entrance by invitation only or free
  private: true,
  // the channel is visible in the search or is available only by direct request
  visible: true,
  // login password
  password: '',
  // new owner ID
  ownerId: 123456,
  // channel owner access
  ownerAcl: {
    // can read messages
    canViewMessages: true,
    // can create messages
    canAddMessage: true,
    // can change messages
    canEditMessage: true,
    // can delete messages
    canDeleteMessage: true,
    // can view members
    canViewMembers: true,
    // can invite other players
    canInvitePlayer: true,
    // can remove players
    canKickPlayer: true,
    // can accept requests to join
    canAcceptJoinRequest: true,
    // can mute players
    canMutePlayer: true
  },
  // channel member access
  memberAcl: {
    // can read messages
    canViewMessages: true,
    // can create messages
    canAddMessage: true,
    // can change messages
    canEditMessage: true,
    // can delete messages
    canDeleteMessage: true,
    // can view members
    canViewMembers: true,
    // can invite other players
    canInvitePlayer: false,
    // can remove players
    canKickPlayer: false,
    // can accept requests to join
    canAcceptJoinRequest: false,
    // can mute players
    canMutePlayer: false
  },
  // channel guest access
  guestAcl: {
    // can read messages
    canViewMessages: false,
    // can create messages
    canAddMessage: false,
    // can change messages
    canEditMessage: false,
    // can delete messages
    canDeleteMessage: false,
    // can view members
    canViewMembers: false,
    // can invite other players
    canInvitePlayer: false,
    // can remove players
    canKickPlayer: false,
    // can accept requests to join
    canAcceptJoinRequest: false,
    // can mute players
    canMutePlayer: false
  }
})

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

ss.channels.on('updateChannel', (channel) => {
  // all fields of the channel
  channel.id
  channel.tags
  channel.messageTags
  channel.channelId
  channel.capacity
  channel.ownerId
  channel.name
  channel.description
  channel.private
  channel.visible
  channel.permanent
  channel.hasPassword
  channel.isJoined
  channel.isRequestSent
  channel.isInvited
  channel.isMuted
  channel.password
  channel.membersCount
  channel.ownerAcl
  channel.memberAcl
  channel.guestAcl
})

Execution with an error:

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

Possible errors are given in the table below:

Basic ErrorsScenario Errors
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied 💡
player_bannedchannel_tag_forbidden 💡
internal_error
info

access_denied 💡 - the player is not the owner, so he has no editing rights. channel_tag_forbidden 💡 - Channel tags contain reserved system tags. System tags begin with @, for example @feed:123456

When updating the channel , all players in the channel come a notification of its change:

ss.channels.on('event:updateChannel', (channel) => {
  // Channel ID
  channel.id
  // Channel tags
  channel.tags
  // Channel tags
  channel.messageTags
  // The maximum number of participants
  channel.capacity
  // The owner of the channel
  channel.ownerId
  // Channel name
  channel.name
  // Channel description
  channel.description
  // Channel privacy
  channel.private
  // Visibility of the channel
  channel.visible
  // The channel has a password
  channel.hasPassword
  // Access of the owner of the channel
  channel.ownerAcl
  // Access of the channel member
  channel.memberAcl
  // Access of the guest of the channel
  channel.guestAcl
})

Delete the Channel​

+1 Request
caution

When removing the channel, the same ones are deleted: all messages, channel participants, invites and requests for joining the channel

To delete the channel with the identifier ChannelId: 123, use the method ss.channels.deleteChannel:

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

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

ss.channels.on('deleteChannel', () => {
  // The channel is deleted
})

Execution with an error:

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

Possible errors are given in the table below:

Basic ErrorsScenario Errors
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowedaccess_denied 💡
player_banned
internal_error
info

access_denied 💡 - the player is not the owner, so he has no rights to remove the channel

When removing the channel, all players in the channel come a notification about this event:

ss.channels.on('event:deleteChannel', (channel) => {
  // Channel ID
  channel.id
})

Get Channel Information by ID​

+1 Request

To get information about a channel by ID, use the method ss.channels.fetchChannel:

const response = await ss.channels.fetchChannel({
  // Channel ID
  channelId: 123
})

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

ss.channels.on('fetchChannel', (result) => {
  // Channel fields
  channel.id
  channel.tags
  channel.templateId
  channel.capacity
  channel.ownerId
  channel.name
  channel.description
  channel.private
  channel.visible
  channel.hasPassword
  channel.membersCount
})

Execution with an error:

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

Possible errors are given in the table below:

Basic ErrorsScenario Errors
player_not_foundempty_channel_id
project_not_foundchannel_not_found
origin_not_allowed
player_banned
internal_error

Fetch List of Channel​

+1 Request

To get a list of channels, you can use the method ss.channels.fetchChannels:

const response = await ss.channels.fetchChannels({
  // List of channel identifiers
  ids: [123, 124, 125],
  // Tags of channels for filtering, through (&)
  tags: ['chat', 'trade'],
  // Search by ID or channel name
  search: '',
  // Search for channels only in which there is my player
  onlyJoined: true,
  // Search for channels only in which my player is the owner of the channel
  onlyOwned: 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 the method call, you can subscribe to events:

ss.channels.on('fetchChannels', (result) => {
  result.items // An array of the list of channels
  result.canLoadMore // Is it possible to load more channels

  result.items.forEach((channel) => {
    // Channel fields
    channel.id
    channel.tags
    channel.templateId
    channel.capacity
    channel.ownerId
    channel.name
    channel.description
    channel.private
    channel.visible
    channel.hasPassword
    channel.membersCount
  })
})

Execution with an error:

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

Possible errors are given in the table below:

Basic Errors
player_not_found
project_not_found
origin_not_allowed
player_banned
internal_error

To additionally load list of channels by the same request, there is a convenient method ss.channels.fetchMoreChannels:

const response = await ss.channels.fetchMoreChannels({
  // Channel ID
  channelId: 123,
  // Tags of messages for filtering, through (&)
  tags: ['chat', 'trade'],
  // 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('fetchMoreChannels', (result) => {
  result.items // An array of the list of channels
  result.canLoadMore // Is it possible to load more channels
})

Execution with an error:

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

Possible errors are given 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!