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.

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

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.

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.

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.

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

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 section

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

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

iOS ​ Android ​ Web TypeScript React Native Ionic Flutter

Amity Chat SDK

The Amity Chat SDK provides a powerful set of pre-built features to enable in-app social experiences and fuel user engagement. With support for a range of platforms and programming languages, the SDK is a flexible and scalable solution for building messaging apps. We hope this documentation page has provided you with the information you need to get started with the SDK. If you have any questions or feedback, please feel free to contact us via our support center.

We provide a range of pre-built features that enable in-app social experiences and fuel user engagement. Here are some of the main features of the SDK:

• Start a new conversation channel with up to 300,000 concurrent participants (actual maximum may varies from selected plan, see for more detail)

• View read counts for every message

• Moderate conversations with user banning, muting, and rate limiting

• Assign moderators and admins via a role-based permission system

• Filter out inappropriate content with automated spam filtering and URL whitelists

• Manage connection state and handle offline data automatically

• Support multi-device and multi-platform for every user

• Powerful messaging capabilities for native and web apps

• Moderation tools for filtering out inappropriate content

• Role-based permission system for assigning moderators and admins

• Real-time syncing of messages across all users in a channel

• Support for text, image, audio, video, file, and custom messages

• Support up to 300,000 concurrent participants in a channel

Getting Started

Channel is a virtual chat room or a group that enables users to send and receive messages in real-time. Channels allow developers to implement different types of chat messaging capabilities into their applications easily, such as private messaging, group chats, and chat rooms.

If you're new to the Amity Chat SDK, the following resources can help you get started:

Channel Types

Messaging is a crucial feature for any chat application, and with Amity Chat SDK, developers can enable real-time communication between users within a chat channel with ease.

The Amity Chat SDK supports several channel types, each designed to match a particular use-case for chat channels. Here's a table showing what features each channel type offers:

Message Types

Moderation is an essential feature for building a community that encourages user participation and engagement. With Amity Chat SDK, developers can use the moderation feature to assign moderators and admins via a role-based permission system, filter out inappropriate content with automated spam filtering and URL whitelists, and manage user bans.

The Amity Chat SDK supports several message types, including:

Chat experience is more fun when you can express yourself! With Amity Chat SDK, developers can use Reactions feature to allow users to react to messages using emojis, stickers, or thumbs up. This feature can help users express their emotions and opinions, making communication more engaging and interactive.

• Text Message

• Image Message

• File Message

• Audio Message

• Video Message

• Custom Message

In addition to these message types, the SDK also supports message reactions, which can be used to enable users to react to messages in a channel.

Features

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

This page highlights the steps you will need to follow to begin integrating chat messaging into your products.

Moderation is an important feature for building a safe community that encourages user participation and engagement.

Interactions are more fun when you can express yourself! Let users react using emojis, stickers, or thumbs up to messages.‌

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.

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:

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.

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.

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.

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.

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.

Messaging is an essential component of any chat application, and the SDK provides robust messaging features. The SDK optimizes the messaging flow for users by instantly displaying sent messages, even before they have been delivered to the server. To ensure the user's smooth messaging experience, the SDK provides the syncState property in the message model to monitor the message delivery status.

Amity supports the sending and receiving of five types of messages:

Message Synchronization

SDK (Android & iOS) now supports resynchronization of message if the internet connection is not available or interrupted at the time the user sends a message. To support resynchronization, we enhanced the internal architecture on how the messages are queued, processed and synced with server.

Local Message

When you create a message, SDK first creates the message locally. This locally created message will be reflected immediately in the related live collection that user is observing at the moment. Then the SDK starts syncing this message with server. User can check the syncState property of the message model inside live collection to reflect the current state of the message.

Message Syncing

Once a message is created locally, SDK adds the message to the queue and starts the process of syncing this message with server. After the message is synced with server, the syncState of the message changes to synced. Here is the table showing various state of the message and its corresponding syncState value per platforms.

The messages are synced in the order they get added to the queue in FIFO (First In First Out) order. SDK will maintain causal ordering of the message of similar types.

Causal Ordering:

SDK maintains causal ordering for similar type of messages i.e (Text, Custom) & (Image/File/Audio/Video). Let’s look at the example to understand this:

If user creates messages in this order from left to right: [Text1 → Image1 → Image2 → Text2 → Text3 → Image3]

• The ordering of text messages are maintained i.e Text 2 will be synced after Text 1 & so on

  • [Text1 → Text2 → Text3]

• The ordering of Media messages are respected i.e Image2 will be synced after Image 1 and so on.

  • [Image1 → Image2 → Image3]

• The ordering of all messages mixed might not be respected. Ex: If image1 takes longer time to upload, the ordering can be:

  • [Text1 → Text2 → Text3 → Image1 → Image2 → Image3]

Waiting for connectivity:

SDK automatically determines the internet connection availability on user device and waits for the stable connection before sending the request to sync with server. Once the connection is available, SDK syncs the message with the server maintaining the causal ordering as described above.

Connection Interruption / Server Error Handling

If the network connection is interrupted during the request or server returns error for the request, depending upon the interruption state & error returned, SDK will automatically retry syncing the message after some interval (~ 5 seconds). SDK will retry syncing up to maximum 3 times and if the message still cannot be synced, SDK will mark the message as failed and notify the user through callback of createMessage api. The syncState of the message would change to failed / error.

Failed Message Handling

The message syncing can fail for many reasons. User should handle the error thrown from create message api and decide what to do for failed messages. Once the status of the message is failed, SDK will not attempt to retry syncing that message anymore. The failed messages will not be automatically removed from the live collection. It’s up to the user to decide if they should resend the same message or delete the failed message so that it disappears from the live collection. The syncState of the failed message would be failed / error.

Deleting failed message:

You can use existing softDeleteMessage() method in AmityMessageRepository class to delete specific failed message.

Deleting all failed messages:

If you do not care about any failed messages, SDK also provides deleteFailedMessages() method in AmityMessageRepository class to allow deletion of all failed messages.

Deleting all failed messages upon SDK Initialization:

This message syncing process is only maintained per active session per device. If user logs out or if user current session is destroyed, all the active syncing process is terminated.

When the SDK is initialized again (i.e client instance is initialized), all the messages which were in syncing state from the previous session would be changed to failed state. User can choose to delete particular failed message (using softDeleteMessage() method) or delete all failed messages (using deleteAllFailedMessages() method).

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.

Messages are JSON content containers that can have up to 20,000 characters or can weigh up to 100KB for custom messages. They will be synchronized among all channel users in real-time. If a message requires larger binary data (such as when sending files), we recommend to upload the data to another cloud storage service, such as AWS S3, and store the URL to the content in the message data.

In addition to the JSON message type, the SDK also provides support for common text and image message types. These additional types are built on top of the standard JSON message layer.

The message payload is always the same regardless of which Development Kit the user is using. Users also have a choice on what type of message they want to send.‌

Message Description

Send a Video Message

Video messages allow users to share videos within a chat or social platform. This could be anything from a quick clip to a longer, more detailed video. With the Amity SDK, developers can easily integrate video message functionality into their apps, allowing users to record, upload, and share videos in real-time.

To send a video message, you must pass a valid local file URL instance instead. You can also specify an optional caption as part of the message. This caption is accessible via the data property in the message model under the caption or text key. You can add up to 1,000 characters of text per message. When a video is uploaded, it is automatically resized to the maximum size of 480p.

For further information regarding a video information please refer to page.

Here is a brief explanation of the function parameters:

• text/caption: A string that contains the text message that the user wants to send. This parameter is mandatory as it contains the actual message content.

• attachment: The local video path that the user wants to send on the device

• subchannelId: An identifier for the subchannel where the message will be sent. Subchannels are subdivisions within a channel that represent individual topics or chat threads. Messages and interactions occur within subchannels, not the main channel itself.

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

Send a Text Message

In a chat application, it's essential to send text messages to each other in real-time, allowing for quick and easy communication. Users can also view previous messages sent and received within the chat, allowing them to reference past conversations as needed.

The sendTextMessage function is a feature provided by the Amity chat SDK that enables users to send plain text messages in a . This function requires two parameters: text and subchannelId.

Here is a brief explanation of the function parameters:

• text: A string that contains the text message that the user wants to send. This parameter is mandatory as it contains the actual message content.

• subchannelId: An identifier for the subchannel where the message will be sent. Subchannels are subdivisions within a channel that represent individual topics or chat threads. Messages and interactions occur within subchannels, not the main channel itself.

• metaData: Additional properties to support custom fields.

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

Send a File Message

A file message is a type of message that allows users to share files with each other within a chat or messaging app. This can include documents, images, videos, and other types of files. To send a file message, the user simply selects the file they want to share and sends it through the app.

When a user receives a file message, they can view or download the file directly within the app. This makes it easy for users to share important files and collaborate with each other without having to switch between different applications or email clients.

A File message can include any of the following:

• Image

• Audio

• File

• Custom

To send a file message, you must provide a valid local file URL instance of the selected file and file name for the file. The default file name is file. The SDK will check the size of the data whether it is exceeding the limit or not before sending it to the server. If the size of the data is more than the limit, the callback will return an Error object with the error information that you can parse and then show an error message.

Here is a brief explanation of the function parameters:

• text/caption: A string that contains the text message that the user wants to send. This parameter is mandatory as it contains the actual message content.

• attachment: The local file path that the user wants to send on the device

• subchannelId: An identifier for the subchannel where the message will be sent. Subchannels are subdivisions within a channel that represent individual topics or chat threads. Messages and interactions occur within subchannels, not the main channel itself.

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

Amity’s customer-centric nature ensures that security needs are kept at the forefront of the work we do. Our purpose has been to continuously develop features that are safe and ready to use. We power our moderators with tools to control and impose permissions that make their applications a safer place, for all users. We put the utmost importance on giving power to our clients to implement protocols that keep their applications healthy, safe and compliant.

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

Querying Messages

The getMessages function is a powerful feature of the chat or messaging SDK that allows users to retrieve messages from a specific subchannel based on various criteria. This function provides flexibility in fetching messages that meet specific requirements. This function returns a #live-collection of messages.

Filter parameters

• subChannelId: This parameter specifies the ID of the subchannel from which you want to retrieve messages.

• includingTags[] (optional): This parameter allows you to filter messages based on specific tags. You can provide an array of tags, and the function will return only the messages that have at least one of the specified tags.

• excludingTags[] (optional): Conversely, this parameter allows you to exclude messages that have certain tags. You can specify an array of tags, and the function will exclude messages with any of the specified tags from the result.

• includeDeleted (optional): This parameter determines whether to include deleted messages in the result. If set to true, the function will include both active and deleted messages. If set to false, only active messages will be returned.

• type (optional): You can filter messages according to their type

  • if no type is passed, any message will match

  • if an AmityMessage.DataType is passed, query for all messages with the specific type

    • AmityMessage.DataType.TEXT for text messages

    • AmityMessage.DataType.IMAGE for image messages

    • AmityMessage.DataType.FILE for file messages

    • AmityMessage.DataType.AUDIO for audio messages

    • AmityMessage.DataType.VIDEO for video messages

    • AmityMessage.DataType.CUSTOM for custom messages

Sorting

In the getMessages function, the sorting option allows you to specify how the returned messages should be ordered. There are two available sorting options:

1. firstCreated: When you set the sorting option to firstCreated, the messages will be ordered in ascending order based on their creation time. This means that the oldest messages will appear first in the returned collection, while the newest messages will be at the end.

2. lastCreated: On the other hand, when you choose the lastCreated sorting option, the messages will be ordered in descending order based on their creation time. This means that the newest messages will appear first in the returned collection, while the oldest messages will be at the end.

By utilizing the getMessages function with these parameters and sorting option, you can retrieve messages from a specific subchannel while applying additional filters based on tags and including or excluding deleted messages. This provides a flexible and efficient way to fetch and manage messages within your chat or messaging application.

import { MessageRepository } from '@amityco/js-sdk';
​
const liveCollection = MessageRepository.queryMessages({
  channelId: 'channelId',
  parentId: parentIdValue,
  filterByParentId: true,
  tags: ['summer2021']
  excludeTags: ['awful_hotel']
});

Threaded Messages

Querying threaded messages allows users to retrieve the replied (children) messages associated with a specific message thread. When a message serves as the root of a thread, you can use the parentId parameter in a message query to fetch its child messages.

To query threaded messages, you can add the following parameters to your message query:

• parentId: This parameter specifies the ID of the parent message. By providing the parentId, you are indicating that you want to retrieve the child messages associated with that specific parent message.

• filterByParentId: This flag enables the filtering of messages based on their parent ID. By setting this flag, the query will only return messages that have the specified parentId.

By including the parentId parameter and setting the filterByParentId flag in your message query, you can retrieve the child messages of a particular message thread. This functionality allows for structured and organized conversations within your chat or messaging application, enabling users to navigate and explore threaded discussions with ease.

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

const liveCollection = MessageRepository.queryMessages({
  channelId: 'channel1',
  parentId: 'exampleParentMessageId',
  filterByParentId: true,
});

Navigating(Jump) to a specific message

To locate a specific message within a chatroom, you can use the index of the message in the collection if known. However, there may be cases where the desired message, such as a reply to a much older message, is not in the current collection. In such instances, it's essential to perform a message query. The SDK offers an additional parameter for message queries called aroundMessageId, which retrieves the target message along with its preceding and following messages.

Using a message query with aroundMessageId generates a new live collection. The application's decision to perform data swapping depends on the query's result. Typically, data swapping should not be executed in case of a business error, such as using an invalid target messageId or a messageId associated with a deleted message for aroundMessageId. Upon a successful query, the application can proceed with the source swap, locate the index of the target message, and scroll to that specific position.

In cases where there is a business error but no existing source (e.g., entering a chatroom via push notification), the application can recover by querying for the latest message using a message query without aroundMessageId.

After swapping the source, most, if not all, of the messages from the previous source will likely no longer be available in the new one. To enable users to navigate back to the message they jumped from, they can scroll through the pages manually. However, the application can also facilitate this by caching the messageId of the message they jumped from and offering a floating button as a shortcut to navigate back. This functionality can be achieved by leveraging a message query and using the cached messageId as the value for aroundMessageId.

Send an Image Message

Image message is a type of message that includes an image file. It allows users to share visual information with others in a chat. Image messages can be used in a variety of ways, such as sharing photos with friends, sending documents, or any other visual content that needs to be shared quickly and easily. With image messages, users can easily convey information to others in a chat, making it a powerful tool for communication.

When calling this function, you can provide the local image path on the device and the ID of the subchannel where the message will be sent. The SDK will create an image message with the specified image and send it to the subchannel.

For further information regarding a video information please refer to Image Handling page.

Here is a brief explanation of the function parameters:

• text/caption: A string that contains the text message that the user wants to send. This parameter is mandatory as it contains the actual message content.

• attachment: The local image path that the user wants to send on the device

• subchannelId: An identifier for the subchannel where the message will be sent. Subchannels are subdivisions within a channel that represent individual topics or chat threads. Messages and interactions occur within subchannels, not the main channel itself.

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

import { FileRepository, MessageRepository } from '@amityco/js-sdk';

// this function takes in input a File from a <input type="file" />
const createImageMessage = (file: File) => {
  // first, create the file object.
  const liveFile = FileRepository.createFile({ file })

  // second, create the message object with the fileId from the liveFile
  const liveMessage = MessageRepository.createImageMessage({
    channelId: 'my-channel',
    imageId: liveFile.model.fileId,
    caption: 'have a look!',
    tags: ['tag1', 'tag2'],
  })
}ja

Image Upload & Sizing

The SDK will resize and process the image object before sending it to the server. When an image is uploaded, it is automatically resized into multiple sizing options.

The size of the image is determined by its longest dimension (in pixels) with the aspect ratios being unchanged. The maximum file size of an image cannot exceed 1 GB.‌ Amity will automatically optimize the image and when queried, will return the image in small, medium and large sizes.

If the image is marked as isFull on upload, the original size of the image can also be returned. Note that this can drastically reduce the speed of message sending, depending on the original image size. If the fullImage is set to false, then the uploaded image size will be up to 1500x1500 pixel.

You can also pass an optional caption as part of the message. This caption will be accessible under the data property in the message model, under the caption key. You can add up to 1,000 characters of text caption per message.

Send a Custom Message

If you'd like to display content on your app that cannot be represented by the available text, image, video, and file message types, you can create your own custom message type. Custom message type allows you to include the necessary data for rendering, such as additional metadata and custom data formatting. This is useful if you want to present specific types of content to your users.

Here is a brief explanation of the function parameters:

• data: A free-form JSON object that can be customized based on your use cases.

• subchannelId: An identifier for the subchannel where the message will be sent. Subchannels are subdivisions within a channel that represent individual topics or chat threads. Messages and interactions occur within subchannels, not the main channel itself.

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

import { MessageRepository, MessageType } from '@amityco/js-sdk';

const messageLiveObject = MessageRepository.createMessage({
  channelId: 'channel1',
  type: MessageType.Custom,
  data: {
    customField1: 'customValue1',
    customField2: 'customValue2',
  }
  tags: ['tag1', 'tag2'],
  mentionees: [{type: 'user', userIds: ['user1', 'user2']}],
});
Previous
Audio Message
Next
Viewing Mesages

In addition to creating top-level messages, Amity Chat SDK also allows you to reply to existing messages. To reply to a message, you'll need to specify the parent message's parentMessageId as one of the parameters. This allows the SDK to associate the new message as a reply to the parent comment.

Similar to creating a top-level message, you can use the SDK's optimistic creation feature to create a reply message.

import { MessageRepository } from '@amityco/js-sdk'
​
const message = { ... };
​
MessageRepository.createTextMessage({
  channelId: 'channelId',
  text: 'reply message',
  parentId: message.messageId
});

Mentions allow users to tag other users in messages. It's a powerful tool for fostering engagement and collaboration within your social application. With mentions, users can easily notify specific individuals or groups to new content or important updates. In the SDK, mentions can be implemented in a range of ways, depending on your application's needs and user experience. For more information about mentions, please refer to Mentions. We only support the ability to mention in only these channel types:

• Community

• Live

Create Message with Mentions

You can easily mention users when creating a message by including their user IDs in the mention user parameter as well as defining metadata for mention rendering. For further explanation, please refer to #mention-users. We offer two types of mentions that can be included in a message:

Mention Users

When using this type of mention, up to 30 channel members can be notified through push notifications. Each individual member mentioned in the message will receive a notification.

import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';

MessageRepository.createTextMessage({
  channelId: 'channelId',
  text: 'hi @user1 @user2',
  mentionees: [{ type: MentionType.User, userIds: ['userId1', 'userId2'] }],
  metadata: MessageTools.createMentionMetadata([
    { type: MentionType.User, userId: 'userId1', index: 3, length: 5 },
    { type: MentionType.User, userId: 'userId2', index: 10, length: 5 },
  ]),
});

Mention Channel

By specifying the channel ID in the mention channel parameter when creating a message, push notifications will be sent to all members of that channel when this type of mention is used.

import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';

MessageRepository.createTextMessage({
  channelId: 'channelId',
  text: 'hi @all',
  mentionees: [{ type: MentionType.Channel }],
  metadata: MessageTools.createMentionMetadata([
    { type: MentionType.Channel, index: 3, length: 3 },
  ]),
});

Update Message with Mentions

We provide developers with an efficient method for updating messages with mentions of specific users, you can easily add mentions to their post updates and but it will not notify the relevant users.

To remove mentions you can provide an empty JSON object for the metadata parameter, and an empty list for the mention users parameter. By doing so, You can easily remove mentions from the post content, while ensuring that the overall structure of the post remains intact.

import { MentionType, MessageRepository, MessageTools } from '@amityco/js-sdk';

MessageRepository.updateMessage({
  messageId: 'messageId',
  data: { text: 'hi @user3' },
  mentionees: [{ type: MentionType.User, userIds: ['userId3'] }],
  metadata: MessageTools.createMentionMetadata([{ type: MentionType.User, userId: 'userId3', index: 3, length: 5 }]),
});

Render Mentions

To render mentions in a supported feature, please refer to #render-mentions, specifically the section on handling mentions. This documentation provides detailed information on how to represent mentions in your application, including information on metadata structure, custom mention objects, and rendering support.

Unread Mention Count

When a member is mentioned(mention type could be channel as well) in a text message and the message is not read, then hasMention property is "true" in Channel class. Every time the hasMention property is true, this means that the member has an unread message with mention(message could be created or updated as well).

AmityMessageRepository class provides APIs for you to perform actions on messages you've sent or received. These actions include editing and deleting an existing message, as well as marking a message as being read by you. You can only perform edit and delete operations on messages you've sent.

Edit Messages

You can only perform edit and delete operations on your own messages. When editing a message, the message's editedAtDate will be set to the current time. This allows you to provide UI to the user to inform the user of specific messages that have been edited, if needed. An optional completion block can be provided to notify you of operation success.

import { MessageRepository } from '@amityco/js-sdk';
​
try {
  await MessageRepository.updateMessage({ 
    messageId: 'messageId', 
    data: { text: 'new text' },
  );
  console.log('message is updated');
} catch (error) {
  console.error('can not update message', error);
}

Delete Messages

The delete message functionality allows users to remove a message from a chat or messaging application. This feature provides flexibility and control, allowing users to delete messages they no longer wish to be visible to other participants in the conversation.

By utilizing the delete message function, users can remove a specific message from the chat history. This can be useful in various scenarios, such as correcting mistakes, removing sensitive or inappropriate content, or simply managing the flow of the conversation. Once the message is deleted, it may still be shown as a deleted message with timestamp which depends on the Query and Filter Messages condition.

The delete message function typically requires the messageId as a parameter, which uniquely identifies the message to be deleted. Once the message is deleted, it will no longer be visible to other users in the chat or messaging context.

import { MessageRepository } from '@amityco/js-sdk';
​
try {
  await MessageRepository.deleteMessage('messageId');
  console.log('message is deleted');
} catch (error) {
  console.error('can not delete message', error);
}

To view the content of a message using the Amity Chat SDK, developers can utilize a message object. The message content can then be used to display to the user in a chat interface, or to perform other operations on the message data as needed. This allows developers to build chat applications that support messaging using the Amity Chat SDK and provides a foundation for building more advanced chat applications that require more complex message handling and processing. The Amity Chat SDK provides several methods for viewing messages in a chat channel. Here's how to use these methods in your app:

Get a single message

To get a single message by its ID, use the getting message function of the Amity Chat SDK. This method returns a message live object, which you can use to display the message in your app. Here's an example:

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

const liveObject = MessageRepository.getMessage('messageId');
let message = liveObject.model;

liveObject .on('dataUpdated', data => {
  message = data;
});

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

// unobserve data changes once you are finished
liveObject.dispose();