消息扩展 - IM 即时通讯

开发者中心

IM 即时通讯

集成开发

消息扩展

更新时间： 2024/08/16 10:56:49

NetEase IM SDK（以下简称 NIM SDK）支持多种消息扩展功能，助您快速实现多样化的消息业务场景。

本文介绍通过 NIM SDK 实现消息扩展功能，包括消息回复、Pin 消息、消息快捷评论、消息收藏功能。

开通消息扩展相关功能

在控制台首页应用管理中选择应用，然后单击 IM 即时通讯下的功能配置按钮进入功能配置页。
在顶部选择全局功能页签，开启对应的消息扩展功能。需要开通以下功能：
- 会话消息标记（Pin 消息）
- 会话消息回复
- 消息快捷评论

实现消息回复

消息回复指，引用收到的某条消息并进行针对性的回复，形成以该消息为根消息的 Thread 树状结构。通过该功能，用户可针对某一条消息进行提问、反馈或补充相关背景信息，且不会对会话造成干扰。

Thread 消息树状结构示例见下图：

Thread消息.png

上图中：

消息 A 是消息 B 的父消息，消息 B1 是消息 C 的父消息
消息 C 是消息 B1 的子消息
消息 A 是消息 B 和消息 C 的根消息
消息 A、B、C 统称为 Threaded Message（串联起来的消息）

一条 Threaded Message 必须有一条父消息或至少一条子消息。如果一条消息既没有父消息，也没有子消息，则为普通消息。

回复一条消息

调用 replyMessage 方法发送一条回复消息。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	发送的消息对象，通过调用 `V2NIMMessageCreator` 中的接口创建。如果为空或不存在则返回 191004 参数错误。
`replyMessage`	`V2NIMMessage`	是	-	被回复的消息对象，如果为空或不存在则返回 191004 参数错误。
`params`	`V2NIMSendMessageParams`	否	null	消息发送配置参数，包括发送、推送、抄送、反垃圾等配置。
`success`	`V2NIMSuccessCallback`	是	-	消息发送成功回调，返回 `V2NIMSendMessageResult`。
`failure`	`V2NIMFailureCallback`	是	-	消息发送失败回调，返回错误码。
`progress`	`V2NIMProgressCallback`	否	null	附件上传进度回调，用于图片、语音、视频、文件类型消息。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	发送的消息对象，通过调用 `V2NIMMessageCreator` 中的接口创建。如果为空或不存在则返回 191004 参数错误。
`replyMessage`	`V2NIMMessage`	是	-	被回复的消息对象，如果为空或不存在则返回 191004 参数错误。
`params`	`V2NIMSendMessageParams`	否	null	消息发送配置参数，包括发送、推送、抄送、反垃圾等配置。
`success`	`V2NIMSuccessCallback`	是	-	消息发送成功回调，返回 `V2NIMSendMessageResult`。
`failure`	`V2NIMFailureCallback`	是	-	消息发送失败回调，返回错误码。
`progress`	`V2NIMProgressCallback`	否	null	附件上传进度回调，用于图片、语音、视频、文件类型消息。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	发送的消息对象，通过调用 `V2NIMMessageCreator` 中的接口创建。如果为空或不存在则返回 191004 参数错误。
`replyMessage`	`V2NIMMessage`	是	-	被回复的消息对象，如果为空或不存在则返回 191004 参数错误。
`params`	`V2NIMSendMessageParams`	否	null	消息发送配置参数，包括发送、推送、抄送、反垃圾等配置。
`success`	`V2NIMSuccessCallback`	是	-	消息发送成功回调，返回 `V2NIMSendMessageResult`。
`failure`	`V2NIMFailureCallback`	是	-	消息发送失败回调，返回错误码。
`progress`	`V2NIMProgressCallback`	否	null	附件上传进度回调，用于图片、语音、视频、文件类型消息。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	发送的消息对象，通过调用 `V2NIMMessageCreator` 中的接口创建。如果为空或不存在则返回 191004 参数错误。
`replyMessage`	`V2NIMMessage`	是	-	被回复的消息对象，如果为空或不存在则返回 191004 参数错误。
`params`	`V2NIMSendMessageParams`	否	null	消息发送配置参数，包括发送、推送、抄送、反垃圾等配置。
`progress`	number	否	null	附件上传进度回调，用于图片、语音、视频、文件类型消息。

Harmony

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	发送的消息对象，通过调用 `V2NIMMessageCreator` 中的接口创建。如果为空或不存在则返回 191004 参数错误。
`replyMessage`	`V2NIMMessage`	是	-	被回复的消息对象，如果为空或不存在则返回 191004 参数错误。
`params`	`V2NIMSendMessageParams`	否	null	消息发送配置参数，包括发送、推送、抄送、反垃圾等配置。
`progress`	number	否	null	附件上传进度回调，用于图片、语音、视频、文件类型消息。

示例代码

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

cpp// 以文本消息为例，构建文本消息
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
}

Harmony

typescripttry {
const message: V2NIMMessage = nim.messageCreator.createTextMessage("reply text")
const result: V2NIMSendMessageResult = await nim.messageService.replyMessage(message, repliedMessage)
// todo Success
} catch (err) {
// todo error
}

实现消息快捷评论

支持针对某条消息进行快捷评论，评论内容通常为表情、短文本，由应用层定义评论内容与 UI 展示之间的映射关系。

注册消息监听器

Android/iOS/Windows/macOS

调用 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

cppV2NIMMessageListener listener;
listener.onMessageQuickCommentNotification = [](V2NIMMessageQuickCommentNotification quickCommentNotification) {
    // receive message quick comment notification
};
messageService.addMessageListener(listener);

Web/uni-app/小程序/Harmony

调用 on("EventName") 方法注册消息监听器，监听消息接收回调事件 onMessageQuickCommentNotification。

Web/uni-app/小程序

typescriptnim.V2NIMMessageService.on("onMessageQuickCommentNotification", function (quickCommentNotification: V2NIMMessageQuickCommentNotification) {})

Harmony

typescriptnim.messageService.on("onMessageQuickCommentNotification", function (quickCommentNotification: V2NIMMessageQuickCommentNotification) {})

添加快捷评论

调用 addQuickComment 方法针对指定消息添加一条快捷评论。添加成功后，消息发送方和消息接收方均会收到消息快捷评论操作通知回调 onMessageQuickCommentNotification 并通知 UI 界面更新。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	Long	是	-	自定义快捷评论索引，必须大于 0。可在本地自定义映射关系，例如：表情回复：1：笑脸；2：大笑。UI 层根据 `index` 展示对应的表情。文本快捷回复等其他回复场景。
`serverExtension`	String	否	null	评论服务端扩展字段。必须为 JSON 格式封装，长度上限为 8 字符，多端同步。
`pushConfig`	`V2NIMMessageQuickCommentPushConfig`	否	null	快捷评论推送配置
`success`	`V2NIMSuccessCallback`	是	-	评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	评论失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	NSInteger	是	-	自定义快捷评论索引，必须大于 0。可在本地自定义映射关系，例如：表情回复：1：笑脸；2：大笑。UI 层根据 `index` 展示对应的表情。文本快捷回复等其他回复场景。
`serverExtension`	NSString *	否	null	评论服务端扩展字段。必须为 JSON 格式封装，长度上限为 8 字符，多端同步。
`pushConfig`	`V2NIMMessageQuickCommentPushConfig`	否	null	快捷评论推送配置
`success`	`V2NIMSuccessCallback`	是	-	评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	评论失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	uint64_t	是	-	自定义快捷评论索引，必须大于 0。可在本地自定义映射关系，例如：表情回复：1：笑脸；2：大笑。UI 层根据 `index` 展示对应的表情。文本快捷回复等其他回复场景。
`serverExtension`	nstd::optionalnstd::string	否	null	评论服务端扩展字段。必须为 JSON 格式封装，长度上限为 8 字符，多端同步。
`pushConfig`	`V2NIMMessageQuickCommentPushConfig`	否	null	快捷评论推送配置
`success`	`V2NIMSuccessCallback`	是	-	评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	评论失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	number	是	-	自定义快捷评论索引，必须大于 0。可在本地自定义映射关系，例如：表情回复：1：笑脸；2：大笑。UI 层根据 `index` 展示对应的表情。文本快捷回复等其他回复场景。
`serverExtension`	String	否	null	评论服务端扩展字段。必须为 JSON 格式封装，长度上限为 8 字符，多端同步。
`pushConfig`	`V2NIMMessageQuickCommentPushConfig`	否	null	快捷评论推送配置

Harmony

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	number	是	-	自定义快捷评论索引，必须大于 0。可在本地自定义映射关系，例如：表情回复：1：笑脸；2：大笑。UI 层根据 `index` 展示对应的表情。文本快捷回复等其他回复场景。
`serverExtension`	String	否	null	评论服务端扩展字段。必须为 JSON 格式封装，长度上限为 8 字符，多端同步。
`pushConfig`	`V2NIMMessageQuickCommentPushConfig`	否	null	快捷评论推送配置

示例代码

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

cppV2NIMMessage 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
}

Harmony

typescripttry {
await nim.messageService.addQuickComment(message, 1, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}

移除快捷评论

调用 removeQuickComment 方法移除一条快捷评论。移除成功后，消息发送方和消息接收方均会收到消息快捷评论操作通知回调 onMessageQuickCommentNotification。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	Long	是	-	快捷评论索引，必须大于 0。
`serverExtension`	String	否	null	服务端扩展字段。长度上限为 8 字符，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	移除评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	移除评论失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	NSInteger	是	-	快捷评论索引，必须大于 0。
`serverExtension`	NSString *	否	null	服务端扩展字段。长度上限为 8 字符，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	移除评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	移除评论失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	uint32_t	是	-	快捷评论索引，必须大于 0。
`serverExtension`	nstd::optionalnstd::string	否	null	服务端扩展字段。长度上限为 8 字符，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	移除评论成功回调
`failure`	`V2NIMFailureCallback`	是	-	移除评论失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	number	是	-	快捷评论索引，必须大于 0。
`serverExtension`	String	否	null	服务端扩展字段。长度上限为 8 字符，多端同步。

Harmony

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`index`	number	是	-	快捷评论索引，必须大于 0。
`serverExtension`	String	否	null	服务端扩展字段。长度上限为 8 字符，多端同步。

示例代码

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

cppV2NIMMessageRefer 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
}

Harmony

typescripttry {
await nim.messageService.removeQuickComment(messageRefer, 1, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}

获取快捷评论列表

调用 getQuickCommentList 获取指定消息的所有快捷评论。获取结果不包含已删除消息的快捷评论，按照评论时间排序。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	List<`V2NIMMessage`>	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照评论时间排序的 `V2NIMMessageQuickComment` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	NSArray <`V2NIMMessage`>	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMGetQuickCommentListSuccess`	是	-	获取成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	std::vector<`V2NIMMessage`>	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照评论时间排序的 `V2NIMMessageQuickComment` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`messages`	`V2NIMMessage`[]	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`messages`	`V2NIMMessage`[]	是	-	被快捷评论的消息对象。如果为空或不存在则返回 191004 参数错误。

示例代码

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

cppnstd::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
}

Harmony

typescripttry {
const quickCommentList = await nim.messageService.getQuickCommentList(messages)
// todo Success
} catch (err) {
// todo error
}

实现收藏功能

支持收藏已发送成功的消息或其他自定义内容。

添加一条收藏

调用 addCollection 方法添加一条收藏。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`params`	`V2NIMAddCollectionParams`	是	-	收藏配置参数
`success`	`V2NIMSuccessCallback`	是	-	收藏成功回调，返回收藏对象 `V2NIMCollection`。
`failure`	`V2NIMFailureCallback`	是	-	收藏失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`params`	`V2NIMAddCollectionParams`	是	-	收藏配置参数
`success`	`V2NIMSuccessCallback`	是	-	收藏成功回调，返回收藏对象 `V2NIMCollection`。
`failure`	`V2NIMFailureCallback`	是	-	收藏失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`params`	`V2NIMAddCollectionParams`	是	-	收藏配置参数
`success`	`V2NIMSuccessCallback`	是	-	收藏成功回调，返回收藏对象 `V2NIMCollection`。
`failure`	`V2NIMFailureCallback`	是	-	收藏失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`params`	`V2NIMAddCollectionParams`	是	-	收藏配置参数

Harmony

参数名称	类型	是否必填	默认值	描述
`params`	`V2NIMAddCollectionParams`	是	-	收藏配置参数

示例代码

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

cppV2NIMAddCollectionParams 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
}

Harmony

typescripttry {
const res: V2NIMCollection = await nim.messageService.addCollection({
    collectionType: 1,
    collectionData: 'data',
    serverExtension: 'serverExtension'
})
// todo Success
} catch (err) {
// todo error
}

批量移除收藏

调用 removeCollections 批量移除收藏列表。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`collections`	List<`V2NIMCollection`>	是	-	收藏对象列表。不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	移除成功回调
`failure`	`V2NIMFailureCallback`	是	-	移除失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`collections`	NSArray<`V2NIMCollection` >	是	-	收藏对象列表。不可为空，否则返回 191004 参数错误。
`success`	`V2NIMRemoveCollectionSuccess`	是	-	移除成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	移除失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`collections`	nstd::vector<`V2NIMCollection`>	是	-	收藏对象列表。不可为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	移除成功回调
`failure`	`V2NIMFailureCallback`	是	-	移除失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`collections`	`V2NIMCollection`[]	是	-	收藏对象列表。不可为空，否则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`collections`	`V2NIMCollection`[]	是	-	收藏对象列表。不可为空，否则返回 191004 参数错误。

示例代码

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

cppnstd::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
}

Harmony

typescripttry {
const res: number = await nim.messageService.removeCollections(collections)
// todo Success
} catch (err) {
// todo error
}

更新收藏的服务端扩展字段

调用 updateCollectionExtension 更新收藏的服务端扩展字段。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`collection`	`V2NIMCollection`	是	-	收藏对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	空	收藏的服务端扩展字段。必须为 JSON 格式封装，如果设置为空则表示取消现有的扩展字段。
`success`	`V2NIMSuccessCallback`	是	-	更新成功回调，返回更新后的 `V2NIMCollection`。
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`collection`	`V2NIMCollection`	是	-	收藏对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	NSString *	否	空	收藏的服务端扩展字段。必须为 JSON 格式封装，如果设置为空则表示取消现有的扩展字段。
`success`	`V2NIMCollectionSuccess`	是	-	更新成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`collection`	`V2NIMCollection`	是	-	收藏对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	nstd::optionalnstd::string	否	空	收藏的服务端扩展字段。必须为 JSON 格式封装，如果设置为空则表示取消现有的扩展字段。
`success`	`V2NIMSuccessCallback`	是	-	更新成功回调，返回更新后的 `V2NIMCollection`。
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`collection`	`V2NIMCollection`	是	-	收藏对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	string	否	空	收藏的服务端扩展字段。必须为 JSON 格式封装，如果设置为空则表示取消现有的扩展字段。

Harmony

参数名称	类型	是否必填	默认值	描述
`collection`	`V2NIMCollection`	是	-	收藏对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	string	否	空	收藏的服务端扩展字段。必须为 JSON 格式封装，如果设置为空则表示取消现有的扩展字段。

示例代码

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

cppV2NIMCollection 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
}

Harmony

typescripttry {
const collection: V2NIMCollection = await nim.messageService.updateCollectionExtension(collection, 'newExtension')
// todo Success
} catch (err) {
// todo error
}

按照查询条件分页获取收藏列表

调用 getCollectionListByOption 方法按照查询条件分页获取收藏列表。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`option`	`V2NIMCollectionOption`	是	-	收藏查询选项
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照收藏时间排序的 `V2NIMCollection` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`option`	`V2NIMCollectionOption`	是	-	收藏查询选项
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照收藏时间排序的 `V2NIMCollection` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`option`	`V2NIMCollectionOption`	是	-	收藏查询选项
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照收藏时间排序的 `V2NIMCollection` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`option`	`V2NIMCollectionOption`	是	-	收藏查询选项

Harmony

参数名称	类型	是否必填	默认值	描述
`option`	`V2NIMCollectionOption`	是	-	收藏查询选项

示例代码

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

cppV2NIMCollectionOption 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
}

Harmony

typescripttry {
const res: V2NIMCollection[] = await nim.messageService.getCollectionListByOption({
    beginTime: 0,
    endTime: 0,
    direction: 0,
    limit: 100,
    collectionType: 0
})
// todo Success
} catch (err) {
// todo error
}

实现 PIN 消息

支持将会话中的重要消息执行 PIN 操作，被 PIN 的消息会以列表形式展示在 UI 界面。

一条消息可以被所在会话内的所有用户执行 PIN 操作，PIN 消息对会话内的所有成员可见。如果多个用户对同一条消息执行 PIN 操作，较晚的 PIN 会覆盖之前的 PIN。

注册消息监听器

Android/iOS/Windows/macOS

调用 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

cppV2NIMMessageListener listener;
listener.onMessagePinNotification = [](V2NIMMessagePinNotification pinNotification) {
    // receive message pin notification
};
messageService.addMessageListener(listener);

Web/uni-app/小程序/Harmony

调用 on("EventName") 方法注册消息监听器，监听消息接收回调事件 onMessageQuickCommentNotification。

Web/uni-app/小程序

typescriptnim.V2NIMMessageService.on("onMessagePinNotification", function (pinNotification: V2NIMMessagePinNotification) {})

Harmony

typescriptnim.messageService.on("onMessagePinNotification", function (pinNotification: V2NIMMessagePinNotification) {})

PIN 一条消息

调用 pinMessage 方法针对指定消息执行 PIN 操作。PIN 成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。不能重复 Pin 相同的消息，否则返回 191007 资源已存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	PIN 失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。不能重复 Pin 相同的消息，否则返回 191007 资源已存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	PIN 失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。不能重复 Pin 相同的消息，否则返回 191007 资源已存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	PIN 失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。不能重复 Pin 相同的消息，否则返回 191007 资源已存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

Harmony

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。不能重复 Pin 相同的消息，否则返回 191007 资源已存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

示例代码

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

cppV2NIMMessage 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
}

Harmony

typescripttry {
await nim.messageService.pinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}

更新 PIN 消息服务端扩展字段

调用 updatePinMessage 方法更新 PIN 消息服务端扩展字段。更新 PIN 消息成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。

如果更新 PIN 消息的操作人非当前登录账号，则 V2NIMMessagePin.operatorId 变更为更新 PIN 消息的实际操作人。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	null	PIN 消息的服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	更新成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	null	PIN 消息的服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	更新成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	null	PIN 消息的服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	更新成功回调
`failure`	`V2NIMFailureCallback`	是	-	更新失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	null	PIN 消息的服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

Harmony

参数名称	类型	是否必填	默认值	描述
`message`	`V2NIMMessage`	是	-	被 PIN 的消息对象。如果为空或不存在则返回 191004 参数错误。
`serverExtension`	String	否	null	PIN 消息的服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

示例代码

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

cppV2NIMMessage 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
}

Harmony

typescripttry {
await nim.messageService.updatePinMessage(message, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}

取消 PIN 消息

调用 unpinMessage 方法取消 PIN 一条消息。取消 PIN 消息成功后，消息发送方和消息接收方均会收到 PIN 消息状态变化通知回调 onMessagePinNotification 并通知 UI 界面更新。

参数说明

Android

参数名称	类型	是否必填	默认值	描述
`messageRefer`	`V2NIMMessageRefer`	是	-	被取消 PIN 的消息参考信息。如果为空或不存在则返回 191004 参数错误。不能重复取消 PIN 相同的消息，否则返回 191006 资源不存在错误。
`serverExtension`	String	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	取消 PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	取消 PIN 失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`messageRefer`	`V2NIMMessageRefer`	是	-	被取消 PIN 的消息参考信息。如果为空或不存在则返回 191004 参数错误。不能重复取消 PIN 相同的消息，否则返回 191006 资源不存在错误。
`serverExtension`	NSString *	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	取消 PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	取消 PIN 失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`messageRefer`	`V2NIMMessageRefer`	是	-	被取消 PIN 的消息参考信息。如果为空或不存在则返回 191004 参数错误。不能重复取消 PIN 相同的消息，否则返回 191006 资源不存在错误。
`serverExtension`	nstd::optionalnstd::string	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。
`success`	`V2NIMSuccessCallback`	是	-	取消 PIN 成功回调
`failure`	`V2NIMFailureCallback`	是	-	取消 PIN 失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`messageRefer`	`V2NIMMessageRefer`	是	-	被取消 PIN 的消息参考信息。如果为空或不存在则返回 191004 参数错误。不能重复取消 PIN 相同的消息，否则返回 191006 资源不存在错误。
`serverExtension`	string	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

Harmony

参数名称	类型	是否必填	默认值	描述
`messageRefer`	`V2NIMMessageRefer`	是	-	被取消 PIN 的消息参考信息。如果为空或不存在则返回 191004 参数错误。不能重复取消 PIN 相同的消息，否则返回 191006 资源不存在错误。
`serverExtension`	string	否	null	消息服务端扩展字段。必须为 JSON 格式封装，长度上限为 1024 字节，多端同步。

示例代码

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

cppV2NIMMessageRefer 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
}

Harmony

typescripttry {
await nim.messageService.unpinMessage(messageRefer, 'serverExtension')
// todo Success
} catch (err) {
// todo error
}

获取 PIN 消息列表

调用 getPinnedMessageList 获取会话内所有 PIN 消息。获取结果不包含已删除、已撤回的消息，结果按照更新时间排序。

参数说明:

Android

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，通过调用 `V2NIMConversationIdUtil` 的对应函数创建。组成方式：用户账号（accountId）\|会话类型（ `V2NIMConversationType`）\|聊天对象账号（accountId）或群组 ID。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照更新时间排序的 `V2NIMMessagePin` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，通过调用 `V2NIMConversationIdUtil` 的对应函数创建。组成方式：用户账号（accountId）\|会话类型（ `V2NIMConversationType`）\|聊天对象账号（accountId）或群组 ID。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照更新时间排序的 `V2NIMMessagePin` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，通过调用 `V2NIMConversationIdUtil` 的对应函数创建。组成方式：用户账号（accountId）\|会话类型（ `V2NIMConversationType`）\|聊天对象账号（accountId）或群组 ID。如果为空或不存在则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	获取成功回调，返回按照更新时间排序的 `V2NIMMessagePin` 列表。
`failure`	`V2NIMFailureCallback`	是	-	获取失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，通过调用 `V2NIMConversationIdUtil` 的对应函数创建。组成方式：用户账号（accountId）\|会话类型（ `V2NIMConversationType`）\|聊天对象账号（accountId）或群组 ID。如果为空或不存在则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`conversationId`	String	是	-	会话 ID，通过调用 `V2NIMConversationIdUtil` 的对应函数创建。组成方式：用户账号（accountId）\|会话类型（ `V2NIMConversationType`）\|聊天对象账号（accountId）或群组 ID。如果为空或不存在则返回 191004 参数错误。

示例代码

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

cpp// 构建会话 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
}

Harmony

typescripttry {
const messagePinArr = await nim.messageService.getPinnedMessageList('me|1|another')
// todo Success
} catch (err) {
// todo error
}

消息参考信息

根据消息参考信息获取消息列表

当消息数据不明确时，可使用该接口获取消息。推荐回复消息、PIN 消息场景下使用。

调用 getMessageListByRefers 方法根据参考信息获取消息列表。

SDK 查询策略如下：

查询引用消息.drawio.png

参数说明:

Android

参数名称	类型	是否必填	默认值	描述
`messageRefers`	List<`V2NIMMessageRefer`>	是	-	消息参考信息对象。不能为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMMessage` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

参数名称	类型	是否必填	默认值	描述
`messageRefers`	NSArray<`V2NIMMessageRefer`>	是	-	消息参考信息对象。不能为空，否则返回 191004 参数错误。
`success`	`V2NIMGetMessageListSuccess`	是	-	查询成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

macOS/Windows

参数名称	类型	是否必填	默认值	描述
`messageRefers`	nstd::vector<`V2NIMMessageRefer`>	是	-	消息参考信息对象。不能为空，否则返回 191004 参数错误。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMMessage` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Web/uni-app/小程序

参数名称	类型	是否必填	默认值	描述
`messageRefers`	`V2NIMMessageRefer`[]	是	-	消息参考信息对象。不能为空，否则返回 191004 参数错误。

Harmony

参数名称	类型	是否必填	默认值	描述
`messageRefers`	`V2NIMMessageRefer`[]	是	-	消息参考信息对象。不能为空，否则返回 191004 参数错误。

示例代码

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

cppnstd::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
}

Harmony

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
}

查询 Thread 消息

分页查询 Thread 历史消息列表

调用 getMessageListByRefers 方法分页获取云端 Thread 历史消息列表。

该方法用于根据 Thread 根消息分页获取所有 Thread 子消息。

为避免触发请求频控，若云端会话数据同步已完成（收到 V2NIMConversationListener.onSyncFinished），建议您改用 getLocalThreadMessageList 方法获取本地 Thread 历史消息列表。

参数说明:

Android

Javavoid getThreadMessageList(V2NIMThreadMessageListOption threadMessageListOption, V2NIMSuccessCallback<V2NIMThreadMessageListResult> success, V2NIMFailureCallback failure);

参数名称	类型	是否必填	默认值	说明
`threadMessageListOption`	`V2NIMThreadMessageListOption`	是	-	Thread 消息查询配置项，支持根据 Thread 根消息的参考信息分页查询子消息。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMThreadMessageListResult` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

Objective-C- (void)getThreadMessageList:(V2NIMThreadMessageListOption *)threadMessageListOption
                    success:(nullable V2NIMGetThreadMessageListSuccess)success
                    failure:(nullable V2NIMFailureCallback)failure;

参数名称	类型	是否必填	默认值	说明
`threadMessageListOption`	`V2NIMThreadMessageListOption`	是	-	Thread 消息查询配置项，支持根据 Thread 根消息的参考信息分页查询子消息。
`success`	`V2NIMGetThreadMessageListSuccess`	是	-	查询成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Windows/macOS

cppvirtual void v2::V2NIMMessageService::getThreadMessageList(V2NIMThreadMessageListOption threadMessageListOption, 
                                                        V2NIMSuccessCallback<V2NIMThreadMessageListResult> success,
                                                        V2NIMFailureCallback failure
)

参数名称	类型	是否必填	默认值	说明
`threadMessageListOption`	`V2NIMThreadMessageListOption`	是	-	Thread 消息查询配置项，支持根据 Thread 根消息的参考信息分页查询子消息。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMThreadMessageListResult` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Web/uni-app/小程序

TypeScriptgetThreadMessageList(option: V2NIMThreadMessageListOption): Promise<V2NIMThreadMessageListResul

参数名称	类型	是否必填	默认值	说明
`option`	`V2NIMThreadMessageListOption`	是	-	Thread 消息查询配置项，支持根据 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) {
        // 查询失败
    }];

Windows/macOS

cppV2NIMTheadMessageListOption 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)
}

查询本地 Thread 历史消息列表

调用 getMessageListByRefers 方法获取本地 Thread 历史消息列表。

该方法用于根据 Thread 根消息获取所有本地 Thread 子消息。

参数说明:

Android

Javavoid getLocalThreadMessageList(V2NIMMessageRefer messageRefer, V2NIMSuccessCallback<V2NIMThreadMessageListResult> success, V2NIMFailureCallback failure);

参数名称	类型	是否必填	默认值	说明
`messageRefer`	`V2NIMMessageRefer`	是	-	Thread 消息参考信息，支持根据 Thread 根消息的参考信息查询本地子消息。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMThreadMessageListResult` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

iOS

Objective-C- (void)getLocalThreadMessageList:(V2NIMMessageRefer *)messageRefer
                        success:(nullable V2NIMGetLocalThreadMessageListSuccess)success
                        failure:(nullable V2NIMFailureCallback)failure;

参数名称	类型	是否必填	默认值	说明
`messageRefer`	`V2NIMMessageRefer`	是	-	Thread 消息参考信息，支持根据 Thread 根消息的参考信息查询本地子消息。
`success`	`V2NIMGetLocalThreadMessageListSuccess`	是	-	查询成功回调，可自定义设置。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

Windows/macOS

cppvirtual void v2::V2NIMMessageService::getLocalThreadMessageList(V2NIMMessageRefer messageRefer,
                                                                V2NIMSuccessCallback<V2NIMThreadMessageListResult> success,
                                                                V2NIMFailureCallback failure)

参数名称	类型	是否必填	默认值	说明
`messageRefer`	`V2NIMMessageRefer`	是	-	Thread 消息参考信息，支持根据 Thread 根消息的参考信息查询本地子消息。
`success`	`V2NIMSuccessCallback`	是	-	查询成功回调，返回 `V2NIMThreadMessageListResult` 列表。
`failure`	`V2NIMFailureCallback`	是	-	查询失败回调，返回错误码。

示例代码

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) {
    // 查询失败
}];

Windows/macOS

cppV2NIMMessageRefer messageRefer;
// ...
messageService.getLocalThreadMessageList(
    messageRefer,
    [](V2NIMThreadMessageListResult response) {
        // do something
    },
    [](V2NIMError error) {
        // get message list by refers failed, handle error
    });

开通消息扩展相关功能

实现消息回复

回复一条消息

实现消息快捷评论

注册消息监听器

添加快捷评论

移除快捷评论

获取快捷评论列表

实现收藏功能

添加一条收藏

批量移除收藏

更新收藏的服务端扩展字段

按照查询条件分页获取收藏列表

实现 PIN 消息

注册消息监听器

PIN 一条消息

更新 PIN 消息服务端扩展字段

取消 PIN 消息

获取 PIN 消息列表

消息参考信息

根据消息参考信息获取消息列表

查询 Thread 消息

分页查询 Thread 历史消息列表

查询本地 Thread 历史消息列表

相关信息