> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Show Cached Data

> Render cached messages, conversations, and lists instantly and reconcile them against the server with the CometChat iOS SDK.

> [accordion] AI Integration Quick Reference
>
> ```swift theme={null}
> // Every read fires up to two phases: cached first (instant), then server.
> let request = MessagesRequest.MessageRequestBuilder()
>     .set(uid: "UID")
>     .set(limit: 30)
>     .build()
>
> request.fetchPrevious(onCachedMessages: { messages in
>     // Phase 1: local cache. Fires first, even when empty. Render immediately.
> }, onServerMessages: { messages in
>     // Phase 2: server. Replaces the same slice — reconcile, don't append. Never fires offline.
> }, onError: { error in
>     // Offline ends here, after the cached page, with ERROR_INTERNET_UNAVAILABLE.
> })
>
> // Single items (additive two-phase overloads)
> CometChat.getConversation(conversationWith: "UID", conversationType: .user, listener: conversationDetailsListener)
> CometChat.getMessageDetails(messageId, listener: messageDetailsListener)
> ```

With offline support enabled, every list and lookup the SDK already offers answers from the on-device cache first and then from the server. Your UI paints instantly from the cache, then reconciles when the server replies. This page describes that contract, the reads it applies to, and how to merge the two phases.

## The two-phase contract

Each read fires **up to two** callbacks, always in this order:

**1. Cached phase**

The SDK delivers a page from the local cache **first**. It fires **even when the page is empty** — an empty cached page is indistinguishable from a cache miss, by design. Render it right away.

**2. Server phase**

After a successful server response, the SDK delivers the server's copy for the **same slice** and writes it through to the cache before the callback. Reconcile your displayed list against it.

Two rules follow from this:

* **Offline, the read ends with an error.** After the cached page, a read that gets no answer because the device is offline settles with `onError`, code `ERROR_INTERNET_UNAVAILABLE`. A real server error reaches `onError` unchanged. The call always settles, as long as you wait for each fetch to return before starting the next one on the same request object.
* **The server phase never fires offline.** It fires only on a genuine server response. Never treat a cached page as "end of history"; an empty cached page only means the end of the *cached* window.

All callbacks are delivered on the main thread.

> [!NOTE]
>
> With offline support **off**, these overloads behave like the classic call: the cached phase never fires, and the server result arrives in `onServer…` instead of `onSuccess`. Nothing changes until you enable offline (see [Enable Offline Support](https://www.cometchat.com/docs/sdk/ios/offline-enable.md)). Requires SDK **4.2.0** or later.

> [!NOTE]
>
> Run one fetch at a time on a request object. A second fetch while the previous one is still in flight fires no cached phase. On `MessagesRequest`, `ThreadsRequest` and `ReactionsRequest` it fails with `ERROR_REQUEST_IN_PROGRESS`. On the user, group, group-member and banned-member lists it returns an empty server result. Wait for the first fetch to finish, or create a new request.

## Read messages

`MessagesRequest` supports both directions. `fetchPrevious` pages toward older messages; `fetchNext` pages toward newer ones. Both have a two-phase overload.

```swift theme={null}
let request = MessagesRequest.MessageRequestBuilder()
    .set(uid: "UID")
    .set(limit: 30)
    .build()

request.fetchPrevious(onCachedMessages: { messages in
    // Render the cached page immediately.
}, onServerMessages: { messages in
    // Reconcile this slice against the cached page, keyed by message id.
}, onError: { error in
    print("Fetch failed: \(error?.errorCode ?? "")")
})
```

The classic `fetchPrevious(onSuccess:onError:)` and `fetchNext(onSuccess:onError:)` are unchanged and never deliver a cached result.

## Read conversations

`ConversationRequest` pages in one direction with `fetchNext`.

```swift theme={null}
let request = ConversationRequest.ConversationRequestBuilder(limit: 30).build()

request.fetchNext(onCachedConversations: { conversations in
    // Render the cached list immediately.
}, onServerConversations: { conversations in
    // Reconcile, keyed by conversation id.
}, onError: { error in
    print("Fetch failed: \(error?.errorCode ?? "")")
})
```

## Read the other lists

Every remaining list read gains the same two-phase overload, with `onCached…` / `onServer…` closures of the matching type plus `onError`.

| Request | Fetch method(s) | Cached / server closure labels |
| - | - | - |
| `MessagesRequest` | `fetchPrevious`, `fetchNext` | `onCachedMessages` / `onServerMessages` |
| `ConversationRequest` | `fetchNext` | `onCachedConversations` / `onServerConversations` |
| `ThreadsRequest` | `fetchNext` | `onCachedThreads` / `onServerThreads` |
| `UsersRequest` | `fetchNext` | `onCachedUsers` / `onServerUsers` |
| `BlockedUserRequest` | `fetchNext` | `onCachedUsers` / `onServerUsers` |
| `GroupsRequest` | `fetchNext` | `onCachedGroups` / `onServerGroups` |
| `GroupMembersRequest` | `fetchNext` | `onCachedGroupMembers` / `onServerGroupMembers` |
| `BannedGroupMembersRequest` | `fetchNext` | `onCachedBannedGroupMembers` / `onServerBannedGroupMembers` |
| `ReactionsRequest` | `fetchPrevious`, `fetchNext` | `onCachedReactions` / `onServerReactions` |
| `NotificationFeedRequest` | `fetchNext` | `onCachedNotificationFeedItems` / `onServerNotificationFeedItems` |

The call shape is identical to the conversations example above — swap the request and the closure labels.

```swift theme={null}
let request = UsersRequest.UsersRequestBuilder()
    .set(limit: 30)
    .build()

request.fetchNext(onCachedUsers: { users in
    // render
}, onServerUsers: { users in
    // reconcile, keyed by uid
}, onError: { error in
    print("Fetch failed: \(error?.errorCode ?? "")")
})
```

> [!NOTE]
>
> For `ReactionsRequest`, `fetchPrevious` and `fetchNext` are recorded and replayed independently — each direction keeps its own cached pages. Users, groups, members, banned members, reactions, and the notification feed are served from a per-request snapshot rather than a shared store: the cached phase replays what the server returned online for the **same builder settings**, so a list you never fetched online has an empty cached page. Per-builder details are in the [Configuration & API Reference](https://www.cometchat.com/docs/sdk/ios/offline-reference.md).

> [!NOTE]
>
> `BlockedUserRequest` is the exception: its cached page is the SDK's own blocked-users list, which the SDK refreshes on login and on each catch-up sync and updates when you call `blockUsers` or `unblockUsers`. The first cached page holds the whole list and later pages are empty.

## Read a single item

`getConversation` and `getMessageDetails` each add a two-phase overload. Unlike the list reads, the cached callback fires **only when the item is cached** — never with an empty or nil object. A cache miss goes straight to the server phase online, or straight to `onError` offline.

`getConversation` takes a `ConversationDetailsListener`; `getMessageDetails` takes a `MessageDetailsListener`.

```swift theme={null}
final class ConversationLoader: NSObject, ConversationDetailsListener {

    func onCachedConversation(_ conversation: Conversation) {
        // Fires only on a cache hit.
    }

    func onServerConversation(_ conversation: Conversation?) {
        // Server copy, written through before delivery.
    }

    func onError(_ error: CometChatException?) {
        print("Lookup failed: \(error?.errorCode ?? "")")
    }
}

let loader = ConversationLoader()
CometChat.getConversation(conversationWith: "UID", conversationType: .user, listener: loader)

final class MessageLoader: NSObject, MessageDetailsListener {

    func onCachedMessage(_ message: BaseMessage) {
        // Fires only on a cache hit.
    }

    func onServerMessage(_ message: BaseMessage?) {
        // Server copy.
    }

    func onError(_ error: CometChatException?) {
        print("Lookup failed: \(error?.errorCode ?? "")")
    }
}

let messageLoader = MessageLoader()
CometChat.getMessageDetails(messageId, listener: messageLoader)
```

> [!NOTE]
>
> The SDK holds the `ConversationDetailsListener` or `MessageDetailsListener` until the read ends, so you do not need to keep your own reference for a single lookup.

## Merge the two phases

The server phase **replaces the same slice** — it is a reconcile, not a second batch. Render the cached page straight away, then on the server phase diff it into your displayed list keyed by the item's stable id (message id, conversation id, uid, guid). Do not append the server page to the cached one.

> [!TIP]
>
> Key your list by id so the two phases merge cleanly: update items that changed, add new ones, and drop cached items the server slice omits. To page further back, issue the next `fetchPrevious` / `fetchNext` rather than treating the server phase as more pages.

## When the cached page is empty

The cache answers a read **only if every filter on it is locally computable**. A single server-only predicate makes the entire cached phase return an empty list — with no error and no warning — while the server phase still answers in full.

The most common server-only predicate is `set(searchKeyword:)`, which blanks the cached phase on every request. Other examples on `MessagesRequest` are `has(links:)`, `updatesOnly(onlyUpdates:)` and `setInteractionGoalCompletedOnly(_:)`. Reading one sender's messages in a group (`set(uid:)` together with `set(guid:)`) is also answered by the server only. On the entity lists, a keyword search or a presence filter (`UsersRequest.set(status:)`, `GroupMembersRequest.set(status:)`) is never snapshotted, so it has no cached phase either.

> [!WARNING]
>
> An offline-critical screen must use only cache-supported filters — one innocuous builder flag can silently disable the cached phase for a whole screen. The full per-builder matrix of what the cache answers lives in the [Configuration & API Reference](https://www.cometchat.com/docs/sdk/ios/offline-reference.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.