Inserting Messages

The IMLib SDK supports inserting messages into the local database. Messages inserted locally will not be actually sent to the RC server or the other party.

tip

Ensure all inserted messages support client-side local storage; otherwise, errors will occur. See Understanding Message Storage Strategies.
The message insertion interface only adds messages to the local database, so when the app is reinstalled or logged in on another device, the inserted messages will not be synced from the remote server to the local database.

Inserting Outgoing Messages

You can use the insertOutgoingMessage: interface to insert an outgoing message into the local database. The following example uses the insertOutgoingMessage method under RCChannelClient.

tip

Incorrect sentTime may affect message sorting—use with caution!
This interface does not support chatroom conversation types.

Interface Prototype

- (void)insertOutgoingMessage:(RCConversationType)conversationType
                     targetId:(NSString *)targetId
                   sentStatus:(RCSentStatus)sentStatus
                      content:(RCMessageContent *)content
                     sentTime:(long long)sentTime
                   completion:(nullable void(^)(RCMessage *_Nullable message))completion;

For messages inserted into the local database to support message expansion, you must use the insertion method under RCChannelClient; otherwise, the message's expandable property (canIncludeExpansion) cannot be enabled. Local message insertion does not support setting message expansion data. You can set expansion data for the message at an appropriate time after insertion. See [Message Expansion] for details.

Parameter Description

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type.
targetId	NSString	Conversation targetId.
channelId	NSString	Channel ID for ultra group conversations; pass `nil` for non-ultra group conversations.
canIncludeExpansion	BOOL	Whether the message supports expansion. `YES` for expandable; `NO` for non-expandable.
sentStatus	[RCSentStatus]	Message sending status.
content	[RCMessageContent]	Message content.
sentTime	long long	Unix timestamp (in milliseconds) when the message was sent (passing `0` will use the local time for insertion).
completion	Block	Asynchronous callback, returning the inserted [RCMessage] object.

Example Code

RCTextMessage *content = [RCTextMessage messageWithContent:@"Test text message"];

[[RCChannelClient sharedChannelManager]
  insertOutgoingMessage:ConversationType_PRIVATE
  targetId:@"targetId"
  channelId:@"channelId"
  canIncludeExpansion:YES
  sentStatus:SentStatus_SENT
  content:content
  sentTime:sentTime
  completion::^(RCMessage * _Nullable message) {
        
  }];

Inserting Incoming Messages

You can use the insertIncomingMessage: interface to insert a received message into the local database.

tip

Incorrect sentTime may affect message sorting—use with caution!
For versions after 5.6.8, use the RCReceivedStatusInfo object to construct the received message status; for versions before 5.6.8, use the RCReceivedStatus object to construct the message received status.

Interface Prototype

- (void)insertIncomingMessage:(RCConversationType)conversationType
                     targetId:(NSString *)targetId
                 senderUserId:(NSString *)senderUserId
           receivedStatusInfo:(RCReceivedStatusInfo *)receivedStatusInfo
                      content:(RCMessageContent *)content
                     sentTime:(long long)sentTime
                   completion:(nullable void(^)(RCMessage *_Nullable message))completion;

Parameter Description

Parameter	Type	Description
conversationType	[RCConversationType]	Conversation type; pass `ConversationType_PRIVATE` for one-to-one chats.
targetId	NSString	Target ID used to identify the conversation. Note: In one-to-one chats, the target ID is always the peer user ID. For group chats and ultra groups, the conversation IDs are the group ID and ultra group ID, respectively. See the explanation of Target ID in Message Introduction.
senderUserId	NSString	Sender ID.
RCReceivedStatusInfo	[RCReceivedStatusInfo]	Message received status.
content	[RCMessageContent]	Message content.
sentTime	long long	Unix timestamp (in milliseconds) when the message was sent (passing `0` will use the local time for insertion).
completion	Block	Asynchronous callback, returning the inserted [RCMessage] object.

Example Code

RCTextMessage *content = [RCTextMessage messageWithContent:@"Test text message"];
RCReceivedStatusInfo *info = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:0];
[[RCCoreClient sharedCoreClient] insertIncomingMessage:ConversationType_PRIVATE 
                                              targetId:@"targetId" 
                                          senderUserId:@"senderUserId" 
                                    receivedStatusInfo:info 
                                              content:content 
                                             sentTime:0 
                                           completion:^(RCMessage * _Nullable message) {
        
}];

Inserting Message Objects

You can use the following interface to insert a pre-constructed message object into the local database.

tip

Incorrect sentTime may affect message sorting—use with caution!
Starting from IMLib SDK version 5.12.2, RCMessage includes a new disableUpdateLastMessage property to control whether the message updates the conversation's latest message. The default value is NO (updates). Set it to YES to prevent updating the conversation's latest message.

Inserting an outgoing message object:

RCTextMessage *txtMessage = [RCTextMessage messageWithContent:@"Test text message"];
RCMessage *outgoing = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                             targetId:@"targetID"
                                            channelId:@"channelID"
                                            direction:MessageDirection_SEND
                                              content:txtMessage];
outgoing.senderUserId = @"own user id";
outgoing.sentStatus = SentStatus_SENT;
outgoing.canIncludeExpansion = YES; // Set to enable expansion support
outgoing.disableUpdateLastMessage = YES; // Do not update the conversation's latest message

[[RCCoreClient sharedCoreClient] insertMessage:outgoing successBlock:successBlock errorBlock:errorBlock];

Inserting an incoming message object:

RCTextMessage *txtMessage = [RCTextMessage messageWithContent:@"Test text message"];
RCMessage *incoming = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                             targetId:@"targetID"
                                            direction:MessageDirection_RECEIVE
                                              content:txtMessage];
incoming.senderUserId = @"senderUserId";
RCReceivedStatusInfo *statusInfo = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:0];
[statusInfo markAsRead];
incoming.receivedStatusInfo = statusInfo;
incoming.disableUpdateLastMessage = YES; // Do not update the conversation's latest message

[[RCCoreClient sharedCoreClient] insertMessage:incoming successBlock:successBlock errorBlock:errorBlock];

Batch Inserting Messages

RCTextMessage *txtMessage = [RCTextMessage messageWithContent:@"测试文本消息"];
RCMessage *incoming = [[RCMessage alloc] initWithType:ConversationType_PRIVATE
                                             targetId:@"targetID"
                                            direction:MessageDirection_RECEIVE
                                              content:txtMessage];
incoming.senderUserId = @"senderUserId";
RCReceivedStatusInfo *statusInfo = [[RCReceivedStatusInfo alloc] initWithReceivedStatus:0];
[statusInfo markAsRead];
incoming.receivedStatusInfo = statusInfo;
incoming.disableUpdateLastMessage = YES;// 不更新会话最新一条消息

[[RCCoreClient sharedCoreClient] insertMessage:incoming successBlock:successBlock errorBlock:errorBlock];

Batch Inserting Messages

tip

Supported since IMLib SDK 5.1.1.
Starting from version 5.3.0, it is recommended to use the asynchronous method batchInsertMessage: of RCCoreClient which returns corresponding insertion results. The original synchronous interface is deprecated.
Since batch insertion failures in the local database will cause the entire operation to fail, it is recommended to insert in batches. The maximum number of messages per operation is 500, with 10 messages per batch recommended.
This feature does not support chatroom conversation types or ultra group conversation types.

The following properties of RCMessage will be stored, while others will be discarded:

conversationType: Conversation type.
messageUId: Globally unique message ID. After successful message transmission/reception, this ID is generated by the server. Supported since SDK 5.3.5, mainly used for data migration.
targetId: Conversation ID.
messageDirection: Message direction.
senderUserId: Sender ID.
receivedStatus: Receipt status. If the message direction is incoming and receivedStatus is ReceivedStatus_UNREAD, the message is unread. Unread counts will accumulate to the conversation's unread count.
sentStatus: Sending status.
content: Message content.
sentTime: Unix timestamp of message sending in milliseconds, affecting message sorting.
extra: Additional message information.

Interface Prototype

/*!
 Asynchronously batch inserts received messages (messages are only inserted into the local database and not actually sent to the server or recipient)

 @discussion This method does not support chatroom conversation types or ultra group conversation types. Maximum 500 messages per batch, exceeding which returns NO.
 @discussion Unread messages will accumulate to the conversation's unread count.

 @remarks Message Operations
 */


- (void)batchInsertMessage:(NSArray<RCMessage *> *)msgs completion:(nullable void(^)(BOOL))completion;

Parameter Description

Parameter	Type	Description
msgs	NSArray	List of RCMessage objects. Maximum 500 messages per operation, with 10 messages per batch recommended. Note: `message` must contain a valid `sentTime` (Unix timestamp in milliseconds), otherwise the message cannot be retrieved from the database via the history message API.
completion	Block	Asynchronous callback returning insertion success status

The following method is provided for batch insertion. When checkDuplicate is set to YES, the IMLib SDK will check if the messageUId of the current message duplicates any in the database and remove duplicates. Note: The app should ensure there are no duplicate messageUIds within the message array.

- (void)batchInsertMessage:(NSArray<RCMessage *> *)msgs checkDuplicate:(BOOL)checkDuplicate completion:(nullable void(^)(BOOL ret))completion;

IMLib

IMKit

Global Chat UIKit

push notification

IMLib

Global Chat UIKit

CallLib

CallKit

RTCLib

Chat Server

Chat Server SDK

Audio & Video Server

Inserting Messages

Inserting Outgoing Messages​

Interface Prototype​

Parameter Description​

Example Code​

Inserting Incoming Messages​

Interface Prototype​

Parameter Description​

Example Code​

Inserting Message Objects​

Batch Inserting Messages​

Batch Inserting Messages​

Interface Prototype​

Parameter Description​

Inserting Outgoing Messages

Interface Prototype

Parameter Description

Example Code

Inserting Incoming Messages

Interface Prototype

Parameter Description

Example Code

Inserting Message Objects

Batch Inserting Messages

Batch Inserting Messages

Interface Prototype

Parameter Description