Skip to main content
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). This page explains the mental model; the other pages show the exact APIs.
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.
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.
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.

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

​
Next steps

Enable Offline Support

Turn it on and verify it is active.

Show Cached Data

The cached-first, server-next read contract.

Send While Offline

The durable outbox and pending messages.

Stay in Sync

Reconnect catch-up, cache resets, logout.

Media Caching

Download and cache attachments for offline viewing.

Encrypt the Cache

Encrypt the local database at rest.

Configuration & API Reference

Every option, method, listener, enum, and error.