Pin & Save Messages

Pin messages for everyone in a conversation and save messages privately using the CometChat iOS SDK, including message fields, fetching, and listener events.

Available from Chat SDK v4.1.9. These APIs require CometChatSDK v4.1.9 or later.

AI Integration Quick Reference

// Pin a message for everyone in the conversation
CometChat.pinMessage(messageId: 148) { msg in } onError: { err in }
CometChat.unpinMessage(messageId: 148) { msg in } onError: { err in }

// Save a message privately for the logged-in user
CometChat.saveMessage(messageId: 148) { msg in } onError: { err in }
CometChat.unsaveMessage(messageId: 148) { msg in } onError: { err in }

// Presence of the timestamp IS the boolean
let isPinned = message.pinnedAt != 0
let isSaved  = message.savedAt != 0

// Fetch pinned messages in a conversation
MessagesRequest.MessageRequestBuilder().set(guid: "guid").set(pinned: true).set(limit: 100).build()

// Fetch the user's saved messages across all conversations
MessagesRequest.MessageRequestBuilder().set(saved: true).set(limit: 100).build()

// Listen for events (CometChatMessageDelegate)
func onMessagePinned(message: BaseMessage) { }
func onMessageUnpinned(message: BaseMessage) { }
func onMessageSaved(message: BaseMessage) { }
func onMessageUnsaved(message: BaseMessage) { }

Pin and save let users mark messages for later. The two features look similar but differ in who sees the result:

	Pin	Save
Visibility	Everyone in the conversation	Private to the user
Scope	One conversation	All conversations
Permission	Group owner, admin or moderator	Anyone
Limit	100 per conversation	100 per user

---

​

Pin a Message

Pinning is conversation-wide: every participant sees the message as pinned.

Swift

CometChat.pinMessage(messageId: 148) { message in
    print("Pinned at: \(message.pinnedAt) by \(message.pinnedBy)")
} onError: { error in
    print("Error: \(error.errorDescription)")
}

Pinning is permission-gated. In a group, only the owner, admins and moderators can pin or unpin; everyone can view the pinned list. In one-to-one conversations both participants can pin.

---

​

Unpin a Message

Swift

CometChat.unpinMessage(messageId: 148) { message in
    // pinnedAt is cleared back to 0
    print("Unpinned: \(message.pinnedAt == 0)")
} onError: { error in
    print("Error: \(error.errorDescription)")
}

---

​

Save a Message

Saving is private to the logged-in user and syncs across that user’s own devices. It carries no permission checks.

Swift

CometChat.saveMessage(messageId: 148) { message in
    print("Saved at: \(message.savedAt)")
} onError: { error in
    print("Error: \(error.errorDescription)")
}

---

​

Unsave a Message

Swift

CometChat.unsaveMessage(messageId: 148) { message in
    print("Unsaved: \(message.savedAt == 0)")
} onError: { error in
    print("Error: \(error.errorDescription)")
}

All four methods return the updated BaseMessage.

---

​

Message Fields

Three fields on BaseMessage carry the state:

Field	Type	Scope	Description
pinnedAt	Double	Global	When the message was pinned. 0 when not pinned.
pinnedBy	String	Global	UID of the last user to pin it. app_system for a system pin.
savedAt	Double	Per-viewer	When the logged-in user saved it. 0 when not saved.

Presence of the timestamp is the boolean. There is no separate isPinned flag — check pinnedAt != 0 and savedAt != 0. Unpinning and unsaving clear the field back to 0 rather than leaving a stale value.

savedAt is per-viewer: it is only ever populated for the user who saved the message, so you cannot use it to tell whether someone else saved it.

Swift

let isPinned = message.pinnedAt != 0
let isSaved  = message.savedAt != 0

// A pin applied by an admin from the dashboard rather than a user
let isSystemPin = message.pinnedBy == "app_system"

---

​

Fetch Pinned Messages

Pinned messages are fetched with MessagesRequest filtered by pinned, scoped to a conversation with uid or guid.

Group

let request = MessagesRequest.MessageRequestBuilder()
    .set(guid: "cometchat-guid-1")
    .set(pinned: true)
    .set(limit: 100)
    .build()

request.fetchPrevious { messages in
    print("Pinned: \(messages?.count ?? 0)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

One-to-one

let request = MessagesRequest.MessageRequestBuilder()
    .set(uid: "cometchat-uid-1")
    .set(pinned: true)
    .set(limit: 100)
    .build()

request.fetchPrevious { messages in
    print("Pinned: \(messages?.count ?? 0)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

---

​

Fetch Saved Messages

Saved messages are a per-user collection spanning every conversation, so the request takes no uid or guid.

Swift

let request = MessagesRequest.MessageRequestBuilder()
    .set(saved: true)
    .set(limit: 100)
    .build()

request.fetchPrevious { messages in
    // Each message carries receiverUid / receiverType identifying its source conversation
    print("Saved: \(messages?.count ?? 0)")
} onError: { error in
    print("Error: \(error?.errorDescription)")
}

Both limits are capped at 100 server-side, so a single page fetches the whole list.

---

​

Real-time Events

Implement CometChatMessageDelegate to receive pin and save updates. All four callbacks are optional and each carries the full updated message.

Swift

extension ViewController: CometChatMessageDelegate {

    func onMessagePinned(message: BaseMessage) {
        // Broadcast to everyone in the conversation
        print("Pinned by \(message.pinnedBy)")
    }

    func onMessageUnpinned(message: BaseMessage) {
        print("Unpinned: \(message.id)")
    }

    func onMessageSaved(message: BaseMessage) {
        // Private — only reaches the saving user's other devices
        print("Saved: \(message.id)")
    }

    func onMessageUnsaved(message: BaseMessage) {
        print("Unsaved: \(message.id)")
    }
}

Register the delegate as you would for any message event — see Real-time Delegates and Listeners.

Pin events are broadcast to every participant. Save events are private and reach only the saving user’s other devices.

---

Your own pin, unpin, save or unsave is reported through its onSuccess closure only. It does not fire onMessagePinned, onMessageUnpinned, onMessageSaved or onMessageUnsaved on the device that made the change, so update your UI from onSuccess.

​

Feature Availability

Both features are gated per app and can be checked before showing any UI:

Swift

if CometChat.isPinMessageEnabled() {
    // Show pin options
}

if CometChat.isSaveMessageEnabled() {
    // Show save options
}

---

​

Error Handling

Error code	Meaning
ERR_PINNED_MESSAGES_LIMIT_EXCEEDED	The conversation already has the maximum pinned messages.
ERR_SAVED_MESSAGES_LIMIT_EXCEEDED	The user already has the maximum saved messages.
ERR_PERMISSION_DENIED	The user’s scope does not allow pinning here.
ERR_MESSAGE_NO_ACCESS	The user cannot access this message.
ERR_MESSAGE_ACTION_NOT_ALLOWED	The action is not allowed on this message.
ERR_FEATURE_NOT_ACCESSIBLE	The feature is not enabled for this app.

CometChatException carries an optional errorParams dictionary holding structured, machine-readable details the server sent alongside the error — so you can react to an error programmatically instead of parsing errorDescription.

Swift

CometChat.pinMessage(messageId: messageId) { _ in
    // pinned
} onError: { error in
    if error.errorCode == "ERR_PINNED_MESSAGES_LIMIT_EXCEEDED",
       let limit = error.errorParams?["limit"] as? Int {
        print("This conversation allows at most \(limit) pinned messages")
    }
}

For the two limit errors, read the actual cap from errorParams rather than hard-coding a number — the limit is server-owned and may change.

errorParams is [String: Any]? and is therefore not exposed to Objective-C. It is nil when the server sent no structured details, so always unwrap it.

---

​

Edge Cases

Scenario	Behavior
A pinned message is deleted	Automatically unpinned; no placeholder is left behind.
A pinned message is edited	Keeps its pin.
A saved message becomes inaccessible	Dropped from subsequent saved fetches.
A thread reply	Can be pinned and saved. Pinned lists return the parent message for context.
Someone else unpins your pin	Allowed — any user with permission can unpin.

---

​

Related

• Pinned Messages UI Component
• Saved Messages UI Component
• Additional Message Filtering
• Real-time Delegates and Listeners