This is beta documentation for Stream Chat IOS SDK v5. For the latest stable version, see the latest version (v4) .

Offline Support

Offline support comes in 4 different aspects:

Connection Recovery
Events Recovery
Queue Offline Actions (optional, enabled by default)
Keeping the DB on disk (optional, enabled by default)

Connection Recovery

It is really important to make sure that the app properly reconnects after a downtime, independently of what was the cause of it. It can happen that you put the app in the background, you lost connection or maybe it was killed by yourself or the system.

We are listening to the app's lifecycle to make sure we perform the right set of actions to bring you up online as soon as possible.

Note that on the iOS simulator, the reconnection doesn't always work reliably. Please use a real iOS device when testing these flows.

Events Recovery

Whenever the app is not foregrounded and connected to the internet, there are likely other actions performed by other users. Especially in a Chat app, there are tons of events that can happen while you were offline.

To overcome this situation, we are fetching all the events that happened since the end of your last online session up until the moment you foreground the app, we are processing them and making sure the app accordingly reflects those.

This happens without you needing to do anything.

Queued Offline Actions

You may be in the subway, and you are trying to send a message, but suddenly your connection drops. We make sure that this action is queued, and sent whenever you come back online. Even if you/the system kills the app, we make sure the request is sent in your next session.

These are the actions that support offline queuing:

Send message
Edit message
Delete message
Save draft message
Add reaction
Delete reaction
Pin message
Unpin message

Keeping the DB on disk

By making sure that the DB stays on disk, we can guarantee that the data stays across sessions. This helps when it comes to perception. Having fewer loading states or blank pages is more engaging to the users.

Configuration

The following properties on ChatClientConfig control offline behavior:

Property	Type	Default	Description
`isLocalStorageEnabled`	`Bool`	`true`	Enables local database caching and offline request queuing.
`shouldFlushLocalStorageOnStart`	`Bool`	`false`	Resets the local cache on startup. Useful during migrations or when cache invalidation is needed.
`isAutomaticSyncOnReconnectEnabled`	`Bool`	`true`	Controls whether the SDK automatically syncs missed events and re-watches channels after reconnecting.
`queuedActionsMaxHoursThreshold`	`Int`	`12`	Maximum number of hours to keep queued offline requests. Requests older than this are discarded.
`staysConnectedInBackground`	`Bool`	`true`	Maintains the WebSocket connection while the app is in the background (up to 5 minutes).

Disabling offline storage

To disable local storage and offline request queuing:

var config = ChatClientConfig(apiKeyString: "<# Your API Key Here #>")
config.isLocalStorageEnabled = false

Changing the queued actions timeout

By default, queued offline requests are discarded after 12 hours. You can adjust this threshold:

var config = ChatClientConfig(apiKeyString: "<# Your API Key Here #>")
config.queuedActionsMaxHoursThreshold = 24

Disabling automatic sync on reconnect

If you want to control the sync process manually:

var config = ChatClientConfig(apiKeyString: "<# Your API Key Here #>")
config.isAutomaticSyncOnReconnectEnabled = false

Controllers

Channels State and Filtering