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.

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.

---

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.

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

---

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