Skip to main content

Messages

Overview

Players in a channel can exchange messages. At the same time, it is possible to implement sending a personal message, as well as messages to a feed or channel. Implemented methods that allow you to change and delete sent messages. Messages can also be used to send gifts to players or even turn-based battles.

This section covers methods for working with messages. The service allows you to send, change, delete messages and much more:

  • ss.channels.sendMessage - sending the message to the channel +1 Request
  • ss.channels.sendPersonalMessage - sending a personal message to the player +1 Request
  • ss.channels.sendFeedMessage - sending a message to a feed +1 Request
  • ss.channels.editMessage - change the sent message +1 Request
  • ss.channels.deleteMessage - delete the sent message +1 Request
  • ss.channels.fetchMessages - get a list of messages in the selected channel +1 Request
  • ss.channels.fetchMoreMessages - additionally load messages in the channel +1 Request
  • ss.channels.fetchPersonalMessages - get a list of private messages +1 Request
  • ss.channels.fetchMorePersonalMessages - additional download private messages +1 Request
  • ss.channels.fetchFeedMessages - get a list of posts in a player's feed +1 Request
  • ss.channels.fetchMoreFeedMessages - additionally load messages in the feed +1 Request

Sending a Message

+1 Request

To send a Hello! message to the channel channelId: 123, use the ss.channels.sendMessage method:

ss.channels.sendMessage({
// Channel ID
channelId: 123,
// Message text
text: 'Hello!',
// Tags of messages for convenient filtration, optional
tags: ['chat', 'trade']
})

Sending a Private Message and to the Player's Feed

+1 Request

There is an option to send a private message to the player and send a message to the feed.

tip

Feed - a player's public channel, to which any member of the channel can send a message

To send a private message Hello! to the player playerId: 123456, use the method ss.channels.sendPersonalMessage:

ss.channels.sendPersonalMessage({
// ID player
playerId: 123,
// Message text
text: 'Hello!',
// Tags of messages for convenient filtration, optional
tags: ['chat', 'trade']
})

To send a message to the feed ss.channels.sendFeedMessage:

ss.channels.sendFeedMessage({
// ID player
playerId: 123,
// Message text
text: 'Hello!',
// Tags of messages for convenient filtration, optional
tags: ['chat', 'trade']
})

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

ss.channels.on('sendMessage', (message) => {
// Successfully sent

// The ID of the post, it can be used to edit or delete the post
message.id
// Channel ID
message.channelId
// Post Author ID
message.authorId
// Message text
message.text
// Tags of messages
message.tags
// Public fields of the player - sender of messages
message.player
// Message sent time
message.createdAt
})

Execution with an error:

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

Possible errors are shown in the table below:

Basic ErrorsScript ErrorsScripted only for sendMessage
player_not_foundempty_messageempty_channel_id
project_not_foundaccess_deniedchannel_not_found
origin_not_allowedmessage_characters_limit_exceeds
player_banned
internal_error

When a message is sent to all players in the channel, a notification of a new message is received:

ss.channels.on('event:message', (message) => {
// Channel ID
message.channelId
// ID messages
message.id
// ID of the author of the message
message.authorId
// Author's fields (avatar, name, custom fields)
message.player
// Message text
message.text
// Tags of messages
message.tags
// The date of sending the message
message.createdAt
// Message target: 'CHANNEL' | 'PERSONAL' | 'FEED'
message.target
})

You can pay attention to message.target:

  • CHANNEL: a new message appeared in the channel
  • PERSONAL: someone wrote a private message to the player
  • FEED: someone wrote a message in the player's feed

Edit Message

+1 Request

Changing the sent message is implemented using the ss.channels.editMessage method by the messageId identifier:

ss.channels.editMessage({
messageId: '638d73ee28520fc3b551a8ac',
text: 'Hello!'
})

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

ss.channels.on('editMessage', (message) => {
// Successfully updated

// The ID of the post, it can be used to edit or delete the post
message.id
// Channel ID
message.channelId
// ID of the author of the message
message.authorId
// Message text
message.text
// Tags of messages
message.tags
// Player Public Fields - Sender of the Message
message.player
// The time of sending the message
message.createdAt
})

Execution with an error:

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

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundchannel_message_not_found
project_not_foundempty_message
origin_not_allowedaccess_denied
player_bannedmessage_characters_limit_exceeds
internal_error

When a message changes, all players in the channel receive a message change notification:

ss.channels.on('event:editMessage', (message) => {
// Channel ID
message.channelId
// ID messages
message.id
// ID of the author of the message
message.authorId
// Message text
message.text
// Tags of messages
message.tags
// The date of sending the message
message.createdAt
})

Deleting a Message

+1 Request

Deleting a sent message is implemented using the ss.channels.deleteMessage method by the messageId identifier:

ss.channels.deleteMessage({ messageId: '638d73ee28520fc3b551a8ac' })

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

ss.channels.on('deleteMessage', () => {
// Successfully deleted
})

Execution with an error:

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

Possible errors are shown in the table below:

Basic ErrorsScript Errors
player_not_foundchannel_message_not_found
project_not_foundaccess_denied
origin_not_allowed
player_banned
internal_error

When a message is deleted, all players in the channel receive a message deletion notification:

ss.channels.on('event:deleteMessage', (message) => {
// Channel ID
message.channelId
// ID messages
message.id
// ID of the author of the message
message.authorId
// Message text
message.text
// Tags of messages
message.tags
// The date of sending the message
message.createdAt
})

Get a List of Messages in the Selected Channel

+1 Request
tip

Mandatory access rights Allow to read messages

You can get a list of messages in the selected channel using the ss.channels.fetchMessages method:

const response = await ss.channels.fetchMessages({
// Channel ID
channelId: 123,
// Tags of messages for filtering, through (&)
tags: ['chat', 'trade'],
// 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
})

Get a list of personal messages with another player:

const response = await ss.channels.fetchPersonalMessages({
// ID of another player
playerId: 123456,
// Tags of messages for filtering, through (&)
tags: ['chat', 'trade'],
// 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
})

Get a list of posts in a player's feed:

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

result.items.forEach((message) => {
// All posts of the message

// ID messages, it can be used to edit or delete a message
message.id
// Channel ID
message.channelId
// ID Player - Author of Message
message.authorId
// Message text
message.text
// Tags of messages
message.tags

// Public fields of the author of the message
message.player
message.player.id
message.player.name
message.player.avatar
// And other public fields

// The date of creation of the message, ISO 8601
message.createdAt
})
})

Execution with an error:

ss.channels.on('error:fetchMessages', (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 additionally fetch messages in a channel for the same request, there is a convenient ss.channels.fetchMoreMessages method:

const response = await ss.channels.fetchMoreMessages({
// 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 additionally fetch personal messages for the same request, there is a convenient method ss.channels.fetchMorePersonalMessages:

const response = await ss.channels.fetchMorePersonalMessages({
// ID of another player
playerId: 123456,
// Tags of messages for filtering, through (&)
tags: ['chat', 'trade'],
// How much to request at a time, Max.100
limit: 100
})

To additionally fetch messages in the feed for the same request, there is a convenient method ss.channels.fetchMoreFeedMessages:

const response = await ss.channels.fetchMoreFeedMessages({
// ID player
playerId: 123456,
// 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('fetchMoreMessages', (result) => {
result.items //An array of the list of messages
result.canLoadMore //Is it possible to load more messages
})

Execution with an error:

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

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!