> ## 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.

# Offline Support

> Understand how local caching, the send outbox, and reconnect catch-up keep chat working without a connection with the CometChat iOS SDK.

> [accordion] AI Integration Quick Reference
>
> ```swift theme={null}
> // Offline support is OFF by default. Turn it on at init (SDK 4.2.0 or later).
> let offlineConfig = OfflineConfig.Builder()
>     .setEnabled(true)
>     .build()
>
> let appSettings = AppSettings.AppSettingsBuilder()
>     .setRegion(region: "REGION")
>     .setOfflineConfig(offlineConfig)   // or OfflineConfig(enabled: true) for defaults
>     .build()
>
> CometChat.init(appId: "APP_ID", appSettings: appSettings, onSuccess: { _ in }, onError: { _ in })
>
> // Is offline support active right now for the logged-in user?
> let active = CometChat.isOfflineEnabled()   // Bool
> ```

Offline support keeps the logged-in user's conversations and messages on the device so your app can show them instantly, lets the user send messages while disconnected, and catches up automatically when the connection returns. It is **off by default** — nothing changes in your app until you enable it ([Enable Offline Support](https://www.cometchat.com/docs/sdk/ios/offline-enable.md)). This page explains the mental model; the other pages show the exact APIs.

> [!NOTE]
>
> Offline support ships in CometChat iOS SDK **4.2.0** or later.

## How it works

Three ideas carry the whole feature.

**1. Cache first, then server**

Every read goes through the local cache first. For list reads the SDK delivers the cached page immediately, even when it is empty. Single-item lookups (`getMessageDetails`, `getConversation`) deliver a cached result only when that item is already cached. The SDK then fetches from the server and delivers the fresh result. Your UI renders what is on the device without waiting for the network, then updates when the server responds. See [Show Cached Data](https://www.cometchat.com/docs/sdk/ios/offline-cached-data.md).

**2. A durable send outbox**

A message sent while offline is saved to a durable outbox and reported as pending instead of failing. It survives app restarts and is sent, in the order it was composed, when the connection returns. See [Send While Offline](https://www.cometchat.com/docs/sdk/ios/offline-send.md).

**3. Catch up on reconnect**

When the device reconnects, the SDK syncs the conversations and messages that changed while it was away and flushes the outbox, so the local cache matches the server again. See [Stay in Sync](https://www.cometchat.com/docs/sdk/ios/offline-sync.md).

```mermaid theme={null}
flowchart LR
    A[App read] --> B[(Local cache)]
    B -- cached result first --> A
    B --> C{Online?}
    C -- yes --> D[Server]
    D -- fresh result --> A
    C -- no --> E[onError:\nERROR_INTERNET_UNAVAILABLE]
    F[Send while offline] --> G[(Durable outbox)]
    G -- on reconnect --> D
```

## What changes in your app

With offline support enabled, reads fire **twice** and sends gain a pending stage. To receive these cached and pending results you call the new overloads of the calls you already use:

* Reads: `fetchNext` / `fetchPrevious` with `onCached…`, `onServer…` and `onError` closures, `getConversation(conversationWith:conversationType:listener:)` with a `ConversationDetailsListener`, and `getMessageDetails(_:listener:)` with a `MessageDetailsListener`.
* Sends: `sendTextMessage`, `sendMediaMessage`, `sendCustomMessage` and `sendInteractiveMessage` with `onMessagePending`, `onMessageSent` and `onError` closures.

The existing `onSuccess` / `onError` overloads are unchanged and keep working exactly as before: they receive only the server result, and a send through them is never queued. With offline support off, the new overloads behave like the classic ones: the cached and pending callbacks never fire and the server result arrives in `onServer…` / `onMessageSent`.

## One cache per user

The SDK keeps a single local cache for the user who is logged in.

* The cache survives app restarts while the same user stays logged in, so the data is there instantly on next launch.
* Logging out, a session expiring, or logging in as a **different** user deletes the cache, including any unsent messages still in the outbox, which are lost. You never clear it yourself — the SDK does it.

See [Stay in Sync](https://www.cometchat.com/docs/sdk/ios/offline-sync.md) for cache resets and logout behaviour.

## How much is kept

By default the cache is bounded by size, not age: it holds up to **100 conversations**, up to **500 messages per conversation**, around **250 MB** of cached content, and up to **500 MB** of cached media. Older entries are evicted first as these limits are reached. Unsent messages, saved messages and pinned rows are never evicted by these limits. Every limit is tunable — see the [Configuration & API Reference](https://www.cometchat.com/docs/sdk/ios/offline-reference.md).

## Next steps

> [card] [Enable Offline Support](https://www.cometchat.com/docs/sdk/ios/offline-enable.md)
>
> Turn it on and verify it is active.

> [card] [Show Cached Data](https://www.cometchat.com/docs/sdk/ios/offline-cached-data.md)
>
> The cached-first, server-next read contract.

> [card] [Send While Offline](https://www.cometchat.com/docs/sdk/ios/offline-send.md)
>
> The durable outbox and pending messages.

> [card] [Stay in Sync](https://www.cometchat.com/docs/sdk/ios/offline-sync.md)
>
> Reconnect catch-up, cache resets, logout.

> [card] [Media Caching](https://www.cometchat.com/docs/sdk/ios/offline-media-caching.md)
>
> Download and cache attachments for offline viewing.

> [card] [Encrypt the Cache](https://www.cometchat.com/docs/sdk/ios/offline-encryption.md)
>
> Encrypt the local database at rest.

> [card] [Configuration & API Reference](https://www.cometchat.com/docs/sdk/ios/offline-reference.md)
>
> Every option, method, listener, enum, and error.


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