Product · · 3 min read
Offline-First Chat: Sync Messages After Reconnect
Learn how offline-first chat queues messages locally, retries safely, detects sync gaps, and reconciles state after reconnecting.
An offline-first chat experience lets users keep reading and composing messages even when the network disappears. The goal is not to pretend the device is always online. The goal is to make temporary disconnection a normal state.
Offline-first chat
Why offline-first matters
Mobile connectivity changes constantly. A user can lose Wi-Fi, switch networks, enter poor coverage, or background the app. If the chat UI assumes a permanent connection, messages can become stuck or disappear.
A better flow is:
- The user writes a message.
- The app stores it locally.
- The UI shows it as pending.
- The app retries when connectivity returns.
- The server acknowledges it.
- The local record becomes canonical.
Start with a local message model
A useful local record contains a client message ID, conversation ID, sender ID, message body, local creation time, server sequence when known, delivery state, and retry count.
The client message ID should be generated before the network request. That ID stays unchanged through every retry.
Queue outgoing messages
Do not make the network request the only place a message exists. Persist the outgoing operation locally first.
Compose → Save locally → Add to outbox → Attempt delivery
If the request succeeds, remove the operation from the pending queue. If the device is offline, leave it there until a sync worker can retry it.
Retry with backoff
A reconnect can release many pending messages at once. Sending everything immediately can create a burst.
Use exponential backoff with jitter for failed requests. For example: 1 second, 2 seconds, 4 seconds, 8 seconds, then a capped delay.
Not every error should retry. Validation and permission errors need normal application handling.
Reconnect is a synchronization event
Opening a realtime connection does not prove that the conversation is synchronized. While the client was offline, other participants may have created new messages.
Track the last authoritative sequence the client has processed. If the client knows sequence 500 and the server has reached 507, it can request 501 through 507.
This is safer than simply asking for the latest page of messages.
Sync both directions
Offline synchronization has two jobs.
Outgoing
Messages created locally while offline must be uploaded safely.
Incoming
Messages created by other participants or devices must be downloaded.
A sync cycle can upload pending operations, fetch missing server messages, reconcile local records, update the last known sequence, and resume realtime subscriptions.
Avoid duplicate local and server messages
A common bug occurs when the local UI creates message A, the server accepts it as message B, and a realtime event for B arrives while A is still present.
The user sees the same message twice.
Keep the client message ID attached to the operation. When the canonical server record arrives, replace the optimistic local record instead of appending another message.
What about edits and deletes?
Offline edits are harder because the same message can change on multiple devices.
A simple product can start with offline message creation and add edits later. If edits are supported, use explicit versions or another server-authoritative conflict rule so an old offline edit cannot overwrite newer state.
Offline-first does not mean everything works offline
Offline-capable means the app can queue work and read cached data. Offline-complete means every feature behaves exactly as it does online.
You usually do not need the second model.
Start with reading recent conversations, composing messages, queueing sends, automatic retries, clear delivery states, and synchronization after reconnect.
For broader UI considerations, see How to Design a Realtime Chat UI on the ByoTalk blog.
A practical sync state machine
A simple client can use online, offline, syncing, and degraded states.
The important transition is:
offline → online → syncing → online
Do not declare the conversation fully synchronized just because a socket opened. First reconcile the state gap.
FAQ
How do I know what messages are missing?
Track the last authoritative sequence and request everything after it.
Can offline chat be built with WebSockets alone?
No. WebSockets handle a connection. Offline synchronization needs local persistence, retry logic, message identity, and a source of truth.
Should offline messages be stored locally until confirmed?
Yes. They should survive the app's normal lifecycle until the server confirms them, subject to platform and security requirements.
The practical rule
Treat connectivity as a variable, not a guarantee. Persist outgoing messages locally, give every operation a stable identity, retry safely, synchronize by sequence after reconnect, and reconcile optimistic UI with canonical server data.
Related ByoTalk guides
- chat-infrastructure
- realtime
- react-native
- byo-database
Build chat on ByoTalk
Realtime chat and calls, with the permanent record in your own database.