SDKsuni-app / uni-app xEnterprise

Pin or unpin a message

Pin or unpin a specific message to the top of a conversation and handle pinned message events.

Pinning messages is a Commercial Edition capability. Invoke setConversationPinnedMsg() with pinned: true to pin a message to the top banner of a conversation, or pinned: false to unpin it.

Parameters

Parameter	Type	Required	Description
`conversationID`	`string`	Yes	Identifier of the conversation containing the message.
`clientMsgID`	`string`	Yes	The `clientMsgID` of the message to pin or unpin.
`pinned`	`boolean`	Yes	Pass `true` to pin the message, or `false` to unpin it.

Caller permissions, supported message types, and maximum pin counts are strictly verified by OpenIMServer.

Code example

import { setConversationPinnedMsg } from '@/uni_modules/unix-openim-sdk'

const clientMsgID = message.clientMsgID
if (clientMsgID == null) return

await setConversationPinnedMsg({
  conversationID,
  clientMsgID,
  pinned: true,
})

Return value

The Promise resolves with void upon successful server processing.

Listen for pinned message changes

Centrally register onChangedPinnedMsg to observe changes in pinned messages. The event delivers an opaque string notification signal. Treat this signal as an invalidation trigger to re-query the pinned messages for the active conversation rather than parsing undocumented properties.

import { off, onChangedPinnedMsg } from '@/uni_modules/unix-openim-sdk'

const handlePinnedMessagesChanged = (_payload: string) => {
  reloadPinnedMessagesForCurrentConversation()
}

const pinnedMessagesSubscription =
  onChangedPinnedMsg(handlePinnedMessagesChanged)

function removePinnedMessagesListener() {
  off(pinnedMessagesSubscription)
}

For query implementation details, see Get pinned messages. Unregister the listener when unmounting the view, logging out, or switching accounts.

Was this page helpful?