Skip to main content

You are viewing Agora Docs forBetaproducts and features. Switch to Docs

Android
iOS
Web
Windows
Unity
Flutter
React Native

Send and receive messages

After logging in to Chat, users can send the following types of messages to a peer user, a chat group, or a chat room:

  • Text messages, including hyperlinks and emojis.
  • Attachment messages, including image, voice, video, and file messages.
  • Location messages.
  • CMD messages.
  • Extended messages.
  • Custom messages.

The Chat message feature is language agnostic. End users can send messages in any language, as long as their devices support input in that language.

In addition to sending messages, users can also forward one or more messages. When forwarding multiple messages, users have the following options:

  • Forward messages one-by-one
  • Forward combined messages as message history

This page shows how to implement sending, receiving, forwarding multiple messages, and modifying sent messages using the Chat SDK.

Understand the tech

The Chat SDK uses the ChatManager class to send, receive, and withdraw messages.

The process of sending and receiving a message is as follows:

  1. The message sender creates a text, file, or attachment message using the corresponding create method.
  2. The message sender calls sendMessage to send the message.
  3. The message recipient calls addMessageListener to listens for message events and receives the message in the OnMessageReceived callback.

Prerequisites

Before proceeding, ensure that you meet the following requirements:

  • You have integrated the Chat SDK, initialized the SDK, and implemented the functionality of registering accounts and login. For details, see Chat SDK quickstart.

    Use Chat SDK 1.2 or higher if you intend to enable users to forward multiple messages, or to modify sent messages.

  • You understand the API call frequency limits as described in Limitations.

Implementation

This section shows how to implement sending and receiving the various types of messages.

Send a text message

Use the ChatMessage class to create a text message, and send the message.


_8
// Call createTextSendMessage to create a text message.
_8
// Set `content` as the content of the text message.
_8
// Set `conversationId` to the user ID of the peer user in one-to-one chat, group ID in group chat, and chat room ID in room chat.
_8
ChatMessage message = ChatMessage.createTextSendMessage(content, conversationId);
_8
// Set `ChatType` as `Chat`, `GroupChat`, or `ChatRoom` for one-to-one chat, group chat, or room chat.
_8
message.setChatType(ChatMessage.GroupChat);
_8
// Send the message.
_8
ChatClient.getInstance().chatManager().sendMessage(message);


_14
// Call setMessageStatusCallback to set the callback instance to get the status of messaging sending.
_14
// You can update the status of messages in this callback, for example, adding a tip when the message sending fails.
_14
message.setMessageStatusCallback(new CallBack() {
_14
@Override
_14
public void onSuccess() {
_14
showToast("Message sending succeeds");
_14
dialog.dismiss();
_14
}
_14
@Override
_14
public void onError(int code, String error) {
_14
showToast("Message sending fails");
_14
}
_14
});
_14
ChatClient.getInstance().chatManager().sendMessage(message);

Set message priority

In high-concurrency scenarios, you can set a certain message type or messages from a chat room member as high, normal, or low priority. In this case, low-priority messages are dropped first to reserve resources for the high-priority ones, for example, gifts and announcements, when the server is overloaded. This ensures that the high-priority messages can be dealt with first when loads of messages are being sent in high concurrency or high frequency. Note that this feature can increase the delivery reliability of high-priority messages, but cannot guarantee the deliveries. Even high-priorities messages can be dropped when the server load goes too high.

You can set the priority for all types of messages in the chat room.


_5
ChatMessage message = ChatMessage.createTextSendMessage(content, conversationId);
_5
message.setChatType(ChatMessage.ChatType.ChatRoom);
_5
// Set the message priority. The default value is `Normal`, indicating the normal priority.
_5
message.setPriority(ChatMessage.ChatRoomMessagePriority.PriorityHigh);
_5
sendMessage(message);

Receive a message

You can use MessageListener to listen for message events. You can add multiple MessageListeners to listen for multiple events. When you no longer listen for an event, ensure that you remove the listener.

When a message arrives, the recipient receives an onMessagesReceived callback. Each callback contains one or more messages. You can traverse the message list, and parse and render these messages in this callback.


_11
MessageListener msgListener = new MessageListener() {
_11
// Traverse the message list, and parse and render the messages.
_11
@Override
_11
public void onMessageReceived(List<ChatMessage> messages) {
_11
}
_11
};
_11
// Add a message listener
_11
ChatClient.getInstance().chatManager().addMessageListener(msgListener);
_11
// Remove a message listener
_11
ChatClient.getInstance().chatManager().removeMessageListener(msgListener);
_11
ChatClient.getInstance().chatManager().removeMessageListener(msgListener);

Recall a message

After a message is sent, you can recall it. The recallMessage method recalls a message that is saved both locally and on the server, whether it is a historical message, offline message or a roaming message on the server, or a message in the memory or local database of the message sender or recipient.

The default time limit for recalling a message is two minutes. You can extend this time frame to up to 7 days in Agora Console. To do so, select a project that enables Agora Chat, then click Configure > Features > Message recall.

message-recall

Except CMD messages, you can recall all types of message.

_7
try {
_7
ChatClient.getInstance().chatManager().recallMessage(message);
_7
EMLog.d("TAG", "Recalling message succeeds");
_7
} catch (ChatException e) {
_7
e.printStackTrace();
_7
EMLog.e("TAG", "Recalling message fails: "+e.getDescription());
_7
}

You can also use onMessageRecalled to listen for the message recall state:


_4
/**
_4
* Occurs when a received message is recalled.
_4
*/
_4
void onMessageRecalled(List<ChatMessage> messages);

Send and receive an attachment message

Voice, image, video, and file messages are essentially attachment messages. This section introduces how to send these types of messages.

Send and receive a voice message

Before sending a voice message, you should implement audio recording on the app level, which provides the URI and duration of the recorded audio file.

Refer to the following code example to create and send a voice message:


_6
// Set voiceUri as the local URI of the audio file, and duration as the length of the file in seconds.
_6
ChatMessage message = ChatMessage.createVoiceSendMessage(voiceUri, duration, conversationId);
_6
// Sets the chat type as one-to-one chat, group chat, or chatroom.
_6
if (chatType == CHATTYPE_GROUP)
_6
message.setChatType(ChatType.GroupChat);
_6
ChatClient.getInstance().chatManager().sendMessage(message);

When the recipient receives the message, refer to the following code example to get the audio file:


_5
VoiceMessageBody voiceBody = (VoiceMessageBody) msg.getBody();
_5
// Retrieves the URL of the audio file on the server.
_5
String voiceRemoteUrl = voiceBody.getRemoteUrl();
_5
// Retrieves the URI if the audio file on the local device.
_5
Uri voiceLocalUri = voiceBody.getLocalUri();

Send and receive an image message

By default, the SDK compresses the image file before sending it. To send the original file, you can set original as true.

Refer to the following code example to create and send an image message:


_6
// Set imageUri as the URI of the image file on the local device. false means not to send the original image. The SDK compresses image files that exceeds 100K before sending them.
_6
ChatMessage.createImageSendMessage(imageUri, false, conversationId);
_6
// Sets the chat type as one-to-one chat, group chat, or chatroom.
_6
if (chatType == CHATTYPE_GROUP)
_6
message.setChatType(ChatType.GroupChat);
_6
ChatClient.getInstance().chatManager().sendMessage(message);

When the recipient receives the message, refer to the following code example to get the thumbnail and attachment file of the image message:


_10
// Retrieves the thumbnail and attachment of the image file.
_10
ImageMessageBody imgBody = (ImageMessageBody) message.getBody();
_10
// Retrieves the image file the server.
_10
String imgRemoteUrl = imgBody.getRemoteUrl();
_10
// Retrieves the image thumbnail from the server.
_10
String thumbnailUrl = imgBody.getThumbnailUrl();
_10
// Retrives the URI of the image file on the local device.
_10
Uri imgLocalUri = imgBody.getLocalUri();
_10
// Retrieves the URI of the image thumbnail on the local device.
_10
Uri thumbnailLocalUri = imgBody.thumbnailLocalUri();

If ChatClient.getInstance().getOptions().getAutodownloadThumbnail() is set as true on the recipient's client, the SDK automatically downloads the thumbnail after receiving the message. If not, you need to call ChatClient.getInstance().chatManager().downloadThumbnail(message) to download the thumbnail and get the path from the thumbnailLocalUri member in messageBody.

Send and receive a video message

Before sending a video message, you should implement video capturing on the app level, which provides the duration of the captured video file.

Refer to the following code example to create and send a video message:


_3
String thumbPath = getThumbPath(videoUri);
_3
ChatMessage message = ChatMessage.createVideoSendMessage(videoUri, thumbPath, videoLength, conversationId);
_3
sendMessage(message);

By default, when the recipient receives the message, the SDK downloads the thumbnail of the video message.

If you do not want the SDK to automatically download the video thumbnail, set ChatClient.getInstance().getOptions().setAutodownloadThumbnail as false, and to download the thumbnail, you need to call ChatClient.getInstance().chatManager().downloadThumbnail(message), and get the path of the thumbnail from the thumbnailLocalUri member in messageBody.

To download the actual video file, call SChatClient.getInstance().chatManager().downloadAttachment(message), and get the path of the video file from the getLocalUri member in messageBody.


_44
// If you received a message with video attachment, you need download the attachment before you open it.
_44
if (message.getType() == ChatMessage.Type.VIDEO) {
_44
VideoMessageBody messageBody = (VideoMessageBody)message.getBody();
_44
// Get the URL of the video on the server.
_44
String videoRemoteUrl = messageBody.getRemoteUrl();
_44
// Download the video.
_44
ChatClient.getInstance().chatManager().downloadAttachment(message);
_44
// Set Callback to know whether the download is finished.
_44
public void onError(final int error, String message) {
_44
EMLog.e(TAG, "offline file transfer error:" + message);
_44
runOnUiThread(new Runnable() {
_44
@Override
_44
public void run() {
_44
if (EaseShowBigImageActivity.this.isFinishing() || EaseShowBigImageActivity.this.isDestroyed()) {
_44
return;
_44
}
_44
image.setImageResource(default_res);
_44
pd.dismiss();
_44
if (error == Error.FILE_NOT_FOUND) {
_44
Toast.makeText(getApplicationContext(), R.string.Image_expired, Toast.LENGTH_SHORT).show();
_44
}
_44
}
_44
});
_44
}
_44
public void onProgress(final int progress, String status) {
_44
EMLog.d(TAG, "Progress: " + progress);
_44
final String str2 = getResources().getString(R.string.Download_the_pictures_new);
_44
runOnUiThread(new Runnable() {
_44
@Override
_44
public void run() {
_44
if (EaseShowBigImageActivity.this.isFinishing() || EaseShowBigImageActivity.this.isDestroyed()) {
_44
return;
_44
}
_44
pd.setMessage(str2 + progress + "%");
_44
}
_44
});
_44
}
_44
};
_44
_44
msg.setMessageStatusCallback(callback);
_44
ChatClient.getInstance().chatManager().downloadAttachment(msg);
_44
// After the download finishes, get the URI of the local file.
_44
Uri videoLocalUri = messageBody.getLocalUri();
_44
}

Send and receive a file message

Refer to the following code example to create, send, and receive a file message:


_4
// Set fileLocalUri as the URI of the file message on the local device.
_4
ChatMessage message = ChatMessage.createFileSendMessage(fileLocalUri, conversationId);
_4
// Sets the chat type as one-to-one chat, group chat, or chatroom.
_4
if (chatType == CHATTYPE_GROUP) message.setChatType(ChatType.GroupChat);ChatClient.getInstance().chatManager().sendMessage(message);

While sending a file message, refer to the following sample code to get the progress for uploading the attachment file:


_19
// Calls setMessageStatusCallback to set the callback instance to listen for the state of messaging sending. You can update the message states in this callback.
_19
message.setMessageStatusCallback(new CallBack() {
_19
@Override
_19
public void onSuccess() {
_19
showToast("Message sending succeeds");
_19
dialog.dismiss();
_19
}
_19
@Override
_19
public void onError(int code, String error) {
_19
showToast("Message sending fails");
_19
}
_19
_19
// The status of sending the message. This only applies to sending attachment files.
_19
@Override
_19
public void onProgress(int progress, String status) {
_19
_19
}
_19
});
_19
ChatClient.getInstance().chatManager().sendMessage(message);

When the recipient receives the message, refer to the following code example to get the attachment file:


_5
NormalFileMessageBody fileMessageBody = (NormalFileMessageBody) message.getBody();
_5
// Retrieves the file from the server.
_5
String fileRemoteUrl = fileMessageBody.getRemoteUrl();
_5
// Retrieves the file from the local device.
_5
Uri fileLocalUri = fileMessageBody.getLocalUri();

Send a location message

To send and receive a location message, you need to integrate a third-party map service provider. When sending a location message, you get the longitude and latitude information of the location from the map service provider; when receiving a location message, you extract the received longitude and latitude information and displays the location on the third-party map.


_6
// Sets the latitude and longitude information of the address.
_6
ChatMessage message = ChatMessage.createLocationSendMessage(latitude, longitude, locationAddress, conversationId);
_6
// Sets the chat type as one-to-one chat, group chat, or chatroom.
_6
if (chatType == CHATTYPE_GROUP)
_6
message.setChatType(ChatType.GroupChat);
_6
ChatClient.getInstance().chatManager().sendMessage(message);

Send and receive a CMD message

CMD messages are command messages that instruct a specified user to take a certain action. The recipient deals with the command messages themselves.

  • CMD messages are not stored in the local database.
  • Actions beginning with em_ and easemob:: are internal fields. Do not use them.

_10
ChatMessage cmdMsg = ChatMessage.createSendMessage(ChatMessage.Type.CMD);
_10
// Sets the chat type as one-to-one chat, group chat, or chat room.
_10
cmdMsg.setChatType(ChatType.GroupChat);
_10
String action="action1";
_10
// You can customize the action.
_10
CmdMessageBody cmdBody = new CmdMessageBody(action);
_10
// Sets the message recipient: user ID of the recipient for one-to-one chat, group ID for group chat, or chat room ID for a chat room.
_10
cmdMsg.setTo(conversationId);
_10
cmdMsg.addBody(cmdBody);
_10
ChatClient.getInstance().chatManager().sendMessage(cmdMsg);

To notify the recipient that a CMD message is received, use a separate delegate so that users can deal with the message differently.


_11
MessageListener msgListener = new MessageListener()
_11
{
_11
// Occurs when the message is received
_11
@Override
_11
public void onMessageReceived(List<ChatMessage> messages) {
_11
}
_11
// Occurs when a CMD message is received
_11
@Override
_11
public void onCmdMessageReceived(List<ChatMessage> messages) {
_11
}
_11
}

Send a customized message

Custom messages are self-defined key-value pairs that include the message type and the message content.

The following code example shows how to create and send a customized message:


_9
ChatMessage customMessage = ChatMessage.createSendMessage(ChatMessage.Type.CUSTOM);
_9
// Set event as the customized message type, for example, gift.
_9
event = "gift"CustomMessageBody customBody = new CustomMessageBody(event);
_9
// The data type of params is Map<String, String>.
_9
customBody.setParams(params);customMessage.addBody(customBody);
_9
// Sets the message recipient: user ID of the recipient for one-to-one chat, group ID for group chat, or chat room ID for a chat room.
_9
customMessage.setTo(to);
_9
// Sets the chat type as one-to-one chat, group chat, or chat room
_9
customMessage.setChatType(chatType);ChatClient.getInstance().chatManager().sendMessage(customMessage);

Use message extensions

If the message types listed above do not meet your requirements, you can use message extensions to add attributes to the message. This can be applied in more complicated messaging scenarios.


_7
ChatMessage message = ChatMessage.createTextSendMessage(content, conversationId);
_7
// Adds message attributes.
_7
message.setAttribute("attribute1", "value");message.setAttribute("attribute2", true);
_7
// Sends the message
_7
ChatClient.getInstance().chatManager().sendMessage(message);
_7
// Retrieves the message attributes when receiving the message.
_7
message.getStringAttribute("attribute1",null);message.getBooleanAttribute("attribute2", false)

Forward multiple messages

Supported types for forwarded messages include text, images, audio & video files, attachment, and custom messages. A user can create a combined message with a list of original messages and send it. When receiving a combined message, the recipient can select it and other messages to create a new layered combined message. A combined message can contain up to 10 layers of messages, with at most 300 messages at each layer.

To forward and receive combined messages, refer to the following code:

  1. Create a combined message using multiple message IDs:


    _8
    ChatMessage message = ChatMessage.createCombinedSendMessage(title, summary, compatibleText, msgIds, toChatUsername);
    _8
    // Set the chat type:
    _8
    // One-to-one chat: ChatMessage.ChatType.Chat
    _8
    // Group chat: ChatMessage.GroupChat
    _8
    // Room chat: ChatMessage.ChatRoom
    _8
    message.setChatType(ChatMessage.ChatType.Chat);
    _8
    // Send the message
    _8
    ChatClient.getInstance().chatManager().sendMessage(message);

  2. Download and parse combined messages:


    _11
    ChatClient.getInstance().chatManager().downloadAndParseCombineMessage(combinedMessage, new ValueCallBack<List<ChatMessage>>() {
    _11
    @Override
    _11
    public void onSuccess(List<ChatMessage> value) {
    _11
    _11
    }
    _11
    _11
    @Override
    _11
    public void onError(int error, String errorMsg) {
    _11
    _11
    }
    _11
    });

For further details see Multiple messages forwarding limitations.

Modify sent messages

Every end user or chat group member may edit messages that they have sent. The client API below, when called, will allow the SDK to modify a message.

There is no time limit for modifying a message, that is, it can be modified as long as the message is still stored on the server. After the message is modified, the message life cycle, that is, its storage time on the server, is recalculated. For example, a message can be stored on the server for 180 days, and the user modifies it on the 30th day after the message was sent. Instead of remaining 150 days, the message can be now stored on the server for 180 days after successful modification.

In the modified message, the message ID remains unchanged. Only the message content is edited and the following items are added:

  • The operator ID of the user performing the action.
  • The operation time that indicates when the message was edited.
  • The number of times a message is edited (up to 10 times).

For the edited message, except the message body, other information included in the message like the message sender, recipient, and message extension attributes remain unchanged.

To modify a sent message, refer to the following code:

  1. Call asyncModifyMessage with the message ID and the new message body:


    _13
    String newContent="new content";
    _13
    TextMessageBody newTextMessageBody = new TextMessageBody(newContent);
    _13
    ChatClient.getInstance().chatManager().asyncModifyMessage(targetMessage.getMsgId(), newTextMessageBody, new ValueCallBack<ChatMessage>() {
    _13
    @Override
    _13
    public void onSuccess(ChatMessage value) {
    _13
    _13
    }
    _13
    _13
    @Override
    _13
    public void onError(int error, String errorMsg) {
    _13
    _13
    }
    _13
    });

  2. Receive notification of messages modified by other users:


    _16
    // Create a MessageListener object
    _16
    MessageListener messageListener = new MessageListener() {
    _16
    //……
    _16
    _16
    @Override
    _16
    public void onMessageContentChanged(ChatMessage messageModified, String operatorId, long operationTime) {
    _16
    // int operationCount = messageModified.getBody().operationCount();
    _16
    // operatorId and operationTime can also be obtained as follows:
    _16
    // String id = messageModified.getBody().operatorId();
    _16
    // long time = messageModified.getBody().operationTime();
    _16
    }
    _16
    };
    _16
    // Register the messageListener
    _16
    ChatClient.getInstance().chatManager().addMessageListener(messageListener);
    _16
    // Remove the messageListener
    _16
    ChatClient.getInstance().chatManager().removeMessageListener(messageListener);

For further details see Sent message modification limitations.

Next steps

After implementing sending and receiving messages, you can refer to the following documents to add more messaging functionalities to your app:

vundefined