功能描述
消息置顶功能是指在即时通讯 App 上，将特定消息固定在列表顶部的功能，即使有新的消息进来，它也会保持在顶部。这个功能可以帮助用户更容易地找到并访问他们认为重要或频繁查看的消息。
效果展示
您可以使用本功能实现如下的群聊消息置顶效果：
接口说明
消息置顶/取消置顶
消息置顶接口入参详解如下：
属性 | 含义 | 说明 |
groupID | 群 ID | 置顶/取消置顶的群聊 ID。 |
message | 消息对象 | 消息必须是发送成功的状态。 |
isPinned | 置顶/取消置顶 | 设置群消息是否置顶。 |
说明
1. 群聊最多支持 10 条置顶消息。
2. 如果置顶消息数量超过最大限制，调用接口会报 ERR_SVR_GROUP_PINNED_MESSAGE_COUNT_LIMIT 错误。
示例代码如下：
V2TIMManager.getMessageManager().pinGroupMessage(groupID, message, true, new V2TIMCallback() {@Overridepublic void onSuccess() {// 消息置顶成功}@Overridepublic void onError(int code, String desc) {// 消息置顶失败}});
[[V2TIMManager sharedInstance] pinGroupMessage:self.groupID message:message isPinned:YES succ:^{// 消息置顶成功} fail:^(int code, NSString *desc) {// 消息置顶失败}];
class Callback final : public V2TIMCallback {public:using SuccessCallback = std::function<void()>;using ErrorCallback = std::function<void(int, const V2TIMString &)>;Callback() = default;~Callback() override = default;void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {success_callback_ = std::move(success_callback);error_callback_ = std::move(error_callback);}void OnSuccess() override {if (success_callback_) {success_callback_();}}void OnError(int error_code, const V2TIMString &error_message) override {if (error_callback_) {error_callback_(error_code, error_message);}}private:SuccessCallback success_callback_;ErrorCallback error_callback_;};auto *callback = new Callback{};callback->SetCallback([=]() {// 消息置顶成功delete callback;},[=](int error_code, const V2TIMString &error_message) {// 消息置顶失败delete callback;});V2TIMManager::GetInstance()->GetMessageManager()->PinGroupMessage(groupID, message, true, callback);
获取已置顶的消息列表
如果需要获取消息置顶者，可以通过 V2TIMMessage 的 pinnerInfo 字段获取消息置顶者。
消息置顶接口入参详解如下：
属性 | 含义 | 说明 |
groupID | 群ID | 需要获取置顶消息列表的群聊 ID。 |
说明
此接口用于获取置顶消息列表，如果置顶消息漫游已过期（体验版 7 天过期，旗舰版 30 天过期）不会返回。
示例代码如下：
V2TIMManager.getMessageManager().getPinnedGroupMessageList(groupID, new V2TIMValueCallback<List<V2TIMMessage>>() {@Overridepublic void onSuccess(List<V2TIMMessage> v2TIMMessages) {// 获取置顶消息列表成功}@Overridepublic void onError(int code, String desc) {// 获取置顶消息列表失败}});
[[V2TIMManager sharedInstance] getPinnedGroupMessageList:self.groupID succ:^(NSArray<V2TIMMessage *> *messageList) {// 获取置顶消息列表成功} fail:^(int code, NSString *desc) {// 获取置顶消息列表失败}];
template <class T>class ValueCallback final : public V2TIMValueCallback<T> {public:using SuccessCallback = std::function<void(const T&)>;using ErrorCallback = std::function<void(int, const V2TIMString&)>;ValueCallback() = default;~ValueCallback() override = default;void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {success_callback_ = std::move(success_callback);error_callback_ = std::move(error_callback);}void OnSuccess(const T& value) override {if (success_callback_) {success_callback_(value);}}void OnError(int error_code, const V2TIMString& error_message) override {if (error_callback_) {error_callback_(error_code, error_message);}}private:SuccessCallback success_callback_;ErrorCallback error_callback_;};auto callback = new ValueCallback<V2TIMMessageVector>{};callback->SetCallback([=](const V2TIMMessageVector& messageVector) {// 获取置顶消息列表成功delete callback;},[=](int error_code, const V2TIMString& error_message) {// 获取置顶消息列表失败delete callback;});V2TIMManager::GetInstance()->GetMessageManager()->GetPinnedGroupMessageList(groupID, callback);
置顶消息列表变更通知
如果您事先调用
addAdvancedMsgListener添加了高级消息事件监听器，当置顶消息列表发生了更新，您会收onGroupMessagePinned(Android / iOS & Mac/ Windows) 回调。说明
如果变更类型为取消置顶，message 参数中只有消息发送者、序列号、随机数及时间戳为有效字段，不包含完整的消息体。
示例代码如下：
V2TIMManager.getMessageManager().addAdvancedMsgListener(new V2TIMAdvancedMsgListener() {@Overridepublic void onGroupMessagePinned(String groupID, V2TIMMessage message, boolean isPinned, V2TIMGroupMemberInfo opUser) {// 收到置顶消息列表变更的通知}});
[[V2TIMManager sharedInstance] addAdvancedMsgListener:self];- (void)onGroupMessagePinned:(NSString *)groupID message:(V2TIMMessage *)message isPinned:(BOOL)isPinned opUser:(V2TIMGroupMemberInfo *)opUser {// 收到置顶消息列表变更的通知}
V2TIMManager::GetInstance()->GetMessageManager()->AddAdvancedMsgListener(this);void OnGroupMessagePinned(const V2TIMString &groupID, const V2TIMMessage &message,bool isPinned, const V2TIMGroupMemberInfo &opUser) override {// 收到置顶消息列表变更的通知}
