Pin & Save Messages is now available across all popular platforms through the CometChat dashboard. The feature introduces two distinct ways to mark messages as important: pins, which are shared across a conversation, and saves, which are personal to each user.
Why this matters
Pinning and saving solve different problems in a chat experience.
A pinned message highlights something important for everyone in a conversation, such as an announcement, guideline, or key update. Saved messages, on the other hand, allow individual users to bookmark content for later without changing the experience for anyone else.
Previously, teams often had to build this functionality using custom message metadata and manage separate logic for permissions, syncing, and message state. Pin & Save Messages provides these capabilities as part of the CometChat message system.
Key Features and Capabilities
Pin messages for an entire conversation
Use CometChat.pinMessage(...) and unpinMessage(...) to manage pinned messages in one-on-one and group conversations.
Pinned messages are shared with everyone in the conversation.
Save messages privately
Use CometChat.saveMessage(...) and unsaveMessage(...) to create a personal list of saved messages.
Saved messages are private to each user and sync across that user's devices without affecting other participants.
Fetch pinned and saved messages directly
Use MessageRequestBuilder.set(pinned: true) or set(saved: true) to retrieve pinned or saved messages directly, without filtering messages client-side.
Message state is available directly on the message
BaseMessage.pinnedAt, pinnedBy, and savedAt provide the relevant state directly on the message object.
Receive real-time updates
The following delegate callbacks allow your app to respond when message state changes:
onMessagePinned
onMessageUnpinned
onMessageSaved
onMessageUnsaved
This means changes made from another device can be reflected in real time.
Check feature availability at runtime
Use CometChat.isPinMessageEnabled() and isSaveMessageEnabled() to check whether each feature is enabled for your app before exposing the corresponding UI.
REST API support
You can also pin messages through the REST API using:
POST /messages/{id}/pin
The optional onBehalfOf header allows the request to pin a message as a specific user rather than as the application.
How Pinning Works
Pinning supports two different identities.
If you call the REST API without the onBehalfOf header, the message is pinned by the application and pinnedBy is returned as app_system.
If you include the onBehalfOf header, the message is pinned on behalf of that user. The user's role and permissions are then used to determine whether the action is allowed.
This makes it possible to distinguish between system-level pins and pins created by specific users, such as moderators or administrators.
Pin Limit
Each conversation can have up to five pinned messages.
Attempting to pin a sixth message returns:
ERR_PINNED_MESSAGES_LIMIT_EXCEEDED
The oldest pinned message is not automatically removed, so applications should handle this limit explicitly in the UI and user flow.
Reference Links
iOS Chat SDK v4.1.9 Release Notes
https://github.com/cometchat/chat-sdk-ios/releases/tag/4.1.9
REST API: Pin Message
https://www.cometchat.com/docs/rest-api/messages/pin-message
Nivedita Bharathy
Product Marketing Specialist , CometChat