Chat Extension
Update time: 2023/02/09 07: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
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