Insert Messages

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

tip

• Ensure that all inserted messages are supported for local storage on the client; otherwise, an error will occur. For details, see Understanding Message Storage Policies.
• The message insertion interface only inserts messages into the local database, so messages will not be synchronized from the remote database when the app is reinstalled or when logging in from a different device.

Insert Outgoing Messages

Developers can use the following interface to insert an outgoing message into the local database. This is not supported for chatroom conversation types. The example below uses the insertOutgoingMessage method under RCChannelClient.

tip

If the sentTime is incorrect, it may affect message sorting. Use with caution!

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:completion];

To enable message expansion for messages inserted into the local database, you must use the insertion method under RCChannelClient; otherwise, the message's expandable property (canIncludeExpansion) cannot be activated. Local message insertion does not support setting message expansion data. The app can choose an appropriate time to set the expansion data for the message. For details, see Message Expansion.

Parameter	Type	Description
conversationType	RCConversationType	Conversation type.
targetId	NSString	Conversation ID.
channelId	NSString	Business identifier for the conversation.
canIncludeExpansion	BOOL	Whether message expansion is supported. YES indicates expandable; NO indicates non-expandable.
sentStatus	RCSentStatus	Sent status.
content	RCMessageContent	Message content.
sentTime	long long	Unix timestamp for when the message was sent, in milliseconds (passing 0 will insert based on local time).
completion	Block	Asynchronous callback, returns the inserted message entity RCMessage.

Insert Incoming Messages

Developers can use the following interface to insert an incoming message into the local database.

tip

If the sentTime is incorrect, it may affect message sorting. Use with caution!

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

[[RCCoreClient sharedCoreClient]
  insertIncomingMessage:ConversationType_PRIVATE
  targetId:@"targetId"
  senderUserId:@"senderUserId"
  receivedStatus:ReceivedStatus_READ
  content:content
  sentTime:sentTime
  completion:completion];

Parameter	Type	Description
conversationType	RCConversationType	Conversation type; for one-to-one chat, pass ConversationType_PRIVATE.
targetId	NSString	Target ID used to identify the conversation, also known as the conversation ID. Note: In one-to-one chat, the Target ID is always the user ID of the other party. For group chats and ultra groups, the conversation ID is the group ID and ultra group ID, respectively. For details, see the explanation of Target ID in Message Introduction.
senderUserId	NSString	Sender ID.
sentStatus	RCReceivedStatus	Received status.
content	RCMessageContent	Message content.
sentTime	long long	Unix timestamp for when the message was sent, in milliseconds (passing 0 will insert based on local time).
completion	Block	Asynchronous callback, returns the inserted message entity RCMessage.

Insert Message Object

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

tip

If the sentTime is incorrect, it may affect message sorting. Use with caution!

The disableUpdateLastMessage property of RCMessaage controls whether the message updates as the latest message in the conversation. The default value of disableUpdateLastMessage is NO, meaning it will update. You can set it to YES to prevent it from updating as the latest message in the conversation.

1. Insert 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;// If expansion capability is needed later, set this before insertion
outgoing.disableUpdateLastMessage = YES;// Do not update as the latest message in the conversation

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

2. Insert 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 as the latest message in the conversation

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

Batch Insert Messages

tip

• Supported starting from version 5.1.1.
• Starting from version 5.3.0 of RCCoreClient, it is recommended to use the interface with asynchronous results below. The original synchronous interface is deprecated.

Insert messages in bulk into the local database. Since a failure in bulk insertion can cause the entire batch to fail, it is recommended to insert in smaller batches. This interface does not support chatroom or ultra group conversation types.

The following properties of RCMessage will be stored in the database; other properties will be discarded:

• conversationType: Conversation type.
• messageUId: Globally unique message ID, generated by the server after successful message transmission. SDK supports storing this property starting from version 5.3.5. This field is generally used for data migration.
• targetId: Conversation ID.
• messageDirection: Message direction.
• senderUserId: Sender ID.
• receivedStatus: Received status; if the message direction is incoming and receivedStatus is ReceivedStatus_UNREAD, the message is unread. Unread messages will be added to the conversation's unread message count.
• sentStatus: Sent status.
• content: Message content.
• sentTime: Unix timestamp for when the message was sent, in milliseconds, which affects message sorting.
• extra: Additional message information.

/*!
 Asynchronously insert incoming messages in bulk (these messages are only inserted into the local database and are not actually sent to the server or the other party)

 @discussion This method does not support chatroom conversation types. It also does not support ultra group conversation types. Each batch can process up to 500 messages; exceeding 500 will return NO.
 @discussion Unread messages will be added to the conversation's unread message count.

 @remarks Message operations
 */
- (void)batchInsertMessage:(NSArray<RCMessage *> *)msgs completion:(nullable void(^)(BOOL))completion;

Parameter	Type	Description
msgs	NSArray	List of RCMessage objects. A maximum of 500 messages can be inserted in a single operation; it is recommended to insert 10 messages at a time. Note that message must contain a correct and valid sentTime (Unix timestamp for when the message was sent, in milliseconds); otherwise, the message cannot be retrieved from the database using the history message retrieval interface.
completion	Block	Asynchronous callback, returns whether the insertion was successful.

The following method is provided for batch inserting messages. Setting checkDuplicate to YES will cause the SDK to check for duplicate UIDs in the database and remove duplicates during insertion. Note that the app should ensure that there are no duplicate UIDs within the message array being inserted.

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