Overview

The chat extension provides chat-related features (v7.6.0), such as message reply, quick comment, *Pin a chat, Bookmarks, and PIN tag of messages. All functionality is wrapped in the NIMChatExtendManager protocol, and callbacks are thrown using NIMChatExtendManagerDelegate.

Replies

Message replies are used to reply to the target message to form a logical structure of parent and child messages. A message can have 0 or one parent message and a parent message can have 0 or n child messages. The parent message of a message can be obtained with threadMessageId. The message reply is obtained with repliedMessageId.

If the reply is not enabled, the system will automatically convert the sent message into a normal message when replying. If you need the thread reply capability, contact the business manager to enable it.

Reply to a message

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Reply a message
 *
 *@param message new message
 * @param target message to be replied.
 *  @param error error. If an error occurs in preparing to send the message, this error will be specified with corresponding information
 *
 * @return result The result returned indicates whether the current function call is successful, and subsequent callbacks are required to determine whether the message has been sent to the server.
 */
- (BOOL)reply:(NIMMessage *)message
           to:(NIMMessage *)target
        error:(NSError * __nullable *)error;
@end

Properties

Parameter	Type	Description
message	NIMMessage	The new message.
target	NIMMessage	The message to be replied.
error	NSError	The call result

Example

objc NIMMessage *repliedMessage = [self.sessionConfig threadMessage];
 [[[NIMSDK sharedSDK] chatExtendManager] reply:newWessage
                                            to:repliedMessage
                                         error:nil];

Get a list of child messages

The interface used to get the list of child messages will not return deleted messages (except those deleted by DB) and unsent messages. The number of child messages include the deleted messages and unsent messages.

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Get the messages of a thread message
 *
 *  @param message parent message
 * @return list of child messages for the target message
 */
- (NSArray<NIMMessage *> * _Nullable)subMessages:(NIMMessage *)message;

/**
 * Get the messages of a thread message
 *
 *  @param message parent message
 * @return the number of child messages for the target message
 */
- (NSInteger)subMessagesCount:(NIMMessage *)message;
@end

Properties

Parameter	Type	Description
message	NIMMessage	The message to be queried .

Example

objcNSArray *subMessages = [[NIMSDK sharedSDK].chatExtendManager subMessages:message];
model.childMessages = subMessages;
model.childMessagesCount = [[NIMSDK sharedSDK].chatExtendManager subMessagesCount:message];

Get child messages from the server

Get the list of child messages of a message from the server

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Get child messages of a thread message
 *
 *  @param message target message
 *  @param option  pagination option
 *  @param block   completion callback
 */
- (void)fetchSubMessagesFrom:(NIMMessage *)message
                      option:(NIMThreadTalkFetchOption * _Nullable)option
                  completion:(NIMThreadTalkFetchMessages)block;
@end

Properties

Parameter	Type	Description
message	NIMMessage	The message to be queried .
option	NIMThreadTalkFetchOption	Options for a query.
block	NIMThreadTalkFetchMessages	Callback for the result.

Example

objcNIMThreadTalkFetchOption *option = [[NIMThreadTalkFetchOption alloc] init];
option.limit = 100; // The default value is 0
option.excludeMessage = firstMessage; // This message is not included in the returned result
option.end = firstMessage.timestamp;
option.sync = YES; // Synchronize the data to the SDK database. Ignore if the data already exists.
option.reverse = NO;
        
[[NIMSDK sharedSDK].chatExtendManager fetchSubMessagesFrom:self.threadMessage option:option completion:^(NSError * error, NIMThreadTalkFetchResult * result)
{
 //TODO...
}

Fetch messages from the server for completeness

To prevent messages from being not synchronized to the local database when the message roaming expires, the SDK fetches messages from the server by message ID and can optionally synchronize the data to the local database.

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 *  Get messages by MessageId
 *
 *  @param infos    request info
 *   @param sync  specify whether messages are synced to the local storage. Note that the message in deleted state in the database cannot be overwritten by synchronization.
 *@param block Completion callback
 */
- (void)fetchHistoryMessages:(NSArray<NIMChatExtendBasicInfo *> *)infos
                    syncToDB:(BOOL)sync
                  completion:(NIMFetchHistoryMessagesByIds)block;
@end

Properties

Parameter	Type	Description
infos	NSArray<NIMChatExtendBasicInfo *>	Basic information about the message to be queried
sync	BOOL	Whether the message is synced to the SDK database.
block	NIMFetchHistoryMessagesByIds	Callback for the result.

Example

objc [[NIMSDK sharedSDK].chatExtendManager fetchHistoryMessages:@[info]
                                                   syncToDB:YES
                                                 completion:^(NSError * error, NSMapTable<NIMChatExtendBasicInfo *,NIMMessage *> * result)
    {
        // TODO
    }];

<span id=“Quick comment”>Quick comment

Add a quick comment

Add a quick comment to a message. A user can add a quick comment of the same to a message onece. Otherwise, the previous comment will be overwritten by a later comment.

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Send a quick reply
 *
 *  @param comment   comment content
 *  @param message      message to be replied
 *  @param completion   completion callback
 */
- (void)addQuickComment:(NIMQuickComment *)comment
              toMessage:(NIMMessage *)message
             completion:(NIMQuickCommentHandler _Nullable)completion;
@end

Properties

Parameter	Type	Description
comment	NIMQuickComment	Comment
message	NIMMessage	The target message.
completion	NIMQuickCommentHandler	Callback for the result.

Example

objc [[NIMSDK sharedSDK].chatExtendManager addQuickComment:comment
                                                toMessage:message
                                               completion:^(NSError * _Nullable error)
    {
        //TODO ...
        
    }];

Delete a quick comment

Add a quick comment to a message. A user can add a quick comment of the same to a message onece. Otherwise, the previous comment will be overwritten by a later comment.

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 *  Delete a comment from the server
 *
 *  @param comment      taget comment
 *  @param completion   completion callback
 */
- (void)deleteQuickComment:(NIMQuickComment *)comment
                completion:(NIMQuickCommentHandler _Nullable)completion;
@end

Properties

Parameter	Type	Description
comment	NIMQuickComment	Comment
completion	NIMQuickCommentHandler	Callback for the result.

Example

objc[[NIMSDK sharedSDK].chatExtendManager deleteQuickComment:comment
                                                  completion:^(NSError * _Nullable error)
    {
       //TODO...
    }];

Query comments

Use the fetchQuickComments: completion: interface to get comments. This interface ensures that the comments are complete. This interface fetches comments from the server and synchronize the data for the first time when the integrity of the local data cannot be judged. The SDK request the data from the server for one time for a single login and a single session and will get the data from the local storage later if the data is complete.

Note: This interface will filter out some invalid incoming messages, such as messages that are blocked by the server, messages constructed locally, etc.

Prototype

objc@protocol NIMChatExtendManager <NSObject>
/**
 *  Get multiple comments at a time
 *
 *  @param messages target messages. Up to 20 messages can be obtained
 *  @param completion Completion callback
 */
- (void)fetchQuickComments:(NSArray<NIMMessage *> *)messages
                completion:(NIMFetchCommentsByMsgsHandler)completion;
@end

Parameter	Type	Description
messages	NSArray<NIMMessage >	Messages to be queried
completion	NIMFetchCommentsByMsgsHandler	Callback for the result.

Pin a session

Make sure the Pinned session synchronization is turned on before use. If you do not use the feature, turn it off (default).

objc[[NIMSDKConfig sharedConfig] setShouldSyncStickTopSessionInfos:YES];

NIMStickTopSessionInfo representation

Parameter	Type	Description
session	NIMSession	The session to be pinned.
ext	NSString	The extension field that can hold 512 characters.
createTime	NSTimeInterval	The time when a session is created in seconds.
updateTime	NSTimeInterval	The time when a session is updated in seconds.

Pin a session

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Pin a session
 * @param params parameters for pinning a session
 * @param completion completion callback
 */
- (void)addStickTopSession:(NIMAddStickTopSessionParams *)params 
                completion:(nullable NIMAddStickTopSessionCompletion)completion;
@end

NIMAddStickTopSessionParams representation

Parameter	Type	Description
session	NIMSession	The session to be pinned.
ext	NSString	The extension field that can hold 512 characters.

Example:

objcNIMAddStickTopSessionParams *params = [[NIMAddStickTopSessionParams alloc] initWithSession:session];
[NIMSDK.sharedSDK.chatExtendManager addStickTopSession:params completion:^(NSError *   _Nullable error, NIMStickTopSessionInfo * _Nullable newInfo) {
    if (error) {
      // handle error
      return;
    }
    // Do something with {newInfo}
}];

Unpin a session

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Unpin a session
 * @param info session info to be unpinned
 *  @param completion Completion callback
 */
- (void)removeStickTopSession:(NIMStickTopSessionInfo *)info 
                   completion:(nullable NIMRemoveStickTopSessionCompletion)completion;
@end

The info representation

Parameter	Type	Description
session	NIMSession	Pinned session
ext	NSTimeInterval	The creation time in seconds.

Example:

objc[NIMSDK.sharedSDK.chatExtendManager removeStickTopSession:info completion:^(NSError * _Nullable error, NIMStickTopSessionInfo * _Nullable removedInfo) {
    if (error) {
      // handle error
      return;
    }
   // Do something with {removedInfo}
}];

Update the extension field of a pinned session

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Update a pinned session
 * @param info session info to be updated
 *  @param completion Completion callback
 */
- (void)udpateStickTopSession:(NIMStickTopSessionInfo *)info 
                   completion:(nullable NIMUpdateStickTopSessionCompletion)completion;
@end

The info representation

Parameter	Type	Description
session	NIMSession	The pinned session
createTime	NSTimeInterval	The time when a session is created in seconds.
ext	NSString	The extension field that can hold 512 characters.

Example:

objc[NIMSDK.sharedSDK.chatExtendManager updateStickTopSession:info completion:^(NSError * _Nullable error, NIMStickTopSessionInfo * _Nullable updatedInfo) {
  if (error) {
   // handle error
     return;
  }
   // Do something with {removedInfo}
}];

Query all pinned sessions

Query all pinned sessions of the current user.

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Query all pinned sessions
 * @param completion completion callback
 */
- (void)loadStickTopSessionInfos:(nullable NIMLoadStickTopSessionInfosCompletion)completion;
@end

Example:

objc[NIMSDK.sharedSDK.chatExtendManager loadStickTopSessionInfos:^(NSError * _Nullable error, NSDictionary<NIMSession *,NIMStickTopSessionInfo *> * _Nullable infos) {
  if (error) {
   // handle error
     return;
  }
   // Do something with {infos}
}];

Query recent pinned sessions

Get the sorted recent sessions

objc@protocol NIMChatExtendManager <NSObject>
/**
 *  Get recent sessions
 * @param options query options (such as sorting by top session)
 */
- (void)loadRecentSessionsWithOptions:(NIMLoadRecentSessionsOptions *)options 
                        　 completion:(nullable NIMLoadRecentSessionsCompletion)completion;
@end

NIMLoadRecentSessionsOptions representation

Parameter	Type	Description
sortByStickTopInfos	BOOL	Whether pinned session are sorted

Example:

objcNIMLoadRecentSessionsOptions *options = [[NIMLoadRecentSessionsOptions alloc] init];
options.sortByStickTopInfos = YES;
[NIMSDK.sharedSDK.chatExtendManager loadRecentSessionsWithOptions:options completion:^(NSError * _Nullable error, NSArray<NIMRecentSession *> * _Nullable recentSessions) {
  if (error) {
   // handle error
     return;
  }
   // Do something with {recentSessions}
}];

Sort pinned sessions

Sort recent sessions by pinned tag

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Sort recent sessions by pinned chat info
 * @param recentSessions The top sessions to be sorted. if a mutable array is passed, they will be sorted in place
 * @param infos [session: pinned info] mapping
 * @return sorted list of recent sessions. If a mutable array is passed, the array will be returned
 */
- (NSArray<NIMRecentSession *> *)sortRecentSessions:(NSArray<NIMRecentSession *> *)recentSessions         
                                  withStickTopInfos:(NSDictionary<NIMSession *,NIMStickTopSessionInfo *> *)infos;
@end                                 

Example:

objcNSMutableArray<NIMRecentSession *> *mutableSessions = ...;
NSDictionary<NIMSession *,NIMStickTopSessionInfo *> *infos = ...;
[NIMSDK.sharedSDK.chatExtendManager sortRecentSessions: mutableSessions]; // Sort recent sessions in place
// Do something with {mutableSessions}

Check the pinned tag of a specified session

Check the pinned tag of a specified session.

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Query pinned info in a session
 * @param session The session to be queried
 * @return Pinned session
 */
- (NIMStickTopSessionInfo *)stickTopInfoForSession:(NIMSession *)session;
@end

Example:

objcNIMStickTopSessionInfo *info = [NIMSDK.sharedSDK.chatExtendManager stickTopInfoForSession:session];
if (info) {
   // Do something with {info}
}

Bookmarks

Query the bookmarks of the current user

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Query paginated bookmarks
 *  @param option  pagination option
 * @param completion completion callback
 */
- (void)queryCollect:(NIMCollectQueryOptions *)options 
          completion:(nullable NIMCollectQueryBlock)completion;
@end

NIMCollectQueryOptions representation

Parameter	Type	Description
fromTime	NSTimeInterval	The start time of a time range for a query in seconds.
toTime	NSTimeInterval	The end time of a time range for a query in seconds. A value of 0 indicates the current time.
excludeId	NSInteger	The ID of a bookmark on the last page. Pass 0 for the first bookmark.
limit	NSInteger	The maximum number of returned bookmarks iun a query. The default value is 100.
reverse	BOOL	Whether bookmarks are sorted in descending order.
type	NSInteger	The type of a bookmark

NIMCollectInfo representation

Parameter	Type	Description
Id	NSUInteger	Bookmark ID.
type	NSInteger	The type of a bookmark
data	NSString	data, a maximum of 20KB is allowed.
ext	NSString	The extension field that can hold 1KB.
uniqueId	NSString	Unique ID
createTime	NSTimeInterval	The time when a bookmark is added in seconds.
updateTime	NSTimeInterval	The time when a bookmark is updated in seconds.

Example:

objcNIMCollectQueryOptions *options = [[NIMCollectQueryOptions alloc] init];
options.toTime = ...;
options.excludeId = ...;
options.type = ...;
[NIMSDK.sharedSDK.chatExtendManager queryCollect:self.queryOptions completion:^(NSError * _Nullable error, NSArray<NIMCollectInfo *> * _Nullable collectInfos, NSInteger totalCount) {
  if (error) {
    // Handle error
    return;
  }
  // Do something with {collectInfos} and {totalCount}
}];

totalCount returns the number of all bookmarks of a specified type for the current user, used to determine whether it is the last page.

Add a bookmark

Add a bookmark.

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Add a bookmark
 * @param info Bookmark parameters. Required fields: type, data, and ext
 * @param completion completion callback
 */
- (void)addCollect:(NIMAddCollectParams *)info 
        completion:(nullable NIMAddCollectBlock)completion;
@end

NIMAddCollectParams

Parameter	Type	Description
type	NSInteger	The type of a bookmark
data	NSString	data, a maximum of 20KB is allowed.
ext	NSString	The extension field that can hold 1KB.
uniqueId	NSString	Unique ID

Example:

objcNIMAddCollectParams *params = [[NIMAddCollectParams alloc] init];
params.data = ...;
params.type = ...;
params.uniqueId = ...; 
[[NIMSDK sharedSDK].chatExtendManager addCollect:params completion:^(NSError * _Nullable error, NIMCollectInfo * _Nullable collectInfo) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {collectInfo}
}];

Remove a bookmark

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Remove multiple bookmarks
 * @param collectList Remove multiple bookmarks at a time. Required fields: id and createTime
 * @param completion completion callback
 */
- (void)removeCollect:(NSArray<NIMCollectInfo *> *)collectList 
           completion:(nullable NIMRemoveCollectBlock)completion;
@end

NIMCollectInfo representation

Parameter	Type	Description
Id	NSUInteger	Bookmark ID
createTime	NSTimeInterval	The time when a bookmark is added in seconds.

Example:

objcNSArray<NIMCollectInfo> *collectList = ...;
[NIMSDK.sharedSDK.chatExtendManager removeCollect:collectList completion:^(NSError * _Nullable error, NSInteger total_removed) {
    if (error) {
        // Handle error
        return;
    }
    // Successfully removed {total_removed} infos
}];

Update the extension field of a bookmark

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Update bookmarks
 * @param collectInfo Bookmarks updated. The id, createTime, and ext fields are required. If ext is not specified, the ext field is deleted.
 */
- (void)updateCollect:(NIMCollectInfo *)collectInfo 
           completion:(nullable NIMUpdateCollectBlock)completion;
@end

NIMCollectInfo

Parameter	Type	Description
Id	NSUInteger	Bookmark ID
createTime	NSTimeInterval	The time when a bookmark is added in seconds.
ext	NSString	The extension field that can hold 1KB.

Example:

objcNIMCollectInfo *info = ...; 
info.ext = "New ext"; //
[[NIMSDK sharedSDK].chatExtendManager updateCollect:params completion:^(NSError * _Nullable error, NIMCollectInfo * _Nullable collectInfo) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {collectInfo}
}];

PIN tag

NIMMessagePinItem PIN object

Parameter	Type	Description
session	NIMSession	The session to which a PIN message belongs
messageFromAccount	NSString	The ID of a message sender.
messageToAccount	NSString	The ID of a recipient.
messageTime	NSTimeInterval	The timestamp of a message in seconds
messageServerID	NSString	Server ID of a message
messageId	NSString	Local message ID
accountID	NSString	Operator. If no value is specified, the current user is the operator.
ext	NSString	The extension field that can hold 512KB.
createTime	NSTimeInterval	The time when a PIN tag is added in seconds.
updateTime	NSTimeInterval	The time when a PIN tag is updated in seconds.

Create a NIMMessagePinItem object based on the message to be operated

objcNIMMessage *message = ...;
NIMMessagePinItem *pinItem = [[NIMMessagePinItem alloc] initWithMessage:message];

Add a PIN tag to a message

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Add a PIN record
 * @param item The PIN target
 * @param completion completion callback
 */
- (void)addMessagePin:(NIMMessagePinItem *)item 
           completion:(nullable NIMAddMessagePinCompletion)completion;
@end

Example:

objcNIMMessage *message = ...;
NIMMessagePinItem *pinItem = [[NIMMessagePinItem alloc] initWithMessage:message];
[NIMSDK.sharedSDK.chatExtendManager addMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

Delete a PIN tag from a message

Delete a PIN tag from a message.

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Remove a PIN record
 * @param item PIN record to be removed
 *  @param completion Completion callback
 */
- (void)removeMessagePin:(NIMMessagePinItem *)item 
              completion:(nullable NIMRemoveMessagePinCompletion)completion;
@end

Example:

objcNIMMessagePinItem *pinItem = ...;
[NIMSDK.sharedSDK.chatExtendManager removeMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

Update the extension field of a PIN tag

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Update a PIN record extension
 * @param item PIN record to be updated. If the ext field is not passed, delete the record.
 * @param completion completion callback
 */
- (void)updateMessagePin:(NIMMessagePinItem *)item 
              completion:(nullable NIMUpdateMessagePinCompletion)completion;
@end

Example:

objcNIMMessagePinItem *pinItem = ...;
pinItem.ext = @"New ext";
[NIMSDK.aredSDK.chatExtendManager updateMessagePin:pinItem completion:^(NSError * _Nullable error, NIMMessagePinItem * _Nullable item) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {item}
}];

Query all PIN messages

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Query all PIN records. Tthe first query of the session after login will trigger a network synchronization.
 * @param session The session to be queried
 * @param completion completion callback
 */
- (void)loadMessagePinsForSession:(NIMSession *)session 
                       completion:(nullable NIMLoadMessagePinsCompletion)completion;
@end

Calling the method during login for the first time triggers data synchronization. No data is synchronized for the rest calls.

Parameters

Parameter	Type	Description
session	NIMSession	The session to be queried.

Example:

objc[NIMSDK.sharedSDK.chatExtendManager loadMessagePinsForSession:_currentSession completion:^(NSError * _Nonnull error, NSArray<NIMMessagePinItem *> * _Nullable items) {
    if (error) {
        // Handle error
        return;
    }
    // Do something with {items}
}];

Query the PIN tag of a message

Query the PIN tag of a message.

objc@protocol NIMChatExtendManager <NSObject>
/**
 * Query the PIN record of a message
 * @param message The message to be queried.
 * @return record
 */
- (NIMMessagePinItem *)pinItemForMessage:(NIMMessage *)message;
@end

Parameters

Parameter	Type	Description
message	NIMMessage	The message to be queried.

Listener for extension events

objc//Add an event delegate
[NIMSDK.sharedSDK.chatExtendManager addDelegate:self];

// Remove an event delegate
[NIMSDK.sharedSDK.chatExtendManager removeDelegate:self];

NIMChatExtendManagerDelegate protocol

objc/**
 *   Chat extension callback
 */
@protocol NIMChatExtendManagerDelegate <NSObject>

#pragma mark - Quick reply
@optional

/**
 *  Add a quick comment
 *
 *  @param comment comment
 */
- (void)onRecvQuickComment:(NIMQuickComment *)comment;

/**
 *  Remove a quick comment
 *
 *  @param comment comment to be deleted
 */
- (void)onRemoveQuickComment:(NIMQuickComment *)comment;

/**
 * Notification for adding a new PIN message
 *  @param item New PIN record
 */
- (void)onNotifyAddMessagePin:(NIMMessagePinItem *)item;

/**
 * Notification for removing a PIN message
 * @param item Removed PIN records
 */
- (void)onNotifyRemoveMessagePin:(NIMMessagePinItem *)item;

/**
 * Notification for updating a PIN message
 * @param item Updated PIN record
 */
- (void)onNotifyUpdateMessagePin:(NIMMessagePinItem *)item;

/**
 * Notification for completing synchronization of pinned sessions
 *  @param response response object after pinned session synced
 */
- (void)onNotifySyncStickTopSessions:(NIMSyncStickTopSessionResponse *)response;

/**
 * Notification for adding a new pinned session
 * @param newInfo New pinned session
 */
- (void)onNotifyAddStickTopSession:(NIMStickTopSessionInfo *)newInfo;

/**
 * Notification for removing a pinned session
 * @param removedInfo removed pinned session
 */
- (void)onNotifyRemoveStickTopSession:(NIMStickTopSessionInfo *)removedInfo;

/**
 * Notification for updating a new pinned session
 * @param updatedInfo Updated pinned session
 */
- (void)onNotifyUpdateStickTopSession:(NIMStickTopSessionInfo *)updatedInfo;
@end