Save A Message

AI Integration Quick Reference

// Save / unsave a message
CometChat.saveMessage(messageId, callbackListener)     // -> BaseMessage
CometChat.unsaveMessage(messageId, callbackListener)   // -> BaseMessage

// Fetch the saved list — user-level, so do NOT set a UID or GUID
val request = MessagesRequest.MessagesRequestBuilder()
    .setSaved(true)
    .setLimit(50)
    .build()
request.fetchNext(callbackListener)                    // List<BaseMessage>

// Read save state off a message
val isSaved = message.isSaved                          // savedAt > 0

// Cap and availability
val limit = CometChat.getSaveMessageLimit()            // -1 when unspecified
val enabled = CometChat.isSaveMessageEnabled()         // Boolean

Let users bookmark messages for later. Saving a message is private to the logged-in user — nobody else in the conversation can see it — and works across conversations: a user’s saved messages from all of their chats appear in one list, synced across all of their devices. Let’s see how to work with saved messages in CometChat’s Android SDK.

Saving a message with the SDK requires the Save Message feature to be enabled for your app. You can check its availability at runtime using the feature flag.

To save a message, use the saveMessage method and pass the ID of the message. On success, the callback returns the updated BaseMessage with its savedAt attribute set.

Java
Kotlin

long messageId = 1;

CometChat.saveMessage(messageId, new CometChat.CallbackListener<BaseMessage>() {
  @Override
  public void onSuccess(BaseMessage message) {
      Log.d(TAG, "Message saved at: " + message.getSavedAt());
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Failed to save message: " + e.getMessage());
  }
});

val messageId = 1L

CometChat.saveMessage(messageId, object : CometChat.CallbackListener<BaseMessage>() {
  override fun onSuccess(message: BaseMessage?) {
      Log.d(TAG, "Message saved at: ${message?.savedAt}")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Failed to save message: ${e?.message}")
  }
})

Saving is idempotent — saving an already saved message succeeds and refreshes getSavedAt() rather than failing.

A just-sent message may not be pinnable or savable yet. On an app with moderation enabled, the server stamps a new message as moderation-pending and clears it a moment later. While it is pending, the call is rejected with ERR_MESSAGE_NO_ACCESS — the same code returned for a genuine permission refusal, so you cannot tell the two apart from the error alone.The window runs from send, not from the user’s tap, and clears within a few seconds. Do not disable the control on this error: by the time someone opens a menu and taps, moderation has usually finished. Prefer a retry or a transient “not ready yet” message over telling the user they lack permission. Moderation is configured per app, so this never reproduces on an app that has it switched off. (The CometChat UI Kits already withhold the Pin/Save options on a moderation-pending, disapproved, deleted or not-yet-sent message; this only concerns custom UI built directly on the SDK.)

Unlike pinning, saving has no role restrictions — every user can save any message they have access to. Deleted messages cannot be saved.

Unsave a Message

To remove a message from the user’s saved list, use the unsaveMessage method. On success, the callback returns the updated BaseMessage with its savedAt attribute cleared.

Java
Kotlin

long messageId = 1;

CometChat.unsaveMessage(messageId, new CometChat.CallbackListener<BaseMessage>() {
  @Override
  public void onSuccess(BaseMessage message) {
      Log.d(TAG, "Message unsaved. isSaved: " + message.isSaved());
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Failed to unsave message: " + e.getMessage());
  }
});

val messageId = 1L

CometChat.unsaveMessage(messageId, object : CometChat.CallbackListener<BaseMessage>() {
  override fun onSuccess(message: BaseMessage?) {
      Log.d(TAG, "Message unsaved. isSaved: ${message?.isSaved}")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Failed to unsave message: ${e?.message}")
  }
})

Fetch Saved Messages

To fetch all messages the logged-in user has saved, create a MessagesRequest with the setSaved(true) filter of the MessagesRequestBuilder. Because saved messages are user-level and span conversations, you must not set a UID or GUID. The returned list is sorted by the time of saving, most recently saved first.

Java
Kotlin

MessagesRequest messagesRequest = new MessagesRequest.MessagesRequestBuilder()
  .setSaved(true)
  .setLimit(50)
  .build();

messagesRequest.fetchNext(new CometChat.CallbackListener<List<BaseMessage>>() {
  @Override
  public void onSuccess(List<BaseMessage> messages) {
      Log.d(TAG, "Saved messages: " + messages.size());
  }

  @Override
  public void onError(CometChatException e) {
      Log.e(TAG, "Saved messages fetch failed: " + e.getMessage());
  }
});

val messagesRequest = MessagesRequest.MessagesRequestBuilder()
  .setSaved(true)
  .setLimit(50)
  .build()

messagesRequest.fetchNext(object : CometChat.CallbackListener<List<BaseMessage>>() {
  override fun onSuccess(messages: List<BaseMessage>?) {
      Log.d(TAG, "Saved messages: ${messages?.size}")
  }

  override fun onError(e: CometChatException?) {
      Log.e(TAG, "Saved messages fetch failed: ${e?.message}")
  }
})

The list is ordered by save time, most recently saved first — not by when the messages were sent. Page it with fetchNext() until a call returns an empty list; the cursor rides on savedAt instead of sentAt, and the SDK swaps it for you.

If the user loses access to a conversation (for example, they are removed from a group), messages saved from it are cleaned up and no longer returned.

Check if a Message is Saved

Every fetched message carries the logged-in user’s save state on the BaseMessage itself. These values are per-user: the same message shows different values to different users.

Method	Description
`isSaved()`	Returns `true` if the logged-in user has saved this message.
`getSavedAt()`	The timestamp at which the logged-in user saved the message. `0` when it is not saved.

Java
Kotlin

if (message.isSaved()) {
    Log.d(TAG, "Saved at " + message.getSavedAt());
}

if (message.isSaved) {
    Log.d(TAG, "Saved at ${message.savedAt}")
}

Real-time Save Events

Because saving is private, save events are never delivered to other participants. Register a MessageListener and override the save callbacks; each event delivers the full updated BaseMessage. Today these callbacks fire on the acting device when a save or unsave succeeds. Delivery to the user’s other devices activates once server-side real-time delivery for save events is rolled out — until then, other sessions pick up save changes on their next fetch.

Java
Kotlin

private String listenerID = "UNIQUE_LISTENER_ID";

CometChat.addMessageListener(listenerID, new CometChat.MessageListener() {
  @Override
  public void onMessageSaved(BaseMessage message) {
      Log.d(TAG, "Message saved: " + message.getId());
  }

  @Override
  public void onMessageUnsaved(BaseMessage message) {
      Log.d(TAG, "Message unsaved: " + message.getId());
  }
});

val listenerID = "UNIQUE_LISTENER_ID"

CometChat.addMessageListener(listenerID, object : CometChat.MessageListener() {
  override fun onMessageSaved(message: BaseMessage) {
      Log.d(TAG, "Message saved: ${message.id}")
  }

  override fun onMessageUnsaved(message: BaseMessage) {
      Log.d(TAG, "Message unsaved: ${message.id}")
  }
})

To stop listening, remove the listener with CometChat.removeMessageListener(listenerID).

Save Limit

A user can save a capped number of messages, configurable per app. Read the cap rather than hard-coding it — it is tenant-overridable and will drift.

Java
Kotlin

int limit = CometChat.getSaveMessageLimit();

if (limit != Settings.LIMIT_UNSPECIFIED && savedCount >= limit) {
    // Disable the save control instead of letting the user hit the error
}

val limit = CometChat.getSaveMessageLimit()

if (limit != Settings.LIMIT_UNSPECIFIED && savedCount >= limit) {
    // Disable the save control instead of letting the user hit the error
}

The call is synchronous and never throws. It returns Settings.LIMIT_UNSPECIFIED (-1) when the app settings carry no value or when it is called before init() completes — show generic copy in that case rather than guessing a number. Unlike pinning, saving has no separate system cap. When the limit is breached, the SDK surfaces the server error through onError, and the applicable limit is carried in the exception’s errorParams:

Java
Kotlin

@Override
public void onError(CometChatException e) {
    Object limit = e.getErrorParams() != null ? e.getErrorParams().get("limit") : null;
    if (limit != null) {
        Log.e(TAG, "You can save up to " + limit + " messages.");
    }
}

override fun onError(e: CometChatException?) {
    val limit = e?.errorParams?.get("limit")
    if (limit != null) {
        Log.e(TAG, "You can save up to $limit messages.")
    }
}

Error Handling

Error	Meaning
`ERR_SAVED_MESSAGES_LIMIT_EXCEEDED`	The user’s save cap was reached. The cap is in `errorParams["limit"]` when the server includes it.
`ERR_MESSAGE_NO_ACCESS`	The user cannot act on this message — either a genuine access refusal or a message still held by moderation (above).

Feature Availability

Check whether the Save Message feature is enabled for your app before showing save actions in your UI. The method is synchronous and safe to call from the UI layer.

Java
Kotlin

if (CometChat.isSaveMessageEnabled()) {
    // show the Save option
}

if (CometChat.isSaveMessageEnabled()) {
    // show the Save option
}

Next Steps

Pin A Message

Highlight a message for everyone in the conversation

Pin A Conversation

Pin a conversation to the top of the list

All Real Time Listeners

Every listener the SDK exposes, in one place

Additional Message Filtering

Filter messages by pinned, saved, type, tags and more

​Save a Message

​Unsave a Message

​Fetch Saved Messages

​Check if a Message is Saved

​Real-time Save Events

​Save Limit

​Error Handling

​Feature Availability

​Next Steps

Pin A Message

Pin A Conversation

All Real Time Listeners

Additional Message Filtering

Save a Message

Unsave a Message

Fetch Saved Messages

Check if a Message is Saved

Real-time Save Events

Save Limit

Error Handling

Feature Availability

Next Steps