diagrams
Mobile

Realtime Messaging App Flow

A realtime messaging app flow describes how two mobile clients exchange messages with low latency through a persistent server-side connection, including connection establishment, message delivery, delivery receipts, and reconnection after network interruptions.

diagram.mmd — sequence
Edit in Graphlet →
Realtime Messaging App Flow sequence diagram
About Source

A realtime messaging app flow describes how two mobile clients exchange messages with low latency through a persistent server-side connection, including connection establishment, message delivery, delivery receipts, and reconnection after network interruptions.

Unlike a traditional request-response API where the client must poll for new messages, a realtime chat system uses a persistent bidirectional connection — typically a WebSocket — that remains open for the duration of the user's session. This allows the server to push new messages to the client the instant they arrive, enabling the sub-second delivery latency users expect from chat applications.

When the app foregrounds, it authenticates with the messaging server by sending a handshake frame containing the user's access token. The server validates the token, associates the connection with the user ID, and confirms the connection is ready. The client then subscribes to the channels or conversation IDs it wants to receive events for.

When a user sends a message, the client emits a message:send event over the WebSocket with a locally generated client_id (a UUID the client creates to deduplicate retries). The server persists the message to the database, broadcasts it to all connected recipients for that conversation, and acknowledges the sender with the server-assigned message ID and timestamp. Recipients' clients display the incoming message and send a message:delivered receipt, which is forwarded back to the sender's client to show the double-check delivery indicator.

Mobile network interruptions are common: when the WebSocket connection drops, the client detects the closure via a timeout on a periodic ping frame or a close event. It then reconnects with exponential backoff and requests messages received since its last known timestamp to fill the gap.

For delivering notifications when the app is backgrounded, see Push Notification Flow. For authentication setup, see Mobile App Authentication.

Free online editor
Edit this diagram in Graphlet
Fork, modify, and export to SVG or PNG. No sign-up required.
Open in Graphlet →

Frequently asked questions

A realtime messaging app flow describes how two clients exchange messages with sub-second latency through a persistent bidirectional WebSocket connection, including authentication handshake, message delivery, delivery receipts, and gap-filling after a reconnect.
The sender emits a `message:send` event with a client-generated UUID. The server persists the message, broadcasts it to connected recipients, and acknowledges the sender with a server-assigned ID and timestamp. Each recipient's client sends a `message:delivered` receipt, which the server forwards back to the sender so a delivery indicator can be shown in the UI.
Use WebSockets while the app is in the foreground — they provide persistent low-latency delivery without polling overhead. Pair them with push notifications as a fallback for when the app is backgrounded or the WebSocket connection is lost, so users receive messages regardless of app state.
Not requesting missed messages since the last known timestamp on reconnect leaves gaps in conversation history. Using a sequential server-assigned ID without a client-generated `client_id` makes it impossible to deduplicate retried sends, causing duplicate messages. Failing to implement ping/pong heartbeats means broken connections are not detected until the next send attempt.
mermaid
sequenceDiagram participant SenderApp as Sender App participant Server as Messaging Server participant DB as Message DB participant RecipientApp as Recipient App SenderApp->>Server: WebSocket upgrade + auth token Server-->>Server: Validate token, map connection to user ID Server-->>SenderApp: Connection acknowledged RecipientApp->>Server: WebSocket upgrade + auth token Server-->>RecipientApp: Connection acknowledged SenderApp->>Server: subscribe {conversation_id} RecipientApp->>Server: subscribe {conversation_id} SenderApp->>Server: message:send {client_id, conversation_id, text} Server->>DB: Persist message with server_id and timestamp DB-->>Server: Stored Server-->>SenderApp: message:ack {server_id, timestamp} Server->>RecipientApp: message:incoming {server_id, text, sender, timestamp} RecipientApp-->>RecipientApp: Display message in conversation thread RecipientApp->>Server: message:delivered {server_id} Server->>SenderApp: message:delivered {server_id} SenderApp-->>SenderApp: Show delivery receipt indicator note">Note over SenderApp,Server: Network interruption SenderApp->>Server: Reconnect WebSocket with backoff SenderApp->>Server: GET /messages?since=last_timestamp Server-->>SenderApp: Missed messages during disconnection
Copied to clipboard