Message overview

In real-time messaging apps, messages are transmitted from the message sender to the message receiver. This page provides overview to the message types and message features supported by the Chat SDK.

The Chat SDK supports the following types of messages.

The message content is text, including hyperlinks and emojis. The maximum data length of a text message is 3 KB.

Image messages are essentially attachment messages. To send an image message, you need to upload the image to the chat server. When the recipient receives the message, the SDK automatically downloads the image thumbnail. The image cannot exceed 10 MB and the maximum data length of an image message is 3 KB.

Voice messages are essentially attachment messages. To send a voice message, you need to upload the audio file to the chat server. When the recipient receives a voice message, the SDK automatically downloads the audio file. The voice file cannot exceed 10 MB and the maximum data length of a voice message is 3 KB.

Video messages are essentially attachment messages. To send a video message, you need to upload the video file to the chat server. When the recipient receives a video message, the SDK automatically downloads the video file thumbnail. To download the video file, the user needs to tap the thumbnail. The video file cannot exceed 10 MB and the maximum data length of a video message is 3 KB.

File messages are essentially attachment messages. To send a file message, you need to upload the file to the chat server. When the recipient receives a file message, the SDK automatically downloads the file. The attachment cannot exceed 10 MB and the maximum data length of a file message is 3 KB.

To send location messages, you need to use a third-party map service provider to get the longitude and latitude information of the location. When the recipient receives a location message, the SDK displays the location in the third-party map service provider according to the longitude and latitude information.

Command messages tell the recipient to take a certain action. After receiving a command message, the recipients deal with the command themselves. You do not need to render command messages on the user interface. You can use command messages to update the avatar and nickname and synchronize this update. Command messages are not stored in the local database. The maximum data length of a command message is 3 KB.

In cases where text, attachment, and location messages do not meet your business requirement, you can use extended messages. One typical use case is sending messages that quote an earlier text or image message. The data length of an extended message must not exceed that of the original message type.

This is a self-defined message type. You can customize multiple message types and add a name to each type. Typical use cases are red-packet messages and template messages. The maximum data length of a custom message is 3 KB.

The Chat SDK supports sending and receiving messages, managing historical messages, and managing message read receipts.

You can implement the following features with the chat APIs.

All chat users can send and receive messages.

• In one-to-one chats, two users send messages to each other.
• In chat groups, group members send and receive messages in the chat group.
• In chat rooms, chat room members send and receive messages in the chat room.

In the scenarios above, the messages between the two users, in each chat group, and in each chat room are also known as a conversation.

The Chat SDK stores the messages that have been sent and received in the local database. You can manage these messages by retrieving all the conversations on the local device.

You can retrieve the messages of the specified conversation. When a user enters the conversation, this user reads all the messages in this conversation.

Since messages are stored with the read status, you can also retrieve the number of the unread messages in each conversation.

Once you read all the messages, the number of the unread messages are cleared. You can also clear the number of unread messages of the specified conversation or all the conversations.

You can delete the conversations on the local device, and while doing so, you can choose whether to clear the chat history or not.

You can search the message in a conversation using key words.

You can import messages from third-party apps into the local database.

You can insert a message to the conversation. This can be applied to use cases such as receiving a notification message.

Apart from the local device, you can also retrieve conversations from the server.

The Chat SDK stores historical messages in the chat server, and you can retrieve historical messages in each conversation from the server with pagination. The time duration for storing historical messages varies according to your pricing plan. See Limitations of message storage duration.

• For Android and iOS, the message resending mechanism is as follows:

After the client calls the method of sending a message, it will wait for the server to return a response. The response timeout period is 10 seconds. If the sending fails due to a response timeout, the client will try to send the message again by reconnecting to the server through a persistent connection to send the message. If the sending fails again, the SDK considers the sending of the message failed, and returns error code 300 and the error message SERVER_NOT_REACHABLE, indicating that the server is unreachable.

• For Web, the message resending mechanism is as follows:

When sending a message, if the WebSocket is disconnected and is reconnecting to the server, the message will be resent after reconnection; if the WebSocket is disconnected during message sending, the SDK will display error code 510 and the error message MESSAGE_WEBSOCKET_DISCONNECTED , indicating that the network disconnection caused the message sending failure.

The SDK supports sending a message delivery receipt when the message is successfully sent.

In one-to-one chats and group chats, the SDK supports sending a message read receipt when the message receiver has read the message.

The storage duration for historical messages varies according to your pricing plans:

Chat plan	Message storage duration (days)
Free	7 days
Starter	90 days
Pro	180 days
Enterprise	Custom (180 days by default)

Message attachments like images, voices, videos, and other files can be stored on the server for seven days by default. To raise the limit, you can contact support@agora.io.