Retrieve Chatroom History Messages

The IMLib SDK supports retrieving chatroom history messages with the following capabilities:

• Use getHistoryMessages to fetch chatroom history messages stored locally. Note that chatroom messages stored locally are automatically cleared when users exit the chatroom by default.
• Use getRemoteChatroomHistoryMessages to retrieve chatroom history messages stored on the server. This feature requires the Cloud Storage for Chatroom Messages service. To enable this service, please submit a ticket.

Enable the Service

Using getRemoteChatroomHistoryMessages requires enabling the Cloud Storage for Chatroom Messages service. To enable this service, please submit a ticket. Once enabled, chatroom history messages are stored in the cloud by default for 2 months.

Retrieve Local Chatroom History Messages

You can use getHistoryMessages to fetch local chatroom history records. By default, the chatroom service clears locally stored history messages when users exit the chatroom.

API Prototype

- (void)getHistoryMessages:(RCConversationType)conversationType
                  targetId:(NSString *)targetId
           oldestMessageId:(long)oldestMessageId
                     count:(int)count
                completion:(nullable void(^)(NSArray<RCMessage *> *_Nullable messages))completion;

Parameter Description

The count parameter specifies the number of messages to return. The oldestMessageId parameter controls pagination boundaries. Each call to getHistoryMessages uses the message referenced by oldestMessageId as a boundary to fetch the specified number of messages from the next page. Set oldestMessageId to -1 to retrieve the latest count messages in the conversation.

tip

We recommend using the messageId of the earliest message in the returned results as the oldestMessageId for subsequent calls to traverse the entire conversation history.

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type
targetId	NSString	Target ID of the conversation
oldestMessageId	long	Pagination boundary. Fetches count messages with timestamps earlier than this messageId. Set to -1 or 0 to retrieve the latest count messages.
count	int	Number of messages to fetch, ordered from newest to oldest by send time
completion	Block	Asynchronous callback returning an array of RCMessage objects

Example Code

[[RCCoreClient sharedCoreClient] getHistoryMessages:ConversationType_CHATROOM
                                           targetId:@"targetId" 
                                    oldestMessageId:-1 
                                              count:10
                                         completion:^(NSArray<RCMessage *> * _Nullable messages) {

}];

Retrieve Remote Chatroom History Messages

Use getRemoteChatroomHistoryMessages to fetch remote chatroom history records. If local messages exist for the same period, this API returns an empty array. Therefore, first call getHistoryMessages to check local history. If empty, then call getRemoteChatroomHistoryMessages to retrieve remote records.

API Prototype

- (void)getRemoteChatroomHistoryMessages:(NSString *)targetId
                              recordTime:(long long)recordTime
                                   count:(int)count
                                   order:(RCTimestampOrder)order
                                 success:(nullable void (^)(NSArray<RCMessage *> *messages, long long syncTime))successBlock
                                   error:(nullable void (^)(RCErrorCode status))errorBlock;

Parameter Description

The successBlock returns the fetched message array and syncTime. For RC_Timestamp_Desc order, syncTime is the timestamp of the earliest message (minimum timestamp). For RC_Timestamp_Asc order, it's the latest message's timestamp (maximum timestamp). With consistent ordering, the returned syncTime can be used as the next call's recordTime for continuous fetching.

Parameter	Type	Description
targetId	NSString	Chatroom ID (max 64 characters)
recordTime	long long	Message timestamp (ms) to fetch messages before or after this time
count	int	Number of messages to fetch (max 200)
order	RCTimestampOrder	Fetch order: RC_Timestamp_Desc (descending) gets messages before recordTime; RC_Timestamp_Asc (ascending) gets messages after recordTime. Default: descending.
successBlock	Block	Success callback
errorBlock	Block	Failure callback returning error code RCErrorCode

Example Code

[[RCChatRoomClient sharedChatRoomClient] getRemoteChatroomHistoryMessages:@"targetId" recordTime:0 count:1 order:RC_Timestamp_Desc success:^(NSArray<RCMessage *> * _Nonnull messages, long long syncTime) {

} error:^(RCErrorCode status) {
}];