Chat Extension

Update time: 2023/02/09 15:46:06

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

@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

 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

@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

NSArray *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

@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

NIMThreadTalkFetchOption *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

@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

 [[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

@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

 [[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

@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

[[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

@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).

[[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

@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:

NIMAddStickTopSessionParams *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

@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:

[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

@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:

[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.

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

Example:

[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

@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:

NIMLoadRecentSessionsOptions *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

@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:

NSMutableArray<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.

@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:

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

Bookmarks

Query the bookmarks of the current user

@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:

NIMCollectQueryOptions *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.

@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:

NIMAddCollectParams *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

@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:

NSArray<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

@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:

NIMCollectInfo *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

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

Add a PIN tag to a message

@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:

NIMMessage *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.

@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:

NIMMessagePinItem *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

@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:

NIMMessagePinItem *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

@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:

[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.

@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

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

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

NIMChatExtendManagerDelegate protocol

/**
 *   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
Was this page helpful?
Yes
No
  • Overview
  • Replies
  • Reply to a message
  • Get a list of child messages
  • Get child messages from the server
  • Fetch messages from the server for completeness
  • <span id=“Quick comment”>Quick comment
  • Add a quick comment
  • Delete a quick comment
  • Query comments
  • Pin a session
  • Pin a session
  • Unpin a session
  • Update the extension field of a pinned session
  • Query all pinned sessions
  • Query recent pinned sessions
  • Sort pinned sessions
  • Check the pinned tag of a specified session
  • Bookmarks
  • Add a bookmark
  • Remove a bookmark
  • Update the extension field of a bookmark
  • PIN tag
  • Add a PIN tag to a message
  • Delete a PIN tag from a message
  • Update the extension field of a PIN tag
  • Query all PIN messages
  • Query the PIN tag of a message
  • Listener for extension events