Retrieve Historical Messages
Enable Service
The Cloud Storage for One-to-One and Group Messages service is enabled by default. You can retrieve historical messages for one-to-one and group chats from the RC server directly. If you are using an App Key in the production environment, this service is available for Chat Starter Plan or Chat Pro Plan. For specific features and pricing, refer to the Billing Guide document.
Please distinguish between historical message records and offline messages?. RC provides a default offline message caching service for one-to-one chats, group chats, and system messages for up to 7 days (adjustable). When the client goes online, the SDK automatically retrieves messages from the offline period, and no API calls are required at the App level. For more details, see Manage Offline Message Storage Configuration.
tip
- Whether users can retrieve historical group chat messages before joining the group depends on the App's settings in the Console. You can enable Retrieve group history when not in group in the RC Console under Chat > Chat settings > One-to-One and Group Chats > Retrieve group history when not in group. Enabling this option allows new group members to retrieve all group chat messages sent before they joined the group. If not enabled, new group members can only see group chat messages sent after they joined.
- By default, users who are not in a group cannot retrieve historical messages from that group. If you want users to be able to retrieve historical group messages even when they are not in the specified group, you can allow this by navigating to Chat > Chat settings > One-to-One and Group Chats > Retrieve group history when not in group in the RC Console.
Retrieve Historical Messages
Developers can use this API to retrieve historical messages for a specific conversation.
Method
Future<int> getMessages(RCIMIWConversationType type, String targetId, String? channelId, int sentTime, RCIMIWTimeOrder order, RCIMIWMessageOperationPolicy policy, int count, {IRCIMIWGetMessagesCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| type | RCIMIWConversationType | Conversation type |
| targetId | String | Conversation ID |
| channelId | String | Channel ID, only supported for ultra groups. For other conversation types, pass null. |
| sentTime | int | Current message timestamp |
| order | RCIMIWTimeOrder | Direction of message retrieval. BEFORE: Retrieve messages before sentTime (in descending order), AFTER: Retrieve messages after sentTime (in ascending order) |
| policy | RCIMIWMessageOperationPolicy | Message loading policy. LOCAL: Load only local messages, REMOTE: Load only remote messages, LOCAL_REMOTE: Load both local and remote messages |
| count | int | Number of messages to retrieve, range: greater than 0 and less than or equal to 20 |
| callback | IRCIMIWGetMessagesCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | Status code for the current API operation. 0 indicates success, and the specific result needs to be implemented in the interface callback. Non-zero values indicate that the current API call failed, and no interface callback will be triggered. For detailed errors, refer to the error codes. |
Code Example
IRCIMIWGetMessagesCallback? callback = IRCIMIWGetMessagesCallback(onSuccess: (List<RCIMIWMessage>? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getMessages(type, targetId, channelId, sentTime, order, policy, count, callback:callback);
Callback Method
- onMessagesLoaded
Function(int? code, RCIMIWConversationType? type, String? targetId, String? channelId, int? sentTime, RCIMIWTimeOrder? order, List<RCIMIWMessage>? messages)? onMessagesLoaded;
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| code | int | Status code for the interface callback. 0 indicates success, non-zero indicates an exception. |
| type | RCIMIWConversationType | Conversation type |
| targetId | String | Conversation ID |
| channelId | String | Channel ID, only supported for ultra groups. For other conversation types, pass null. |
| sentTime | int | Current message timestamp |
| order | RCIMIWTimeOrder | Direction of message retrieval. BEFORE: Retrieve messages before sentTime (in descending order), AFTER: Retrieve messages after sentTime (in ascending order) |
| messages | List<RCIMIWMessage> | Retrieved message collection |
Code Example
engine?.onMessagesLoaded = (int? code, RCIMIWConversationType? type, String? targetId, String? channelId, int? sentTime, RCIMIWTimeOrder? order, List<RCIMIWMessage>? messages) {
//...
};
Retrieve Message by messageId
Developers can use this API to retrieve a specific message.
Method
Future<int> getMessageById(int messageId, {IRCIMIWGetMessageCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| messageId | int | The messageId of the message, which can be obtained from the message object. |
| callback | IRCIMIWGetMessageCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | Status code for the current API operation. 0 indicates success, and the specific result needs to be implemented in the interface callback. Non-zero values indicate that the current API call failed, and no interface callback will be triggered. For detailed errors, refer to the error codes. |
Code Example
IRCIMIWGetMessageCallback? callback = IRCIMIWGetMessageCallback(onSuccess: (RCIMIWMessage? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getMessageById(messageId, callback:callback);
Retrieve Message by messageUId
Developers can use this API to retrieve a specific message.
Method
Future<int> getMessageByUId(String messageUId, {IRCIMIWGetMessageCallback? callback});
Parameter Description
| Parameter | Type | Description |
|---|---|---|
| messageUId | String | The of the message, which can be obtained from the message object. Only successfully sent messages will have this value. |
| callback | IRCIMIWGetMessageCallback | Event callback. The SDK supports callback-based responses starting from version 5.3.1. Other callback methods for this interface are deprecated as of version 5.4.0. If the callback parameter is provided, only the callback will be triggered. |
Return Value
| Return Value | Description |
|---|---|
| Future<int> | Status code for the current API operation. 0 indicates success, and the specific result needs to be implemented in the interface callback. Non-zero values indicate that the current API call failed, and no interface callback will be triggered. For detailed errors, refer to the error codes. |
Code Example
IRCIMIWGetMessageCallback? callback = IRCIMIWGetMessageCallback(onSuccess: (RCIMIWMessage? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getMessageByUId(messageUId, callback:callback);