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

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;

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.

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.

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.

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

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.

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

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

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

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.

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.

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

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

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

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.

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.

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.

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.

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.

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

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.

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:

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.

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:

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.

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

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

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

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

Permission

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

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.

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.

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

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.

Get a Channel

The function allows users to retrieve information about a specific channel using the channelId parameter. This function returns a 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.

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.