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

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

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

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:

• Text Message

• Image Message

• Video Message

• Audio Message

• File Message

• Custom Message

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

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