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

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

const liveObject = MessageRepository.createTextMessage({
  channelId: 'channel1',
  text: 'Hello World!',
});

liveObject.on('dataUpdate', message => {
  console.log('message is created', message);
});

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

const messageLiveObject = MessageRepository.createTextMessage({
  channelId: 'channel1',
  text: 'Hello World!',
  parentId: 'exampleParentMessageId,
  tags: ['tag1', 'tag2'],
  mentionees: [
    {
      "type": "user",
      "userIds": [
        "user1", “user2”
      ]
    }
  ]
});

Send an Audio Message

An audio message is a type of message that allows users to send and receive audio recordings in a chat or messaging application. Audio messages can be used to convey emotions, tone, or detailed information in a way that is not always possible with text messages or other types of media. They are a convenient and intuitive way to communicate with other users in real-time.

With the Amity Chat SDK, you can easily send and receive audio messages within your chat or messaging application. Simply provide the local path of the audio file to the sendAudioMessage method.

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

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

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.

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

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

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

// this function takes in input a File from a <input type="file" />
const createFileMessage = (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.createFileMessage({
    channelId: 'my-channel',
    fileId: id, // id of the file created with FileRepository.createFile
    caption: 'have a look!',
    tags: ['tag1', 'tag2'],
  })
}ja

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

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

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.

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.

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.

The Social SDK product also provides functionality for adding and removing reactions on messages. Users can add any number of reactions to a particular message, allowing them to engage with the content in a more expressive and nuanced way. Additionally, users can also remove reactions that they have added to a message, providing greater control and flexibility over their engagement with the content.

Add Reaction

The addReaction function allows users to add a reaction to a message. The function takes the name of the reaction as a parameter, with a maximum length of 100 characters. The reaction name is case-sensitive, which means that "like" and "Like" are treated as two different reactions.

• referenecId - ID of the message.

• reactionName - name of the reaction that you will remove. Reaction name is case sensitive, i.e "like" & "Like" are two different reactions.

Remove Reaction

You can remove a reaction from a reference by calling removeReaction.

• reactionName - name of the reaction that you will remove. Reaction name is case sensitive, i.e "like" & "Like" are two different reactions.

• referenecId - ID of the message.

Reaction Query

To further facilitate the management of reactions in your app, the Chat SDK product includes a getReactions method that allows you to retrieve information about a specific reaction or all reactions on a message.

Using this method, you can fetch detailed information about a particular reaction, including the user who made the reaction, the timestamp of the reaction, and any additional metadata associated with the reaction. This can be useful for analyzing the sentiment of the community and gaining insights into the types of content that are resonating with your users.

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

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.

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.

Render Mentions

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.

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.

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.

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:

Get messages with a query

View a message

Text Message

This is the most basic type of message, and is useful for sending simple messages such as chat messages, system notifications, or status updates. Each text message has a character limit of 20,000 characters, making it suitable for sending concise messages.

Image Message

Sending visual content such as photos, graphics, or images in a channel is facilitated by this type of message. The maximum size for an image is 1 GB, and the image will be automatically transformed into four different sizes for versatile usage which are:

• Small

• Medium

• Large

• Full

File Message

Video Message

This is a useful type of message for sharing video content within a chat conversation, such as a short clip or a longer video. The maximum size for a video is 1 GB, and the video will be automatically transcoded into different resolutions for versatile usage which are

• 1080p

• 720p

• 480p

• 360p

• original

Custom Message

In addition to the built-in message types such as text, image, file, audio, and video, the Amity Chat SDK also provides support for "custom messages". Custom messages allow users to design their own JSON structure that can be used to represent any kind of data, essentially providing the freedom to create their own message types.

This can be useful for a variety of use cases. For example, a developer building a chat application for a sports team could use custom messages to create a "score update" message type that contains data such as the score of a game, the time remaining, and other relevant information. Similarly, a developer building a chat application for an e-commerce platform could use custom messages to create a "product update" message type that contains information such as product details, availability, pricing, and other relevant data.

The possibilities for custom messages are endless, and can be tailored to the specific needs of any application. Custom messages can be sent and received using the Amity Chat SDK, and can be queried and displayed in a chat channel just like any other message type.

Flag a Message

The Chat SDK product also includes a flag method that allows users to flag messages in their app. Once a message is flagged, an indicator will appear in the Admin console, where an administrator can review and validate the flag. If the content is found to be in violation of your app's policies, it can be deleted from the app. On the other hand, if the content is not found to be in violation, the flag can be revoked.

The flag method provides an essential tool for managing user-generated content in your app, ensuring that inappropriate messages can be quickly identified and removed. By integrating this method into your app's user interface, you can empower your users to take an active role in promoting a safe and respectful community.

To use the function you simply need to identify the messageId that you'd like to flag.

Unflag a Message

Another useful feature is the unflag method, which enables users to revoke a previously flagged message. If a user flags a message by mistake or if the message is found not to violate your app's policies after review, the unflag method can be used to remove the flag from the message. It ensures that users have control over the content they flag and the ability to reverse their flag if necessary.

Similar to the flag function, you simply need to identify the messageId that you'd like to unflag.

Check if Message is Flagged

The isFlaggedByMe method allows users to check whether they have previously flagged a particular message. This method provides a convenient way for users to keep track of the content they have flagged and to ensure that they are staying up-to-date with their moderation activities.

By using the isFlaggedByMe method, your app's users can quickly determine whether they have already flagged a particular message and avoid duplicating their efforts.