Why online status matters
In channel-oriented sessions, online status serves several critical purposes:- Session abandonment detection: Agents need to know when users have fully disconnected to decide whether to continue processing, pause work, or clean up resources. Presence provides reliable signals when all of a user’s devices have left the session.
- Multi-device coordination: A single user can connect from multiple devices simultaneously. Presence tracks each connection separately while maintaining stable identity across devices, allowing you to distinguish between “one device left” and “user completely offline”.
- Agent availability signaling: Clients need to know when agents are online and ready to process requests. Agents can enter presence to advertise availability and leave when they complete work or shut down.
- Collaborative session awareness: In sessions with multiple users, participants can see who else is currently present. This enables realtime collaboration features and helps users understand the current session context.
Going online
Use theenter() method to signal that a user or agent is online. When a client enters presence, they are added to the presence set and identified by their clientId. You can optionally include data when entering presence to communicate additional context.
You have flexibility in when to enter presence. For example, an agent might choose to appear as online only while processing a specific task, or remain present for the duration of the entire session. Users typically enter presence when they connect to a session and remain present until they disconnect.
For example, a user client can enter presence when joining a session:
Similarly, an agent can enter presence to signal that it’s online:
Going online from multiple devices
A single user can be present on a channel from multiple devices simultaneously. Ably tracks each connection separately using a uniqueconnectionId, while maintaining the same clientId across all connections.
When a user connects from multiple devices, each device enters presence independently. All connections share the same clientId but have different connectionId values.
For example, when the user connects from their desktop browser:
And then connects from their mobile app while still connected on desktop:
Both devices are now members of the presence set with the same clientId but different connectionId values. When you query the presence set, you’ll see two separate entries:
When either device leaves or disconnects, the other device remains in the presence set.
Going offline
Clients can go offline in two ways: explicitly by calling the leave method, or automatically when Ably detects a disconnection.Explicitly going offline
Use theleave() method when a user or agent wants to mark themselves as offline. This immediately notifies presence subscribers on the channel and removes the entry from the presence set, even if they remain connected to Ably.
For example, a user client can explicitly leave presence:
Similarly, an agent can leave presence when it completes its work or shuts down:
Optionally include data when leaving presence to communicate the reason for going offline. This data is delivered to presence subscribers listening to leave events and is also available in presence history:
Subscribers receive the leave data in the presence message:
Going offline after disconnection
When a client loses connection unexpectedly, Ably detects the lost connection and automatically leaves the client from the presence set. By default, clients remain present for 15 seconds after an abrupt disconnection. This prevents excessive enter/leave events during brief network interruptions. If the client reconnects within this window, they remain in the presence set without triggering leave and reenter events. Use thetransportParams client option to configure disconnection detection and presence lifecycle behaviour. After an abrupt disconnection, the heartbeatInterval transport parameter controls how quickly Ably detects the dead connection, while the remainPresentFor option controls how long the member is kept in presence before Ably emits the leave event.
For example, if implementing resumable agents using techniques such as durable execution, configure a longer remainPresentFor period to allow time for the new agent instance to come online and resume processing before the previous instance appears as offline. This provides a seamless handoff:
Viewing who is online
Participants in a session can query the current presence set or subscribe to presence events to see who else is online and react to changes in realtime. Users might want to see which agents are processing work, while agents might want to detect when specific users are offline to pause or cancel work.Retrieving current presence members
Usepresence.get() to retrieve the current list of users and agents in the session. Each presence member is uniquely identified by the combination of their clientId and connectionId. This is useful for showing who is currently available or checking if a specific participant is online before taking action.
Subscribing to presence changes
Usepresence.subscribe() to receive realtime notifications when users or agents enter or leave the session. This enables building responsive UIs that show online users, or implementing agent logic that reacts to user connectivity changes.
You can also subscribe to specific presence events: