All pages
Powered by GitBook
1 of 20

Channels

Our channels enable developers to implement different types of chat messaging capabilities into their applications easily

In this section, we will cover the concept of channels in Amity Chat SDK and how to use them to enable different types of chat messaging capabilities in your application.

Please be aware that there is some incompatibility between SDK version 5 and version 6 regarding the Subchannel feature.

  • Applications using SDK version 5 cannot view messages sent to subchannels by SDK version 6.

  • Channels can be sorted by 'Last Activity', which means that if messages are sent to SDK version 5 in subchannels, it moves the channel to the top of the collection. However, while the order will be updated to the top, the SDK version 5 will not display the message.

Channel and Subchannel Structure

The concept of "channel and subchannel" is central to understanding how communication is structured in a chat SDK. Channels are the primary containers that hold subchannels, while subchannels are subdivisions within a channel that represent individual topics or chat threads.

The relationship between a channel and its subchannels is hierarchical. A channel serves as a parent container for multiple subchannels, each of which represents a separate conversation or topic. Messages and interactions occur within subchannels, not the main channel itself. This organization allows for easier navigation and management of different conversations within a single channel.

The differences between channels and subchannels are as follows:

  1. Function: Channels act as containers for subchannels, while subchannels are where actual conversations and interactions take place.

  2. Hierarchy: Channels serve as parent containers, whereas subchannels are subdivisions within a channel.

  3. Messages: Channels do not contain any messages directly; instead, all messages are stored within subchannels.

  4. Management: Users can create, update, delete, and query subchannels within a channel, managing each subchannel individually.

  5. Moderation: Moderation actions, such as banning, unbanning, muting, and unmuting users, can be performed at the channel level rather than the subchannel level. This approach ensures that moderation decisions apply to all subchannels within the main channel, providing consistent management across different conversations or topics.

By default, when a channel is created, a corresponding default subchannel is also automatically generated.

Channel Types

Amity's Chat SDK has several channel types with different use cases. Each type is designed to match a particular use-case for chat channels.

Channel Type

Discoverable by

Message sending privileges

Moderation access

Channel Creation

Realtime Events Retrieval

Community

All users and admins

Joined members and admins

All Moderation tools

SDK, Console

Automatic

Private Community

Joined members and admins

Joined members and admins

All Moderation tools

SDK, Console

Automatic

Live

Joined members and admins

Joined members and admins

All Moderation tools

SDK, Console

Subscription needed

Broadcast

All users and admins

Admins

Admin Moderation tools

Console

Subscription needed

Conversation

Joined members

Joined members

No Moderation tools

SDK

Automatic

For further information about channel realtime events process, please visit Chat Realtime Events.

Community and Private Community Channel

The community channel is the default channel type and can be discovered by all users and admins. It acts as a public chat channel that showcases all of the features that our SDK's have to offer.

Channel characteristics:

  • All users in the network can search for community channel

  • All users in the network can join the community without an invitation

  • Support @mention user

  • Support @mention all users in the channel

  • Appear on ASC Console for administrator to monitor

Typical use cases:

  • Team collaboration

  • Online gaming

  • Celebrity fan club

  • Live streaming

  • Any type of public chat

Live Channel

Live channels offer the ability for users and admins to create channels with exclusive membership. The live channel is identical to our Community channel in features with the caveat that users will not be able to discover the channel when querying for all channels unless they are already a member of it. However, users and admins can still invite other users to join the channel.

Channel characteristics

  • Can only be searched by member

  • Users can join if they know channel ID

  • Support @mention user

  • Support @mention channel users (mention all users)

  • Appear on the ASC console for administrator to monitor

Typical use cases:

  • Chat channel for a one-time Live event

Conversation

Conversation channels is designed for 1-on-1 messaging and private small group chat. Unlike the other channel types, a Conversation channel can be created simply by knowing the userId of the user we want to converse with. Users can start conversations with any other user and only they will be able to see their conversation.

Each channel has its own list of members, and no two channels can have the exact same member list. If someone tries to create a new channel with the same set of members as an existing channel, the system will return the existing channel. For example creating a new channel with User A and User B will always result in the same channel no matter how many time the create command is called. This is useful when trying to establish a private chat channel between 2 or more users as we want to make sure the user can continue using the existing channel that contains previous messages history.

Channel characteristics

  • Channel is always unique with the same set of membership.

  • Support up to 10 members per conversation channel

  • Users can not join, leave, be added or removed from the channel once it's created

  • Users can not ban / unban other users in the channel

  • Does not appear on the ASC console for administrator to monitor

  • Does not support @mention user & @mention all

Typical use cases:

  • 1:1 Chat Channel

  • Private Group Chat

  • Customer Support Chat

Channel types can be created through SDK i.e Community, Live and Conversation. Creation of Private and Standard type has been removed. Creation of Broadcast channel type is not supported through the SDK. But for query, getChannels: method supports all channel types including Broadcast, Private and Standard.

Broadcast

The Broadcast channel is heavily adopted by corporate users who constantly promote or advertise their products, or make the announcement to drive awareness. Unlike other channel types, broadcast channels only allow admin users to send messages from Console, and everyone else in the channel will be under read-only mode.

Broadcast channel characteristics

  • Broadcast message can only be sent out via ASC console

  • The administrator can choose to send to any community OR live channel (but not to the conversation channel).

  • Support @mention user

  • Support @mention channel users (mention all users)

Typical use cases:

  • Marketing & Advertising

  • Organizational Announcements

Channel Properties

Name

Data Type

Description

channelId

String

ID of the channel

defaultSubchannelId

String

ID of the default subchannel that's generated upon channel creation

isDistinct

Bool

Is channel distinct?

metadata

JsonObject

Additional properties to support custom fields

type

AmityChannelType

Type of channel

tags

Array<String>

Tags used for searching

isMuted

Bool

Is this channel muted?

isRateLimited

Bool

This channel has limited sending rate?

rateLimit

Int

Number of messages within rate limit

displayName

String

Channel name for displaying

memberCount

Integer

Number of members in channel

messageCount

Integer

Number of messages in channel

unreadCount

Integer

Number of unread messages in channel

lastActivity

DateTime

Date/time of user's last activity related to the channel (e.g. add/remove member)

createdAt

DateTime

Date/time the channel was created

updatedAt

DateTime

Date/time the channel was last updated

avatarFileId

String

Avatar file ID

isPublic

Bool

Public / Private community channel

Channel Object is a Live Object and you can observe real-time changes in Channel Properties. Please see to Live Object on how to listen to real-time changes.

Get Channels

SDK now supports querying channels based on provided channel IDs. The ChannelRepository class includes a getChannels method that takes an array of channel IDs as input and returns a live collection of channels. This live collection will contain all the channels that are being queried in the first page. This live collection will not support pagination.

Any update to the channels present in this live collection will be automatically notified to the user. Furthermore,

  • This live collection will only contain valid channels. In case of invalid channels (such as user gets banned etc.) the list may exclude those channels.

  • If any channel id is invalid, live collection will throw error.

💡 The maximum number of channel that can be queried is 100.

Limitations:

If the channel is not public and user leaves the channel, the channel will still remain in the live collection until user refresh or resets the live collection.

Create Channel

ChannelRepository offers a function to create a new channel. This function provides support for creating three distinct types of channels, including Community, Live, and Conversation. Each channel type has its own unique characteristics and capabilities as we explained earlier, and the create channel function allows users to easily create and customize channels to suit their specific needs.

The SDK offers two standard ways for creating channels. The first method involves specifying a specific channel ID during the channel creation process. The second method allows for the automatic generation of a unique channel ID. The create channel API is designed to ensure that the channel being created is a new channel, and in the event that the requested channel already exists, it will return a conflict error (400900). The channel ID parameter in the channel creation function may be left undefined, in which case the SDK will automatically generate a unique channel ID to avoid any conflicts with existing IDs.

Create Community Channel

This function on the SDK allows you to create a new #community-channel. The displayName parameter is a required field, and it represents the public display name of the channel.

Here is a brief explanation of the function parameters:

  • displayName: The public display name of the channel.

  • avatarFileId: The image fileId that represents the image of the channel.

  • metaData: Additional properties to support custom fields.

  • tags - Arbitrary strings that can be used for defining and querying for the channels.

  • isPublic - Specify visibility for the community channel that public or private community.

Supported ✅ (please wait while we prepare a real example!)

Version 6

Beta (v0.0.1)

Create Live Channel

Similar to community channel creation function, the function allows you to create a new Live Channel. The displayName parameter is a required field, and it represents the public display name of the channel.

Here is a brief explanation of the function parameters:

  • displayName: The public display name of the channel.

  • avatarFileId: The image fileId that represents the image of the channel.

  • metaData: Additional properties to support custom fields.

  • tags - Arbitrary strings that can be used for defining and querying for the channels.

import { ChannelRepository, ChannelType } from '@amityco/js-sdk';

const liveChannel = ChannelRepository.createChannel({
  channelId: 'channel1',
  type: ChannelType.Community,
  userIds: [ 'user1', 'user2' ],
})

liveChannel.once('dataUpdated', model => {
  console.log(`Channel created: ${model.channelId}`);
});

liveChannel.once('dataError', error => {
  // Handle channel create error (non-unique channelID)
});

Version 6

Beta (v0.0.1)

Create Conversation Channel

The Conversation channel creation function can also be utilized to create channels of the Conversation type. However, it should be noted that the channel ID for these channels will always be generated by the SDK. This ensures that the channel ID is unique and avoids any potential conflicts with existing channels

Here is a brief explanation of the function parameters:

  • userId: The userId of the user that you'd like to chat with.

  • displayName: The public display name of the channel.

  • avatarFileId: The image fileId that represents the image of the channel.

  • metaData: Additional properties to support custom fields.

  • tags - Arbitrary strings that can be used for defining and querying for the channels.

Conversation channel is unique based on its membership. When creating conversation, the system will check if a channel with the same membership already exists. If such channel already exists, the system will return the existing channel instead of creating a new one.

import { ChannelRepository, ChannelType } from "@amityco/js-sdk"

const liveChannel = ChannelRepository.createChannel({ type: ChannelType.Conversation })

liveChannel.once('dataUpdated', () => {
  console.log('channel created');
});

Version 6

Beta (v0.0.1)

Create Broadcast Channel

Broadcast channel can only be created from Amity Social Cloud Console. We recommend to see instructions in Create Channel on how to create a Broadcast channel.

Subchannel

Subchannels are the part of a channel. They are separate topics or chat thread inside a channel. Messages can be sent & received in subchannel. By default, a channel itself would also generate a main subchannel once it's created. You can create, update, delete & query subchannels inside a channel. For the sturcture and relationship of channels and subchannels, please visit Channel and Subchannel Structure.

Limitations:

  • Sub-channel creation is supported for Conversation and Community channel types.

  • Users can create up to 300 sub-channels per channel.

Create Subchannel

In the concept of channels and subchannels, a channel is a primary container that can hold multiple subchannels. When you create a subchannel, it will serve as a thread where users can send messages and participate in discussions related to a specific thread. The subchannel creation function requires two parameters: channelId and displayName.

  • channelId: specifies the unique identifier of the parent channel where the subchannel will be created. This allows the SDK to link the subchannel to the correct parent channel, and organize it within the correct hierarchy.

  • displayName: Specifies the public name or label of the subchannel that will be visible to users.

We don't support this feature in JS SDK.

Version 6

Beta (v0.0.1)

Update Subchannel

When you update a subchannel's properties, the changes will be reflected for all users who are members of that subchannel. Please note that the updateSubChannel function only updates the properties of the subchannel itself, and does not affect any messages or other content that has been sent within the subchannel.

The function requires two parameters: subchannelId and displayName.

  • subhannelId: This is the unique identifier of the subchannel that you'd like to update.

  • displayName: This is the updated public name or label of the subchannel that will be visible to users.

We don't support this feature in JS SDK.

Version 6

Beta (v0.0.1)

Delete Subchannel

The subchannelId parameter specifies the ID of the subchannel that you'd like to delete. The hardDelete parameter is a boolean value that determines whether to perform a hard delete or a soft delete.

A soft delete will mark the subchannel as deleted but keep its data in the system. A hard delete will immediately and permanently delete the subchannel and all its data from the system.

We don't support this feature in JS SDK.

Version 6

Beta (v0.0.1)

Get Subchannel

To get a subchannel, you can use the getSubchannel method provided by the SubchannelRepository. This method accepts a subchannelId parameter and returns a Live Object of the AmitySubchannel class.

The AmitySubchannel class represents a subchannel in a channel. It contains information about the subchannel, such as its ID, display name, avatar, creation time, and more.

By using a Live Object combines with #real-time-events, you can observe any changes made to the subchannel in real-time. This is particularly useful in cases where multiple users may be interacting with the same subchannel and you need to keep the UI up-to-date with the latest data.

We don't support this feature in JS SDK.

Version 6 and Beta(v0.0.1)

Query Subchannels

The getSubChannels function allows you to retrieve a list of subchannels within a specific channel. It accepts the channelId parameter to specify which channel to retrieve subchannels from.

The function returns a Live Collection, which allows you to observe changes to the collection in real-time.

We don't support this feature in JS SDK.

Version 6 and Beta(v0.0.1)

Get Channel

Get a Channel

The function allows users to retrieve information about a specific channel using the channelId parameter. This function returns a Live Object of the AmityChannel class, which contains information such as the channel's display name, tags, avatar, and other metadata.

This function is useful for a variety of purposes, such as displaying information about a channel to users or retrieving channel details before joining the channel.

const liveChannel = ChannelRepository.getChannel('channel3');

liveChannel.once('dataUpdated', data => {
  ...
});

Version 6 and Beta (v0.0.1)

Query Channels

Query Channels

The getChannels function is a powerful function that allows you to search for and retrieve channels that match specific criteria. With this function, you can quickly and easily find the channels you need.

The function accepts several parameters that allow you to customize your search. The keyword parameter is a string that specifies the search query, allowing you to search for channels based on their displayName.

Once you have made your query, the function returns a Live Collection of channels that match your query criteria. You can use this collection to display the search results in your app, or to further filter the results as needed.

You can query channels with the following criteria:

  • keyword: Specify keyword that should be in channel displayName

  • includeDeleted : Specify whether to search for channels that has been closed. Possible values are:

    • null (default) - Show both channel is active and closed.

    • false - Search for channels that is still open

  • tags : Search for channels with the specific tags. If more than 1 tags are specified in the query, system will search for channels that contain any of those tags.

  • excludeTags : Search for channels without the specific tags. If more than 1 tags are specified in the query, system will search for channels that does not contain any one of those tags.

  • filter : Membership status of the user. Possible values are:

    • all (default) - Search for channels

    • member - Search for channels that the user is a member of

    • notMember - Search for channels that the user is not a member of

    • flagged - Search for channels that the user flagged

  • types : type of channel to search for - conversation , broadcast , live or community

  • userId : Search for channels that is created by a given User ID

If you use a UITableView or UICollectionView to display channel list data, the ideal location to reload table data is directly in the observe block of the live collection that you are displaying.

import { 
  ChannelRepository, 
  ChannelType, 
  ChannelFilter, 
  ChannelSortingMethod,
} from '@amityco/js-sdk';

let channels;

const liveCollection = ChannelRepository.queryChannels({
  keyword: 'asd',
  types: [ChannelType.Conversation],
  filter: ChannelFilter.Member,
  isDeleted: false,
  tags: ['tag1'],
  excludeTags: ['tag2'],
  sortBy: ChannelSortingMethod.LastCreated
});

liveCollection.on('dataUpdated', models => {
  channels = models;
});

channels = liveCollection.models;

Version 6

Beta(v0.0.1)

Join/Leave Channel

Join a Channel

The joinChannel function allows users to join a channel, making them a member of the channel. This function takes one parameter, channelId, which is the ID of the channel that the user wishes to join.

Once the user joins the channel, they will be able to participate in conversations and receive updates about the channel's activity. It is important to note that this function is idempotent, which means that it can be called multiple times without causing any issues. If the user has already joined the channel, a successful result will still be returned.

const isJoined = await ChannelRepository.joinChannel({
channelId: 'channel2'
});

Version 6

Beta (v0.0.1)

Leave a Channel

The leaveChannel function is used to disengage a user from a channel by removing them from the list of members. This function takes the channelId parameter, which specifies the ID of the channel that the user wishes to leave. Once the user has left the channel, they will no longer receive any messages or updates from the channel.

import { ChannelMembershipRepository } from '@amityco/js-sdk';

await ChannelMembershipRepository.leaveChannel({ 
  channelId: 'channelId', 
})

Version 6

Beta (v0.0.1)

Channel Membership

When a user joins a channel, they are able to observe and chat with other users in that channel. They are also automatically considered a member of that channel. The Chat SDK provides the ability to view which users are currently in the channel as well as invite other users to join the channel.

Each channel is identified by a unique channelId, which is any string that uniquely identifies the channel and is immutable through its lifetime. When creating channels, you can specify your own channelId, or leave it to Amity's Chat SDK to automatically generate one for you.

It's important to note that, createChannel guarantees that the requested channel is a new channel (except for conversation type), whereas joinChannel will attempt to join an existing channel. If there is a requirement to create a new channel, then use of createChannel then call joinChannel. Lastly calling getChannel only gives you back the channel LiveObject, but it won't make the current user join said channel.

Observe for changes in Membership

You can observe the channel to determine changes in the membership status. If the user is banned from the channel, you would want to show the particular UI and move from the chat screen.

For example, in the event of a channel-ban, it's possible to implement the appropriate user interface, navigating the user to be redirected away from the chat screen.

Supported ✅ (please wait while we prepare a real example!)

Supported ✅ (please wait while we prepare a real example!)

Update Channel

Update a Channel

The updateChannel function allows users to modify the properties of a channel. This function is useful in cases where a channel's details need to be updated, such as changing the channel's display name or avatar.

The function takes a channelId parameter as a required input, which specifies the channel to be modified. Additionally, users can pass in any number of optional parameters to update the channel's properties. These optional parameters include:

  • displayName: The new display name for the channel.

  • avatarFileId: A new avatar image for the channel - Used to store ID of image file that represents avatar of the channel. To obtain file ID to set as channel avatar please see Upload Images section

  • tags: Arbitrary strings that can be used for define and query for the channels

  • metadata: Additional metadata to be associated with the channel.

metadata is implemented with last writer wins semantics: multiple mutations by independent users to the metadata object will result in a single stored value. No locking, merging, or other coordination is performed across multiple writes on the data.

await ChannelRepository.updateChannel({ 
    channelId: 'channelId', 
    displayName: channelName,
    avatarFileId: fileId,
    tags: ['tag1', 'tag2'],
    metadata: { hello: 'world' }
 })

Version 6

Updating Display Name and Tags

Beta (v0.0.1)

Message Preview

Messages preview is partial data of the message that offers a brief summary of incoming messages through channel and subchannel objects. It allows users to quickly assess partial message content without opening the entire message.

Message Preview is an on demand feature. Please submit your request to Amity Help Center to enable this feature. It will take approximately 5 business days to process your request.

Message Previews in Applications

Message previews play a crucial role in enhancing user experience in messaging platforms. By offering a brief glimpse of incoming messages through channel and subchannel objects, users can assess the urgency, context, and relevance of messages without needing to open the entire conversation. This feature is particularly beneficial in various scenarios:

  1. Notifications: When a user receives a push notification or a message alert, a message preview can be shown, allowing the user to decide whether to engage immediately or defer it to a later time.

  2. Chat List: In a list of ongoing conversations, each chat item can display the latest message as a preview. This helps users quickly identify and prioritize which chat to respond to first.

  3. Data Economy: In scenarios where users have limited bandwidth or are on metered connections, previews allow them to decide if they want to download or load the complete message or any associated media.

Integrating message previews into applications can significantly boost user engagement and satisfaction. By offering users an efficient way to manage their interactions, apps can optimize response times and streamline communication workflows.

Message Preview attributes

Name
Data Type
Description
Attributes

messageId

string

The id of this message

​Content

channelId

string

The name of the channel this message was created in

​Content

userId

string

The name of the user this message was created by

​Content

type

string

The message type

enum*: text custom image file

data

Object

The message data (any text will be stored in text key)

text: Text message

isDeleted

boolean

The message has been marked as deleted

​Content

createdAt

date

The date/time the message was created at

​Content

updatedAt

date

The date/time the message was updated at

​Content

Channel message preview

Within our SDK, clients can effortlessly obtain message previews using a channel object attribute.

Subchannel message preview

Our SDK offers clients a straightforward approach to access message previews for subchannels through dedicated subchannel object attributes.

Unread Count

The unread count feature in chat channels and subchannels allows you to keep track of new messages and stay up-to-date with ongoing conversations. By providing a simple indicator of unread messages, users can quickly prioritize which channels require their attention. This topic provides instructions for managing unread messages in a chat channel and sub-channel.

Note: we only support unread count on community, conversation, and broadcast channels. We do not support this feature in live channels. Mention unread in channels and subchannels aren't supported as well.

Unread Count Syncing

To enable the unread message count feature on the device, the user must start unread count syncing. This ensures that the user, as well as all channels and subchannels, have an up-to-date message unread count. To disable this feature, users simply stop the unread count syncing, which will stop updating the message unread count from their device.

Start unread count syncing

To start unread count syncing, you can use the following code:

Stop unread count syncing

To stop unread count syncing, you can use the following code:

User Unread Count

User Unread Count

This function enables users to obtain the current user's total count of unread messages and their mention status across all channels and sub-channels. To retrieve this value, utilize the CoreClient and follow the code pattern below.

Please note that the TypeScript SDK does not yet support retrieving mention status information with this function.

Channel Unread Count

Channel unread count

The SDK provides a simple way for clients to retrieve the unread count for a channel. To view the unread count for a channel, we can get it from a channel object. This count represents the number of messages that you have not yet read in that channel.

Check unread count support for channel

To check if a channel supports the Unread Count feature, you can use the following code:

Channel Mention Status

To get the mention status of the current user in a channel, developers can use the following code.

Subchannel Mention Status

To get the mention status of the current user in a sub channel, developers can use the following code.

Subchannel Unread Count

The SDK provides a simple way for clients to retrieve the unread count for a sub channel. To view the unread count for a sub channel, we can get it from a sub channel object. This count represents the number of messages that you have not yet read in that sub channel.

Check unread count support for sub channel

To check if a sub channel supports the Unread Count feature, you can use the following code:

Start / Stop reading a Subchannel

To ensure that the message read count is up to date for a subchannel, users need to start reading the sub channel. When a user opens a subchannel, the chat system updates the read count for all messages in that channel, based on the user's reading status. This feature is designed to provide accurate read counts for sub channels, ensuring that users have a clear understanding of which messages have been read and which are still unread

Start reading a sub channel

Active reading of a subchannel and letting the chat system know that reading status can update the message read count in that sub channel. The system will update the read count for all messages in the sub channel that the user has not yet read.

Stop reading a sub channel

To maintain an accurate message read count, users should stop reading a sub channel when they have finished reading it. The chat system updates the read count based on the user's reading status, so if a user leaves a sub channel, they should stop reading to avoid reading new messages.

stopReading will be called automatically if the internet connection drops or is disconected. It lasts for one minute. This means that if an internet connection drops after one minute, stopReading will be automatically called, and after it is re-established, startReading will be called again.

Mark Channel as Read

Mark Channel as Read

Clearing all unread counts in a channel is a useful feature that allows users to easily keep track of their message history. To accomplish this, the SDK provides a convenient method to mark all messages within a channel as read, effectively clearing the unread count. This method can be called by invoking the markAsRead() function on the ChannelRepository class with the appropriate channelId parameter.

Once called, the function will iterate through all messages in subchannels within the specified channel and mark each as read. This process will clear the unread count.

Please note that clearing unread counts in a channel only applies to the specified channel and does not affect any other channels or subchannels. Additionally, clearing unread counts does not delete any messages or modify their content in any way. It simply updates their status to reflect that they have been read by the user.

Message Delivery Status

Mark Message as Delivered

When you send a message to someone, it's important to know whether that message has been delivered to the recipient's device or not. This is where the "Mark message delivered" function comes in.

By calling this function, you can update the status of a message to "delivered", which indicates that the message has been successfully delivered to the recipient's device. This can be useful for ensuring that important messages have been received by the intended recipient.

The parameters for this function are:

  • subchannelId: The ID of the subchannel where the message is located.

  • messageId: The ID of the message you want to mark as delivered.

Get Message's Read Users

In a chat application, it is often necessary to track which users have read a message. The Get Message's Read User function allows developers to retrieve a list of users who have read a particular message. This function can be useful for a variety of purposes, such as displaying read receipts or tracking user engagement with a particular message.

To use this function, you can call the getMessageReadUsers method, this will return a collection of users who have read the message.

Get Message's Delivered Users

It is also important for users to know whether their messages have been successfully delivered to the intended recipients. The "Get message's delivered user" function allows users to query the list of users who have marked a particular message as delivered. This feature can be useful in scenarios where users need to know whether their messages have reached their intended recipients, such as in a customer service application or a team collaboration tool.

The function takes a message ID as a parameter, and returns a collection of user objects who have marked the message as delivered. By observing the live collection, users can receive real-time updates as new users mark the message as delivered.

Read Status & Unread Count (Legacy)

For Android, iOS, JS SDK version 6.5.0 and below and TS SDK version v0.0.1-beta.42.3

Reading Status and Unread Count

The ChannelRepository object exposes a totalUnreadCount property that reflects the number of messages that the current user has yet to read. This count is the sum of all the unreadCount channels properties where the user is already a member.

Version 6

The ChannelRepository provides getTotalDefaultSubChannelUnreadCount() method.

Version 5 (Maintained)

The ChannelRepository provides getTotalUnreadCount() method. It's giving the flowable of the number of messages that the current user has yet to read. This count is the sum of all the unreadCount channels properties where the user is a member of.

Unread Mention

To check whether the current user has been mentioned on one of the unread messages:

Version 6

Version 5 (Maintained)

const liveObject = ChannelRepository.getChannel('channelId');

liveObject.on('dataUpdated', channel => {
  // the number of unread messages
  console.log(channel.unreadCount);
});

Version 6

The Channel object exposes a unreadCount property that reflects the number of messages that the current user has yet to read. This count is the sum of all the unreadCount channels properties where the user is already a member. It also provides hasMention which is a boolean presenting having a mention for current user in channel.

The startReading() and stopReading() methods let the server know that the current user is reading a channel. After the startReading()and stopReading() methods are called, the unreadCount is reset to 0.

You can call both methods as much you'd like, the SDK takes care of multi-device management: therefore a user can read multiple channels, from one or multiple devices at the same time. In case of an abrupt disconnection (whether because the app was killed, or the internet went down, etc.), the SDK backend will automatically call the stopReading on the user's behalf.

Version 6

Version 5 (Maintained)

// start reading a channel
await ChannelRepository.startReading({ channelId: 'channel1' });

// stop reading a channel
await ChannelRepository.stopReading({ channelId: 'channel1' }); 

Beta (v0.0.1)

This is the legacy feature, for version 6.0.0 and above, please visit Unread Count.

Channel Moderation

Channel Moderation is an essential feature for creating a safe and engaging chat community. With Amity Chat SDK, developers can use moderation to manage chat channels effectively and ensure that the chat community remains safe and welcoming. Moderation features such as user banning and muting can help prevent inappropriate content and maintain a positive chat environment.

Add / Remove Roles

Roles define varying levels of access and permissions that can be assigned to users within a chat channel. Each role is defined by a set of permissions that determine what actions a user can perform within the channel.

Roles can be assigned to users based on factors such as their level of participation in the chat community or their specific responsibilities within the channel. For example, a moderator might have the ability to remove inappropriate messages or ban users from the channel, while a regular user might only have the ability to send and receive messages.

You can use ChannelRepository class to add / remove users from a role

Supported ✅ (please wait while we prepare a real example!)

Supported ✅ (please wait while we prepare a real example!)

  1. The channel creator is automatically assigned as the channel moderator.

  2. The previous/last moderator is not allowed to leave a community and an error is displayed.

  3. The channel moderator can promote a user/member to moderator.

  4. The channel moderator can demote a moderator to a user/member.

This applies only to Live and Community channels’. This does not apply to Conversation Channel.

Permission

You can check your permission in channel by sending Permission enums to CoreClient.hasPermission(amityPermission).

Supported ✅ (please wait while we prepare a real example!)

The functionality isn't currently supported by this SDK.

Supported ✅ (please wait while we prepare a real example!)

Add / Remove Members

AmityChannelMembership provides methods to add and remove members, as well as removing yourself as a member of the channel (leaving the channel).

  • channelId: The ID of the channel to which you want to add or remove members.

  • userIds: An array of user IDs to be added to the channel or removed from the channel.

// add 'user1' and 'user2' to this channel
const isAdded = await ChannelRepository.addMembers({
  channelId: 'channel1',
  userIds: [ 'user1', 'user2' ],
});

// remove 'user3' from this channel
const isRemoved = await ChannelRepository.removeMembers({
  channelId: 'channelId',
  userIds: [ 'user3' ],
});

// leave this channel
const isLeaved = await ChannelRepository.leave('channelId');

Version 6

Add Channel Members

Remove Channel Members

Beta (v0.0.1)

Add Channel Members

Remove Channel Members

The functionality isn't currently supported by this SDK.

Ban / Unban Members

ChannelRepository class also provides various methods to moderate the users present in channel. You can ban/unban users, assign roles or remove it from user.

For the banMembers function, the following parameters are required:

  • channelId: The ID of the channel from which the members are being banned.

  • userIds: An array of user IDs to be banned from the channel.

For the unbanMembers function, the following parameters are required:

  • channelId: The ID of the channel from which the members are being unbanned.

  • userIds: An array of user IDs to be unbanned from the channel.

const isBanned = await ChannelRepository.banMembers({ 
  channelId: 'channel1', 
  userIds: ['user1']
);
​
const isUnbanned = await ChannelRepository.banMembers({ 
  channelId: 'channel1', 
  userIds: ['user1']
);
​
await ChannelRepository.addRole({ 
  channelId: 'channel1', 
  userIds: ['user1'],
  role: 'role1',
);
​
await ChannelRepository.removeRole({ 
  channelId: 'channel1', 
  userIds: ['user1'],
  role: 'role1',
);

Version 6

Ban members

Unban members

Beta (v0.0.1)

Ban members

Unban members

Supported ✅ (please wait while we prepare a real example!)

Query Members

Query Channel Members

The ability to search for and query members within a chat channel is an essential feature for creating a seamless and engaging user experience. With Amity Chat SDK, developers can use the query member feature to allow users to search for and retrieve member information within a channel. We will discuss how to use the query member feature of Amity Chat SDK to enable users to search and retrieve member information within a chat channel.

For the specified channel, the list of users will be sorted by as a lastCreated default parameter. Users can also choose to sort by lastCreated or firstCreated.

All participation related methods in a channel fall under a separate ChannelParticipation class.

All participation related methods in a channel fall under a separate ChannelParticipation class.

You can get a list of all members, or add memberships, roles , search parameters to get certain members of the channel.

import { ChannelRepository, MemberFilter } from '@amityco/js-sdk';

let members;

const liveCollection = ChannelRepository.queryMembers({ 
  channelId: 'channel1',
  memberships: [MemberFilter.Member],
  roles: ['role1'],
  search: 'asd',
});

liveCollection.on('dataUpdated', newModels => {
  members = newModels;
});

liveCollection.on('dataError', error => {
  console.error(error);
});

members= liveCollection.models;

Version 6

Beta (v0.0.1)

Search Members

Search Channel Members

The searchMembers function in the AmityChannelParticipation class is used to search for members in a channel when mentioning. It takes the following parameters:

The function returns a Live Collection of ChannelMember objects. You can filter search results with more than one option, such as filtering by muted and banned users. The role filter, which takes the role enum as an argument.

If no keyword is supplied, the list of users will be organized alphabetically by display name. When a keyword is provided, the list will be arranged based on search rank.

It takes the following parameters:

  • displayName/keywords: This parameter takes in the display name or user ID of the member being searched.

  • roles: This parameter is used to filter search results by roles:

    • member - Standard member

    • mute - Muted member

    • ban - Banned member

Supported ✅ (please wait while we prepare a real example!)