消息扩展
更新时间： 2024/11/18 15:30:30
NetEase IM SDK（以下简称 NIM SDK）支持多种消息扩展功能，助您快速实现多样化的消息业务场景。
本文介绍通过 NIM SDK 实现消息扩展功能，包括消息回复、Pin 消息、消息快捷评论、消息收藏功能。
支持平台
本文内容适用的开发平台或框架如下表所示：
| Android | iOS | macOS/Windows | Web/uni-app/小程序 | Node.js/Electron | HarmonyOS | Flutter |
|---|---|---|---|---|---|---|
| ✔️️️ | ✔️️️ | ✔️️️ | ✔️️️ | ✔️️️ | ✔️️️ | ✔️ |
开通消息扩展相关功能
-
在控制台首页 应用管理 中选择应用，然后单击 IM 即时通讯 下的 功能配置 按钮进入功能配置页。
-
在顶部选择 全局功能 页签，开启对应的消息扩展功能。需要开通以下功能：
- 会话消息标记（Pin 消息）
- 会话消息回复
- 消息快捷评论
实现消息回复
消息回复指，引用收到的某条消息并进行针对性的回复，形成以该消息为根消息的 Thread 树状结构。通过该功能，用户可针对某一条消息进行提问、反馈或补充相关背景信息，且不会对会话造成干扰。
Thread 消息树状结构示例见下图：
上图中：
- 消息 A 是消息 B 的 父消息，消息 B1 是消息 C 的 父消息
- 消息 C 是消息 B1 的 子消息
- 消息 A 是消息 B 和消息 C 的 根消息
- 消息 A、B、C 统称为 Threaded Message（串联起来的消息）
一条 Threaded Message 必须有一条父消息或至少一条子消息。如果一条消息既没有父消息，也没有子消息，则为普通消息。
回复一条消息
调用 replyMessage 方法发送一条回复消息。
示例代码如下：
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// 以文本消息为例，构建文本消息
V2NIMMessage v2Message = V2NIMMessageCreator.createTextMessage("xxx");
// V2NIMMessage replyMessage = ; // 被回复的消息
// 根据实际情况配置
V2NIMMessageAntispamConfig antispamConfig = V2NIMMessageAntispamConfig.V2NIMMessageAntispamConfigBuilder.builder()
.withAntispamBusinessId()
.withAntispamCheating()
.withAntispamCustomMessage()
.withAntispamEnabled()
.withAntispamExtension()
.build();
// 根据实际情况配置
V2NIMMessageConfig messageConfig = V2NIMMessageConfig.V2NIMMessageConfigBuilder.builder()
.withLastMessageUpdateEnabled()
.withHistoryEnabled()
.withOfflineEnabled()
.withOnlineSyncEnabled()
.withReadReceiptEnabled()
.withRoamingEnabled()
.withUnreadEnabled()
.build();
// 根据实际情况配置
V2NIMMessagePushConfig pushConfig = V2NIMMessagePushConfig.V2NIMMessagePushConfigBuilder.builder()
.withContent()
.withForcePush()
.withForcePushAccountIds()
.withForcePushContent()
.withPayload()
.withPushEnabled()
.withPushNickEnabled()
.build();
// 根据实际情况配置
V2NIMMessageRobotConfig robotConfig = V2NIMMessageRobotConfig.V2NIMMessageRobotConfigBuilder.builder()
.withAccountId()
.withCustomContent()
.withFunction()
.withTopic()
.build();
// 根据实际情况配置
V2NIMMessageRouteConfig routeConfig = V2NIMMessageRouteConfig.V2NIMMessageRouteConfigBuilder.builder()
.withRouteEnabled()
.withRouteEnvironment()
.build();
// 根据实际情况配置
V2NIMSendMessageParams sendMessageParams = V2NIMSendMessageParams.V2NIMSendMessageParamsBuilder.builder()
.withAntispamConfig(antispamConfig)
.withClientAntispamEnabled()
.withClientAntispamReplace()
.withMessageConfig(messageConfig)
.withPushConfig(pushConfig)
.withRobotConfig(robotConfig)
.withRouteConfig(routeConfig)
.build();
// 发送回复消息
v2MessageService.replyMessage(v2Message, replyMessage, sendMessageParams,
new V2NIMSuccessCallback<V2NIMSendMessageResult>() {
@Override
public void onSuccess(V2NIMSendMessageResult v2NIMSendMessageResult) {
// TODO: 发送成功
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// TODO: 发送失败
}
},
new V2NIMProgressCallback() {
@Override
public void onProgress(int progress) {
// TODO: 发送进度
}
});
iOS
Objective-C// 以文本消息为例，构建文本消息
V2NIMMessage *replyMessage = [V2NIMMessageCreator createTextMessage:@"reply message"];
// 消息见参数设置文档
V2NIMSendMessageParams *params = [[V2NIMSendMessageParams alloc] init];
[[[NIMSDK sharedSDK] v2MessageService] sendMessage:replyMessage
conversationId:@"conversationId"
params:params
success:^(V2NIMSendMessageResult * _Nonull result) {
// 发送成功回调
}
failure:^(V2NIMError * _Nonnull error) {
// 发送失败回调， error 包含错误原因
}
progress:^(NSUInteger progress) {
// 发送进行
}];
V2NIMMessage *message = [V2NIMMessageCreator createTextMessage:@"message"];
// 发送回复消息
[[[NIMSDK sharedSDK] v2MessageService] replyMessage:message
replyMessage:replyMessage
params:params
success:^(V2NIMSendMessageResult * _Nonnull result) {
// 发送成功回调
}
failure:^(V2NIMError * _Nonnull error) {
// 发送失败回调， error 包含错误原因
}
progress:^(NSUInteger progress) {
// 发送进行
}];
macOS/Windows
C++// 以文本消息为例，构建文本消息
auto message = V2NIMMessageCreator::createTextMessage("hello world");
auto params = V2NIMSendMessageParams();
// 发送回复消息
messageService.replyMessage(
message,
replyMessage,
params,
[](V2NIMSendMessageResult result) {
// reply message succeeded
},
[](V2NIMError error) {
// reply message failed, handle error
},
[](uint32_t progress) {
// upload progress
});
Web/uni-app/小程序
TypeScripttry {
// 以文本消息为例，构建文本消息
const message: V2NIMMessage = nim.V2NIMMessageCreator.createTextMessage("reply text")
const result: V2NIMSendMessageResult = await nim.V2NIMMessageService.replyMessage(message, repliedMessage)
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const replyMessage = v2.messageCreator.createTextMessage('Hello NTES IM')
const result = await v2.messageService.replyMessage(message, replyMessage, params, progressCallback)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const message: V2NIMMessage = nim.messageCreator.createTextMessage("reply text")
const result: V2NIMSendMessageResult = await nim.messageService.replyMessage(message, repliedMessage)
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.replyMessage(message, replyMessage, params);
实现消息快捷评论
支持针对某条消息进行快捷评论，评论内容通常为表情、短文本，由应用层定义评论内容与 UI 展示之间的映射关系。
注册消息监听器
Android/iOS/macOS/Windows
调用 addMessageListener 方法注册消息监听器，监听消息快捷评论通知回调 onMessageQuickCommentNotification。
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
V2NIMMessageListener messageListener = new V2NIMMessageListener() {
@Override
public void onMessageQuickCommentNotification(V2NIMMessageQuickCommentNotification quickCommentNotification) {
// receive message quick comment notification
}
};
v2MessageService.addMessageListener(messageListener);
iOS
Objective-C[[[NIMSDK sharedSDK] v2MessageService] addMessageListener:listener];
macOS/Windows
C++V2NIMMessageListener listener;
listener.onMessageQuickCommentNotification = [](V2NIMMessageQuickCommentNotification quickCommentNotification) {
// receive message quick comment notification
};
messageService.addMessageListener(listener);
Web/uni-app/小程序/Node.js/Electron/HarmonyOS
调用 on("EventName") 方法注册消息监听器，监听消息接收回调事件 onMessageQuickCommentNotification。
Web/uni-app/小程序
TypeScriptnim.V2NIMMessageService.on("onMessageQuickCommentNotification", function (quickCommentNotification: V2NIMMessageQuickCommentNotification) {})
Node.js/Electron
TypeScriptv2.messageService.on("messageQuickCommentNotification", function (quickCommentNotification: V2NIMMessageQuickCommentNotification) {})
HarmonyOS
TypeScriptnim.messageService.on("onMessageQuickCommentNotification", function (quickCommentNotification: V2NIMMessageQuickCommentNotification) {})
Flutter
调用 add 方法注册消息监听器，监听消息接收回调事件 onMessageQuickCommentNotification。
Dartsubsriptions.add(NimCore
.instance.messageService.onMessageQuickCommentNotification
.listen((event) {
//do something
}));
添加快捷评论
调用 addQuickComment 方法针对指定消息添加一条快捷评论。添加成功后，消息发送方和消息接收方均会收到消息快捷评论操作通知回调 onMessageQuickCommentNotification 并通知 UI 界面更新。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
V2NIMMessageQuickCommentPushConfig quickCommentPushConfig = V2NIMMessageQuickCommentPushConfig.V2NIMMessageQuickCommentPushConfigBuilder.builder()
// 根据实际情况设置
.withNeedBadge()
.withPushContent()
.withPushEnabled()
.withPushPayload()
.withPushTitle()
.build();
// V2NIMMessage quickCommentMessage = ; // 添加快捷评论的消息
// int quickCommentIndex = ; // 快捷评论的序号
// 添加快捷评论
v2MessageService.addQuickComment(quickCommentMessage, quickCommentIndex, "xxx", quickCommentPushConfig,
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
}
});
iOS
Objective-CV2NIMMessageQuickCommentPushConfig *quickCommentPushConfig = [[V2NIMMessageQuickCommentPushConfig alloc] init];
// 添加快捷评论
[[[NIMSDK sharedSDK] v2MessageService] addQuickComment:message
index:1
serverExtension:@"serverExtension"
pushConfig:quickCommentPushConfig
success:^{
// success
} failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMMessage message;
V2NIMMessageQuickCommentPushConfig pushConfig;
// 添加快捷评论
messageService.addQuickComment(
message,
1,
"serverExtension",
pushConfig,
[]() {
// add quick comment succeeded
},
[](V2NIMError error) {
// add quick comment failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
// 添加快捷评论
await nim.V2NIMMessageService.addQuickComment(message, 1, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
await v2.messageService.addQuickComment(message, index, 'serverExtension', pushConfig)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
await nim.messageService.addQuickComment(message, 1, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.addQuickComment(message, index, serverExtension, pushConfig);
移除快捷评论
调用 removeQuickComment 方法移除一条快捷评论。移除成功后，消息发送方和消息接收方均会收到消息快捷评论操作通知回调 onMessageQuickCommentNotification。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// V2NIMMessageRefer quickCommentMessageRefer // 移除快捷评论的消息引用
// int quickCommentIndex // 快捷评论的序号
// 移除快捷评论
v2MessageService.removeQuickComment(quickCommentMessageRefer, quickCommentIndex, "xxx",
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-CV2NIMMessageRefer *refer = [[V2NIMMessageRefer alloc] init];
// 移除快捷评论
[[[NIMSDK sharedSDK] v2MessageService] removeQuickComment:refer index:1 serverExtension:@"serverExtension" success:^{
// success
} failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMMessageRefer messageRefer;
// 移除快捷评论
messageService.removeQuickComment(
messageRefer,
1,
"serverExtension",
[]() {
// remove quick comment succeeded
},
[](V2NIMError error) {
// remove quick comment failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
// 移除快捷评论
await nim.V2NIMMessageService.removeQuickComment(messageRefer, 1, 'serverExtension')
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
await v2.messageService.removeQuickComment(messageRefer, index, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
await nim.messageService.removeQuickComment(messageRefer, 1, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.removeQuickComment(messageRefer, index, serverExtension);
获取快捷评论列表
调用 getQuickCommentList 获取指定消息的所有快捷评论。获取结果不包含已删除消息的快捷评论，按照评论时间排序。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// List<V2NIMMessage> messages // 需要查询快捷评论的消息列表
v2MessageService.getQuickCommentList(messages,
new V2NIMSuccessCallback<Map<String, List<V2NIMMessageQuickComment>>>() {
@Override
public void onSuccess(Map<String, List<V2NIMMessageQuickComment>> stringListMap) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-C[[[NIMSDK sharedSDK] v2MessageService] getQuickCommentList:@[message1, message2]
success:^(NSDictionary<NSString *,NSArray<V2NIMMessageQuickComment *> *> * _Nonnull result) {
// 返回 Dictionary 被快捷评论的消息
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++nstd::vector<V2NIMMessage> messages
// ...
messageService.getQuickCommentList(
messages,
[](nstd::map<nstd::string, nstd::vector<V2NIMMessageQuickComment>> quiments) {
for (auto&& quickComment : quickComments) {
// do something
}
},
[](V2NIMError error) {
// get quick comment list failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const quickCommentList = await nim.V2NIMMessageService.getQuickCommentList(messages)
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.getQuickCommentList(messages)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const quickCommentList = await nim.messageService.getQuickCommentList(messages)
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.getQuickCommentList(messages);
实现收藏功能
支持收藏已发送成功的消息或其他自定义内容。
添加一条收藏
调用 addCollection 方法添加一条收藏。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// int collectionType = ;
// String collectionData = ;
V2NIMAddCollectionParams addCollectionParams = V2NIMAddCollectionParams.V2NIMAddCollectionParamsBuilder
// 必填
.builder(collectionType, collectionData)
// 根据实际情况配置
.withServerExtension()
.build();
v2MessageService.addCollection(addCollectionParams,
new V2NIMSuccessCallback<V2NIMCollection>() {
@Override
public void onSuccess(V2NIMCollection v2NIMCollection) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-CV2NIMAddCollectionParams *addCollectionParams = [[V2NIMAddCollectionParams alloc] init];
[[[NIMSDK sharedSDK] v2MessageService] addCollection:addCollectionParams
success:^(V2NIMCollection * _Nonnull result) {
// V2NIMCollection
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMAddCollectionParams params;
params.collectionClientId = "id1";
params.collectionType = 1;
params.collectionData = "data";
params.serverExtension = "serverExtension";
messageService.addCollection(
params,
[](V2NIMCollection collection) {
// add collection succeeded
},
[](V2NIMError error) {
// add collection failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const res: V2NIMCollection = await nim.V2NIMMessageService.addCollection({
collectionType: 1,
collectionData: 'data',
serverExtension: 'serverExtension'
})
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.addCollection(params)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const res: V2NIMCollection = await nim.messageService.addCollection({
collectionType: 1,
collectionData: 'data',
serverExtension: 'serverExtension'
})
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.addCollection(params);
批量移除收藏
调用 removeCollections 批量移除收藏列表。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// List<V2NIMCollection> collections = ; // 需要移除的相关收藏
v2MessageService.removeCollections(collections,
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
}
});
iOS
Objective-CV2NIMCollection *collection = [[V2NIMCollection alloc] init];
[[[NIMSDK sharedSDK] v2MessageService] removeCollections:@[collection]
success:^(int count) {
// count
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++nstd::vector<V2NIMCollection> collections;
// ...
messageService.removeCollections(
collections,
[]() {
// remove collection succeeded
},
[](V2NIMError error) {
// remove collection failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const res: number = await nim.V2NIMMessageService.removeCollections(collections)
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const count = await v2.messageService.removeCollections(collections)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const res: number = await nim.messageService.removeCollections(collections)
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.removeCollections(collections);
更新收藏的服务端扩展字段
调用 updateCollectionExtension 更新收藏的服务端扩展字段。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
//V2NIMCollection collection = ; // 需要更新的收藏信息
v2MessageService.updateCollectionExtension(collection, "xxx",
new V2NIMSuccessCallback<V2NIMCollection>() {
@Override
public void onSuccess(V2NIMCollection v2NIMCollection) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-C[[[NIMSDK sharedSDK] v2MessageService] updateCollectionExtension:collection
serverExtension:@"serverExtension"
success:^(V2NIMCollection * _Nonnull result) {
// result 更新后的 collection
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMCollection collection
// ...
messageService.updateCollectionExtension(
collection,
"serverExtension",
[](V2NIMCollection collection) {
// update collection succeeded
},
[](V2NIMError error) {
// update collection failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const collection: V2NIMCollection = await nim.V2NIMMessageService.updateCollectionExtension(collection, 'newExtension')
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.updateCollectionExtension(collection, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const collection: V2NIMCollection = await nim.messageService.updateCollectionExtension(collection, 'newExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.updateCollectionExtension(collection, serverExtension);
按照查询条件分页获取收藏列表
调用 getCollectionListByOption 方法按照查询条件分页获取收藏列表。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// 根据实际情况配置
V2NIMCollectionOption option = V2NIMCollectionOption.V2NIMCollectionOptionBuilder.builder()
.withAnchorCollection()
.withBeginTime()
.withCollectionType()
.withDirection()
.withEndTime()
.withLimit()
.build();
v2MessageService.getCollectionListByOption(option,
new V2NIMSuccessCallback<List<V2NIMCollection>>() {
@Override
public void onSuccess(List<V2NIMCollection> v2NIMCollections) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-CV2NIMCollectionOption *collectionOption = [[V2NIMCollectionOption alloc] init];
[[[NIMSDK sharedSDK] v2MessageService] getCollectionListByOption:collectionOption
success:^(NSArray<V2NIMCollection *> * _Nonnull result) {
// result V2NIMCollection list
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMCollectionOption option;
option.collectionType = 1;
option.limit = 10;
messageService.getCollectionListByOption(
option,
[](nstd::vector<V2NIMCollection> collections) {
for (auto&& collection : collections) {
// do something
}
},
[](V2NIMError error) {
// get collection list failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const res: V2NIMCollection[] = await nim.V2NIMMessageService.getCollectionListByOption({
beginTime: 0,
endTime: 0,
direction: 0,
limit: 100,
collectionType: 0
})
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.getCollectionListByOption(option)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const res: V2NIMCollection[] = await nim.messageService.getCollectionListByOption({
beginTime: 0,
endTime: 0,
direction: 0,
limit: 100,
collectionType: 0
})
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.getCollectionListByOption(option);
实现 PIN 消息
支持将会话中的重要消息执行 PIN 操作，被 PIN 的消息会以列表形式展示在 UI 界面。
一条消息可以被所在会话内的所有用户 执行 PIN 操作，PIN 消息对会话内的所有成员可见。如果多个用户对同一条消息执行 PIN 操作，较晚的 PIN 会覆盖之前的 PIN。
注册消息监听器
Android/iOS/macOS/Windows
调用 addMessageListener 方法注册消息监听器，监听消息快捷评论通知回调 onMessagePinNotification。
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
V2NIMMessageListener messageListener = new V2NIMMessageListener() {
@Override
public void onMessagePinNotification(V2NIMMessagePinNotification pinNotification) {
// receive message pin notification
}
};
v2MessageService.addMessageListener(messageListener);
iOS
Objective-C[[[NIMSDK sharedSDK] v2MessageService] addMessageListener:listener];
macOS/Windows
C++V2NIMMessageListener listener;
listener.onMessagePinNotification = [](V2NIMMessagePinNotification pinNotification) {
// receive message pin notification
};
messageService.addMessageListener(listener);
Web/uni-app/小程序/Node.js/Electron/HarmonyOS
调用 on("EventName") 方法注册消息监听器，监听消息接收回调事件 onMessagePinNotification。
Web/uni-app/小程序
TypeScriptnim.V2NIMMessageService.on("onMessagePinNotification", function (pinNotification: V2NIMMessagePinNotification) {})
Node.js/Electron
TypeScriptv2.messageService.on("messagePinNotification", function (pinNotification: V2NIMMessagePinNotification) {})
HarmonyOS
TypeScriptnim.messageService.on("onMessagePinNotification", function (pinNotification: V2NIMMessagePinNotification) {})
Flutter
调用 add 方法注册消息监听器，监听消息接收回调事件 onMessagePinNotification。
Dartsubsriptions.add(NimCore
.instance.messageService.onMessagePinNotification
.listen((event) {
//do something
}));
PIN 一条消息
调用 pinMessage 方法针对指定消息执行 PIN 操作。PIN 成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// V2NIMMessage pinMessage = ; // 被 PIN 的消息
// PIN 一条消息
v2MessageService.pinMessage(pinMessage, "xxx",
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-C// PIN 一条消息
[[[NIMSDK sharedSDK] v2MessageService] pinMessage:message
serverExtension:@"json string"
success:^{
// success
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMMessage message;
// PIN 一条消息
messageService.pinMessage(
message,
"serverExtension",
[]() {
// pin message succeeded
},
[](V2NIMError error) {
// pin message failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
// PIN 一条消息
await nim.V2NIMMessageService.pinMessage(message, 'serverExtension')
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
await v2.messageService.pinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
await nim.messageService.pinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.pinMessage(message, serverExtension);
更新 PIN 消息服务端扩展字段
调用 updatePinMessage 方法更新 PIN 消息服务端扩展字段。更新 PIN 消息成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。
如果更新 PIN 消息的操作人非当前登录账号，则 operatorId 变更为更新 PIN 消息的实际操作人。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// V2NIMMessage updateMessage = ; // 被更新的消息
// 更新 PIN 消息服务端字段
v2MessageService.updatePinMessage(updateMessage, "xxx",
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
}
});
iOS
Objective-C// 更新 PIN 消息服务端字段
[[[NIMSDK sharedSDK] v2MessageService] updatePinMessage:message
serverExtension:@"json string"
success:^{
// success
}
failure:^(V2NIMError * _Nonnull error) {
//error 包含错误原因
}];
macOS/Windows
C++V2NIMMessage message;
// 更新 PIN 消息服务端字段
messageService.updatePinMessage(
message,
// 服务端字段
"serverExtension",
[]() {
// update pin message succeeded
},
[](V2NIMError error) {
// update pin message failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
// 更新 PIN 消息服务端字段
await nim.V2NIMMessageService.updatePinMessage(message, 'serverExtension')
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
await v2.messageService.updatePinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
await nim.messageService.updatePinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.updatePinMessage(message, serverExtension);
取消 PIN 消息
调用 unpinMessage 方法取消 PIN 一条消息。取消 PIN 消息成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// V2NIMMessageRefer unpinMessageRefer // 被取消 PIN 的消息参考信息
v2MessageService.unpinMessage(unpinMessageRefer, "xxx",
new V2NIMSuccessCallback<Void>() {
@Override
public void onSuccess(Void unused) {
// success
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-C// 取消 PIN，传入 PIN 消息参考信息
[[[NIMSDK sharedSDK] v2MessageService] unpinMessage:messageRefer
serverExtension:@"json string"
success:^{
// success
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++V2NIMMessageRefer messageRefer;
messageService.unpinMessage(
// 被取消 PIN 的消息参考信息
messageRefer,
"serverExtension",
[]() {
// unpin message succeeded
},
[](V2NIMError error) {
// unpin message failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
await nim.V2NIMMessageService.unpinMessage(messageRefer, 'serverExtension')
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
await v2.messageService.unpinMessage(messageRefer, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
await nim.messageService.unpinMessage(messageRefer, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.unpinMessage(messageRefer, serverExtension);
获取 PIN 消息列表
调用 getPinnedMessageList 获取会话内所有 PIN 消息。获取结果不包含已删除、已撤回的消息，结果按照更新时间排序。
示例代码
Android
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
// 以单聊为例
V2NIMConversationType conversationType = V2NIMConversationType.V2NIM_CONVERSATION_TYPE_P2P;
// 构建会话 ID
String conversationId = V2NIMConversationIdUtil.conversationId("xxx", conversationType);
v2MessageService.getPinnedMessageList(conversationId,
new V2NIMSuccessCallback<List<V2NIMMessagePin>>() {
@Override
public void onSuccess(List<V2NIMMessagePin> v2NIMMessagePins) {
// success, return V2NIMMessagePin list
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
iOS
Objective-C[[[NIMSDK sharedSDK] v2MessageService] getPinnedMessageList:@"conversationId"
success:^(NSArray<V2NIMMessagePin *> * _Nonnull result) {
// success，返回 V2NIMMessagePin 数组
}
failure:^(V2NIMError * _Nonnull error) {
// error 包含错误原因
}];
macOS/Windows
C++// 构建会话 ID
auto conversationId = V2NIMConversationIdUtil::p2pConversationId("target_account_id");
messageService.getPinnedMessageList(
conversationId,
[](std::vector<V2NIMMessagePin> pins) {
for (auto&& pin : pins) {
// do something
}
},
[](V2NIMError error) {
// get pin message list failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const messagePinArr = await nim.V2NIMMessageService.getPinnedMessageList('me|1|another')
// todo Success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.getPinnedMessageList(conversationId)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const messagePinArr = await nim.messageService.getPinnedMessageList('me|1|another')
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.getPinnedMessageList(conversationId);
消息参考信息
根据消息参考信息获取消息列表
当消息数据不明确时，可使用该接口获取消息。推荐回复消息、PIN 消息场景下使用。
调用 getMessageListByRefers 方法根据参考信息获取消息列表。
SDK 查询策略如下：
示例代码
JavaV2NIMMessageService v2MessageService = NIMClient.getService(V2NIMMessageService.class);
List<V2NIMMessageRefer> messageRefers = new ArrayList<>();
// 根据实际情况增加
// messageRefers.add(messageRefer);
v2MessageService.getMessageListByRefers(messageRefers,
new V2NIMSuccessCallback<List<V2NIMMessage>>() {
@Override
public void onSuccess(List<V2NIMMessage> v2NIMMessages) {
// success, return V2NIMMessage list
}
},
new V2NIMFailureCallback() {
@Override
public void onFailure(V2NIMError error) {
// failed, handle error
}
});
:::
iOS
Objective-CV2NIMMessageRefer *refer1 = [[V2NIMMessageRefer alloc] init];
V2NIMMessageRefer *refer2 = [[V2NIMMessageRefer alloc] init];
V2NIMMessageRefer *refern = [[V2NIMMessageRefer alloc] init];
NSArray *refers = @[refer1, refer2, refern];
[[[NIMSDK sharedSDK] v2MessageService] getMessageListByRefers:refers
success:^(NSArray<V2NIMMessage *> *result) {
// result 返回消息数组
}
failure:^(V2NIMError *error) {
// error 包含错误原因
}];
macOS/Windows
C++nstd::vector<V2NIMMessageRefer> messageRefers;
messageService.getMessageListByRefers(
messageRefers,
[](nstd::vector<V2NIMMessage> messages) {
for (auto&& message : messages) {
// do something
}
},
[](V2NIMError error) {
// get message list by refers failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const res: V2NIMMessage[] = await nim.V2NIMMessageService.getMessageListByRefers(
[{
senderId: 'me',
receiverId: 'another',
messageClientId: 'messageClientId',
messageServerId: 'messageServerId',
conversationType: 1,
conversationId: 'me|1|another',
createTime: 232312
}]
)
// todo success
} catch (err) {
// todo error
}
Node.js/Electron
TypeScripttry {
const messages = await v2.messageService.getMessageListByRefers(messageRefers)
// todo Success
} catch (err) {
// todo error
}
HarmonyOS
TypeScripttry {
const res: V2NIMMessage[] = await nim.messageService.getMessageListByRefers(
[{
senderId: 'me',
receiverId: 'another',
messageClientId: 'messageClientId',
messageServerId: 'messageServerId',
conversationType: 1,
conversationId: 'me|1|another',
createTime: 232312
}]
)
// todo Success
} catch (err) {
// todo error
}
Flutter
Dartawait NimCore.instance.messageService.getMessageListByRefers(messageRefers);
查询 Thread 消息
分页查询 Thread 历史消息列表
调用 getThreadMessageList 方法分页获取云端 Thread 历史消息列表。
该方法用于根据 Thread 根消息分页获取所有 Thread 子消息。
为避免触发请求频控，若云端会话数据同步已完成（收到 onSyncFinished 回调），建议您改用 getLocalThreadMessageList 方法获取本地 Thread 历史消息列表。
示例代码
Android
JavaV2NIMThreadMessageListOption option = new V2NIMThreadMessageListOption();
// messageRefer field is mandatory and is used to determine a root message. It can be filled directly with a message body or a V2NIMMessageRefer object can be constructed based on the message body's fields.
option.setMessageRefer(rootMessageRefer);
// The following fields are optional
// beginTime and endTime define the time range of the query. Fill with 0 to indicate no restriction.
option.setBeginTime(0L);
option.setEndTime(0L);
// For the first page, leave this field blank. When paging, fill in the serverId of the message closest to the target page's current page. For example, anchorMessage represents the earliest message on the current page, allowing the current request to page backward (earlier events). Query 20 messages earlier than anchorMessage (excluding itself).
option.setExcludeMessageServerId("123456");
// Maximum number of messages to be retrieved
option.setLimit(20);
// Query direction, default is V2NIM_QUERY_DIRECTION_DESC
option.setDirection(V2NIMQueryDirection.V2NIM_QUERY_DIRECTION_DESC);
NIMClient.getService(V2NIMMessageService.class).getThreadMessageList(option, v2NIMThreadMessageListResult -> {
//Query successful
}, error -> {
//Query failed
});
iOS
Objective-CV2NIMThreadMessageListOption *option = [[V2NIMThreadMessageListOption alloc] init];
// messageRefer 字段必填，此字段用于确定一条根消息。可以直接填消息体，也可以根据消息体的字段，构造一个 V2NIMMessageRefer 对象
option.messageRefer = rootMessage;
//下面的字段均为可选字段
// beginTime 和 endTime 划定了查询的时间范围，填 0 表示不做限制。
option.beginTime = 0;
option.endTime = 1715331571.927; //anchorMessage.createTime
// 第一页不填，翻页时填写距离目标页最近的当前页的消息的 serverId。
// 如 anchorMessage 表示当前页中最早的一条消息，则当前请求可以实现向前（事件更早）翻页。查询比 anchorMessage 早（不包括自己）的 20 条消息
option.excludeMessageServerId = @"123456"; //anchorMessage.messageServerId
// 查询出的消息条数上限
option.limit = 20;
// 查询方向。DESC 为按时间戳从大到小查询
option.direction = V2NIM_QUERY_DIRECTION_DESC;
// 调用接口查询消息
[[NIMSDK sharedSDK].v2MessageService getThreadMessageList:option success:^(V2NIMThreadMessageListResult *result) {
// 查询成功
} failure:^(V2NIMError *error) {
// 查询失败
}];
macOS/Windows
C++V2NIMTheadMessageListOption threadMessageListOption;
// ...
messageService.getThreadMessageList(
threadMessageListOption,
[](V2NIMThreadMessageListResult response) {
// do something
},
[](V2NIMError error) {
// get message list by refers failed, handle error
});
Web/uni-app/小程序
TypeScripttry {
const result = await nim.V2NIMMessageService.getThreadMessageList({
messageRefer: {
"senderId": "account1",
"receiverId": "account2",
"messageClientId": "21a7e3d43a7afdf52e11f61d9753f99c",
"messageServerId": "231689624",
"createTime": 1715222453441,
"conversationType": 1,
"conversationId": "account1|1|account2"
},
"limit": 50
})
} catch(err) {
console.error('getAddApplicationUnreadCount Error:', err)
}
Node.js/Electron
TypeScripttry {
const result = await v2.messageService.getThreadMessageList({
messageRefer: {
"senderId": "account1",
"receiverId": "account2",
"messageClientId": "21a7e3d43a7afdf52e11f61d9753f99c",
"messageServerId": "231689624",
"createTime": 1715222453441,
"conversationType": 1,
"conversationId": "account1|1|account2"
},
"limit": 50
})
} catch(err) {
console.error('getAddApplicationUnreadCount Error:', err)
}
HarmonyOS
TypeScripttry {
const result = await nim.messageService.getThreadMessageList({
messageRefer: {
"senderId": "account1",
"receiverId": "account2",
"messageClientId": "21a7e3d43a7afdf52e11f61d9753f99c",
"messageServerId": "231689624",
"createTime": 1715222453441,
"conversationType": 1,
"conversationId": "account1|1|account2"
},
"limit": 50
})
} catch(err) {
console.error('getAddApplicationUnreadCount Error:', err)
}
Flutter
Dartawait NimCore.instance.messageService.getThreadMessageList(threadMessageListOption);
查询本地 Thread 历史消息列表
调用 getLocalThreadMessageList 方法获取本地 Thread 历史消息列表。
该方法用于根据 Thread 根消息获取所有本地 Thread 子消息。
示例代码
Android
Java// messageRefer 字段用于确定一条根消息。可以直接填消息体，也可以根据消息体的字段，构造一个 V2NIMMessageRefer 对象
V2NIMMessageRefer messageRefer = rootMessage;
NIMClient.getService(V2NIMMessageService.class).getLocalThreadMessageList(messageRefer, v2NIMThreadMessageListResult -> {
//Query successful
}, error -> {
//Query failed
});
iOS
Objective-C// messageRefer 字段用于确定一条根消息。可以直接填消息体，也可以根据消息体的字段，构造一个 V2NIMMessageRefer 对象
V2NIMMessageRefer *messageRefer = rootMessage;
// 调用接口查询消息
[[NIMSDK sharedSDK].v2MessageService getLocalThreadMessageList:messageRefer success:^(V2NIMThreadMessageListResult *result) {
// 查询成功
} failure:^(V2NIMError *error) {
// 查询失败
}];
macOS/Windows
C++V2NIMMessageRefer messageRefer;
// ...
messageService.getLocalThreadMessageList(
messageRefer,
[](V2NIMThreadMessageListResult response) {
// do something
},
[](V2NIMError error) {
// get message list by refers failed, handle error
});
HarmonyOS
const messageRefer = {
"senderId": "account1",
"receiverId": "account2",
"messageClientId": "21a7e3d43a7afdf52e11f61d9753f99c",
"messageServerId": "231689624",
"createTime": 1715222453441,
"conversationType": 1,
"conversationId": "account1|1|account2"
} as V2NIMMessageRefer
const result = await nim.messageService.getLocalThreadMessageList(messageRefer)
Flutter
Dartawait NimCore.instance.messageService.getLocalThreadMessageList(messageRefer);
相关信息
涉及接口
Android/iOS/macOS/Windows
| API | 说明 |
|---|---|
addMessageListener |
注册消息监听器 |
removeMessageListener |
取消注册消息监听器 |
replyMessage |
回复消息 |
addQuickComment |
添加指定消息的快捷评论 |
removeQuickComment |
移除指定消息的快捷评论 |
getQuickCommentList |
查询指定消息的快捷评论 |
addCollection |
添加进收藏夹 |
removeCollections |
移除收藏列表 |
updateCollectionExtension |
更新收藏的服务端扩展字段 |
getCollectionListByOption |
获取收藏列表 |
pinMessage |
PIN 一条消息 |
updatePinMessage |
更新指定 PIN 消息的服务端扩展字段 |
unpinMessage |
取消一条 PIN 消息 |
getPinnedMessageList |
查询已 PIN 消息列表 |
getMessageListByRefers |
根据消息参考信息批量查询消息列表 |
getThreadMessageList |
查询云端 Thread 历史消息列表 |
getLocalThreadMessageList |
查询本地 Thread 历史消息列表 |
Web/uni-app/小程序/Node.js/Electron/HarmonyOS
| API | 说明 |
|---|---|
on("EventName") |
注册消息监听器 |
off("EventName") |
取消注册消息监听器 |
replyMessage |
回复消息 |
addQuickComment |
添加指定消息的快捷评论 |
removeQuickComment |
移除指定消息的快捷评论 |
getQuickCommentList |
查询指定消息的快捷评论 |
addCollection |
添加进收藏夹 |
removeCollections |
移除收藏列表 |
updateCollectionExtension |
更新收藏的服务端扩展字段 |
getCollectionListByOption |
获取收藏列表 |
pinMessage |
PIN 一条消息 |
updatePinMessage |
更新指定 PIN 消息的服务端扩展字段 |
unpinMessage |
取消一条 PIN 消息 |
getPinnedMessageList |
查询已 PIN 消息列表 |
getMessageListByRefers |
根据消息参考信息批量查询消息列表 |
getThreadMessageList |
查询云端 Thread 历史消息列表 |
getLocalThreadMessageList |
查询本地 Thread 历史消息列表 |
Flutter
| API | 说明 |
|---|---|
add |
注册消息监听器 |
cancel |
取消注册消息监听器 |
replyMessage |
回复消息 |
addQuickComment |
添加指定消息的快捷评论 |
removeQuickComment |
移除指定消息的快捷评论 |
getQuickCommentList |
查询指定消息的快捷评论 |
addCollection |
添加进收藏夹 |
removeCollections |
移除收藏列表 |
updateCollectionExtension |
更新收藏的服务端扩展字段 |
getCollectionListByOption |
获取收藏列表 |
pinMessage |
PIN 一条消息 |
updatePinMessage |
更新指定 PIN 消息的服务端扩展字段 |
unpinMessage |
取消一条 PIN 消息 |
getPinnedMessageList |
查询已 PIN 消息列表 |
getMessageListByRefers |
根据消息参考信息批量查询消息列表 |
getThreadMessageList |
查询云端 Thread 历史消息列表 |
getLocalThreadMessageList |
查询本地 Thread 历史消息列表 |
此文档是否对你有帮助？
