Saved Messages - CometChat Docs

CometChatSavedMessages is a full-screen list of the messages the logged-in user has saved, newest save first. Saves are private to the user and span every conversation, so each row is labelled with the chat it came from.

AI Integration Quick Reference

{
  "component": "CometChatSavedMessages",
  "package": "CometChatUIKitSwift",
  "import": "import CometChatUIKitSwift\nimport CometChatSDK",
  "description": "Full-screen, user-level list of saved messages spanning all conversations, newest save first",
  "inherits": "CometChatListBase",
  "primaryOutput": {
    "callback": "onMessageClicked",
    "type": "(BaseMessage) -> Void"
  },
  "props": {
    "data": {
      "requestBuilder": { "type": "MessagesRequest.MessageRequestBuilder", "note": "Must retain set(saved: true); takes no uid/guid" }
    },
    "callbacks": {
      "onMessageClicked": "(BaseMessage) -> Void",
      "onError": "(CometChatException) -> Void",
      "onLoad": "([BaseMessage]) -> Void",
      "onEmpty": "() -> Void",
      "onBack": "() -> Void"
    },
    "visibility": {
      "hideUnsaveOption": { "type": "Bool", "default": false }
    },
    "styling": {
      "style": { "type": "SavedMessagesStyle" },
      "dateStyle": { "type": "DateStyle" },
      "avatarStyle": { "type": "AvatarStyle" }
    },
    "viewSlots": {
      "titleView": "(BaseMessage?) -> UIView",
      "subtitle": "(BaseMessage?) -> UIView",
      "leadingView": "(BaseMessage?) -> UIView",
      "trailingView": "(BaseMessage?) -> UIView",
      "listItemView": "(BaseMessage?) -> UIView"
    }
  },
  "events": ["onMessageSaved", "onMessageUnsaved", "ccMessageSaved"],
  "sdkListeners": ["CometChatConnectionDelegate"],
  "compositionExample": {
    "description": "Opened from app chrome, not a conversation header, because saves are user-level",
    "components": ["CometChatSavedMessages", "CometChatMessageList"],
    "flow": "User opens Saved messages from the chats screen menu → taps a row → the source conversation opens"
  }
}

Field	Value
Component	`CometChatSavedMessages`
Package	`CometChatUIKitSwift`
Inherits	`CometChatListBase`

Where It Fits

This is a user-level screen, not a per-conversation one. It takes no user or group — it always shows the logged-in user’s saves across every chat. Open it from your app’s chrome (a tab, the chats-screen menu, a profile or settings entry), not from a conversation header.

Contrast with Pinned Messages, which is scoped to one conversation and visible to everyone in it. Saves are private: only the saving user sees them, synced across that user’s own devices. Pin and save are off by default — see the Pin and Save Messages guide to turn them on. This screen is read-only by design: opening it never marks anything as read, sends receipts, or changes the unread count.

Minimal Render

CometChatSavedMessages is a view controller with a no-argument initializer.

import UIKit
import CometChatUIKitSwift
import CometChatSDK

let savedVC = CometChatSavedMessages()
navigationController?.pushViewController(savedVC, animated: true)

If you push this screen from a tab that hides the navigation bar, set hideNavigationBar = false or the title and back button never appear.Do not also set hideBackButton = false. The component supplies its own back chevron as a left bar button item, so clearing that flag renders two back buttons side by side.

let savedVC = CometChatSavedMessages()
savedVC.hidesBottomBarWhenPushed = true
savedVC.hideNavigationBar = false

navigationController?.setNavigationBarHidden(false, animated: true)
navigationController?.pushViewController(savedVC, animated: true)

Filtering

The list is fetched with a MessagesRequest.MessageRequestBuilder. The default comes from SavedMessagesBuilder:

// The default builder used when you set nothing
MessagesRequest.MessageRequestBuilder()
    .set(limit: 100)
    .set(saved: true)

Unlike the pinned builder there is no uid or guid to set — saved messages are a per-user collection spanning every conversation. The server caps saves at 100, so a limit of 100 fetches the entire list in one page.

// MARK: - Only saved text messages
let requestBuilder = MessagesRequest.MessageRequestBuilder()
    .set(limit: 100)
    .set(saved: true)
    .set(types: ["text"])

let savedVC = CometChatSavedMessages()
savedVC.set(requestBuilder: requestBuilder)

A custom request builder must keep set(saved: true). Without it the request returns every message the user can see and the screen lists them all as though they were saved.

Actions and Events

Callback Props

onMessageClicked

Fires when a row is tapped. Because a row can belong to any conversation, use it to open that message’s own chat — see Common Patterns.

savedVC.set(onMessageClicked: { [weak self] message in
    self?.openConversation(for: message)
})

onError

Fires when the fetch fails, and again when an unsave fails.

savedVC.set(onError: { error in
    print("Saved messages error: \(error.errorCode)")
})

onLoad

Fires with the fetched messages each time the list reloads.

savedVC.set(onLoad: { messages in
    print("Loaded \(messages.count) saved messages")
})

onEmpty

Fires when the fetch completes with nothing saved.

onBack

Inherited from CometChatListBase. The component ships a default that pops the navigation stack; set your own to replace it — useful when you also need to re-hide the navigation bar on the way out.

savedVC.set(onBack: { [weak self] in
    self?.navigationController?.setNavigationBarHidden(true, animated: true)
    self?.navigationController?.popViewController(animated: true)
})

Actions Reference

Action	Trigger	Default behavior
Row tap	User taps a saved message	Calls `onMessageClicked`; no default navigation
Unsave	User swipes a row from the trailing edge	Unsaves the message, removes the row, shows a toast
Back	User taps the back chevron	Pops the navigation stack
Pull to refresh	User pulls the list down	Refetches the saved list

Global UI Events

Event	Meaning
`ccMessageSaved`	The local user saved or unsaved a message. Read `message.savedAt` to tell which — non-zero means saved.

See Events for the full listener surface.

Custom View Slots

Each slot receives the row’s BaseMessage and returns a view that replaces the default.

set(titleView:)

Replaces the row title, which by default is the source conversation name rather than the sender.

savedVC.set(titleView: { message in
    let label = UILabel()
    label.text = message?.sender?.name ?? ""
    return label
})

set(subtitle:)

Replaces the message-preview line.

set(leadingView:)

Replaces the leading slot, which holds the source conversation’s avatar by default.

set(trailingView:)

Replaces the trailing slot, which holds the timestamp by default.

set(listItemView:)

Replaces the entire row.

Styling

Style Hierarchy

SavedMessagesStyle conforms to ListBaseStyle and ListItemStyle, so it carries the standard list properties plus two save-specific ones.

Global Level Styling

// MARK: - Apply global styling
CometChatSavedMessages.style.backgroundColor = UIColor(hex: "#F76808")
CometChatSavedMessages.style.unsaveActionBackgroundColor = UIColor(hex: "#D92D20")

Instance Level Styling

// MARK: - Apply instance-level styling
var customStyle = SavedMessagesStyle()
customStyle.backgroundColor = UIColor(hex: "#F76808")
customStyle.messageTypeImageTint = CometChatTheme.iconColorHighlight

let savedVC = CometChatSavedMessages()
savedVC.set(style: customStyle)

Key Style Properties

Property	Description	Default
`messageTypeImageTint`	Tint of the message-type glyph leading the preview (photo, video, document).	`CometChatTheme.iconColorSecondary`
`unsaveActionBackgroundColor`	Background of the unsave swipe action.	`CometChatTheme.errorColor`
`backgroundColor`	Screen background.	`CometChatTheme.backgroundColor01`
`titleColor`	Navigation title color.	`CometChatTheme.textColorPrimary`
`listItemTitleTextColor`	Row title color.	`CometChatTheme.textColorPrimary`
`listItemTitleFont`	Row title font.	`CometChatTypography.Heading4.medium`
`listItemSubTitleTextColor`	Row preview color.	`CometChatTheme.textColorSecondary`
`listItemSubTitleFont`	Row preview font.	`CometChatTypography.Body.regular`
`emptyTitleTextColor`	Empty-state title color.	`CometChatTheme.textColorPrimary`
`errorTitleTextColor`	Error-state title color.	`CometChatTheme.textColorPrimary`

Customization Matrix

What to change	Where	Property/API
Unsave swipe color	Style	`style.unsaveActionBackgroundColor`
Hide unsave entirely	Prop	`set(hideUnsaveOption: true)`
Media glyph tint	Style	`style.messageTypeImageTint`
Row layout	View slot	`set(listItemView:)`
Which messages appear	Filter	`set(requestBuilder:)`
Row tap behavior	Callback	`set(onMessageClicked:)`

Props

All props are optional. Sorted alphabetically.

avatarStyle

Styling for the row avatar, which shows the source conversation.


Type	`AvatarStyle`
Default	`CometChatAvatar.style`

dateStyle

Styling for the row timestamp.


Type	`DateStyle`
Default	`CometChatDate.style`, flattened to bare text

dateTimeFormatter

Custom timestamp formatting.


Type	`CometChatDateTimeFormatter`
Default	`CometChatUIKit.dateTimeFormatter`

hideUnsaveOption

Hides the per-row unsave swipe action.


Type	`Bool`
Default	`false`

savedVC.set(hideUnsaveOption: true)

style

The component’s style object.


Type	`SavedMessagesStyle`
Default	`SavedMessagesStyle()`

Methods

set(requestBuilder:)

Replaces the request used to fetch the list. Must retain set(saved: true).

set(textFormatters:)

Applies custom text formatters to the message previews.

savedVC.set(textFormatters: [myCustomTextFormatter])

SavedMessagesViewModel is public in name only — every member except setRequestBuilder(requestBuilder:) is internal. Customize through the props and view slots above rather than the view model.

Common Patterns

Saves are user-level, so the entry point belongs in app chrome rather than a conversation.

private func openSavedMessages() {
    let savedVC = CometChatSavedMessages()
    savedVC.hidesBottomBarWhenPushed = true

    // The component supplies its own back chevron, so leave hideBackButton alone.
    savedVC.hideNavigationBar = false

    savedVC.set(onBack: { [weak self] in
        self?.navigationController?.setNavigationBarHidden(true, animated: true)
        self?.navigationController?.popViewController(animated: true)
    })

    savedVC.set(onMessageClicked: { [weak self] message in
        self?.openConversation(for: message)
    })

    // The chats screen hides the bar; unhide it before pushing.
    navigationController?.setNavigationBarHidden(false, animated: true)
    navigationController?.pushViewController(savedVC, animated: true)
}

Open the conversation a row came from

A saved row can belong to any chat, so resolve the conversation from the message before navigating. For a group, look it up by receiverUid. For one-to-one, a received message is addressed to the logged-in user, so the conversation is with its sender.

private func openConversation(for message: BaseMessage) {
    let openMessages: (CometChatSDK.User?, Group?) -> Void = { [weak self] user, group in
        guard let self = self, user != nil || group != nil else { return }
        let messages = MessagesVC()
        messages.user = user
        messages.group = group
        self.navigationController?.pushViewController(messages, animated: true)
    }

    if message.receiverType == .group {
        CometChat.getGroup(GUID: message.receiverUid) { group in
            DispatchQueue.main.async { openMessages(nil, group) }
        } onError: { _ in }
    } else {
        // A received 1:1 message is addressed to the logged-in user, so the
        // conversation is with its sender; one they sent is addressed to the other party.
        let isReceived = message.receiverUid == CometChat.getLoggedInUser()?.uid
        let uid = isReceived ? (message.sender?.uid ?? message.receiverUid) : message.receiverUid

        CometChat.getUser(UID: uid) { user in
            DispatchQueue.main.async { openMessages(user, nil) }
        } onError: { _ in }
    }
}

Custom empty state

let savedVC = CometChatSavedMessages()
savedVC.emptyStateTitleText = "Nothing saved yet"
savedVC.emptyStateSubTitleText = "Save messages to read them later."

Pinned Messages - The per-conversation pinned messages screen
Message List - Where messages are saved and unsaved
Conversations - The chats screen that hosts the entry point
Events - Pin and save event callbacks

Pin and Save Messages Guide

End-to-end setup for pinning and saving

Chat SDK: Pin and Save

The underlying SDK methods and message fields

​Where It Fits

​Minimal Render

​Filtering

​Actions and Events

​Callback Props

​onMessageClicked

​onError

​onLoad

​onEmpty

​onBack

​Actions Reference

​Global UI Events

​Custom View Slots

​set(titleView:)

​set(subtitle:)

​set(leadingView:)

​set(trailingView:)

​set(listItemView:)

​Styling

​Style Hierarchy

​Global Level Styling

​Instance Level Styling

​Key Style Properties

​Customization Matrix

​Props

​avatarStyle

​dateStyle

​dateTimeFormatter

​hideUnsaveOption

​style

​Methods

​set(requestBuilder:)

​set(textFormatters:)

​Common Patterns

​Open from the chats screen menu

​Open the conversation a row came from

​Custom empty state

​Related Components

Pin and Save Messages Guide

Chat SDK: Pin and Save

Where It Fits

Minimal Render

Filtering

Actions and Events

Callback Props

onMessageClicked

onError

onLoad

onEmpty

onBack

Actions Reference

Global UI Events

Custom View Slots

set(titleView:)

set(subtitle:)

set(leadingView:)

set(trailingView:)

set(listItemView:)

Styling

Style Hierarchy

Global Level Styling

Instance Level Styling

Key Style Properties

Customization Matrix

Props

avatarStyle

dateStyle

dateTimeFormatter

hideUnsaveOption

style

Methods

set(requestBuilder:)

set(textFormatters:)

Common Patterns

Open from the chats screen menu

Open the conversation a row came from

Custom empty state

Related Components