Online status

Modern AI applications require agents to know when users are online, when they've fully disconnected, and how to handle users connected across multiple devices. Ably's Presence feature provides realtime online status with automatic lifecycle management, allowing agents to decide when to continue processing, when to wait for user input, and when to clean up resources. Presence detects which users and agents are currently connected to a session, distinguishes between a single device disconnecting and a user going completely offline, and enables responsive online/offline indicators.

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 the enter() 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:

// Client code
const channel = ably.channels.get("job-map-new");

// Enter presence with metadata about the user's device
await channel.presence.enter({
  device: "mobile",
  platform: "ios"
});

Similarly, an agent can enter presence to signal that it's online:

// Agent code
const channel = ably.channels.get("job-map-new");

// Enter presence with metadata about the agent
await channel.presence.enter({
  model: "gpt-4"
});

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 unique connectionId, 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:

// Client code (device 1: desktop browser)
const channel = ably.channels.get("job-map-new");
await channel.presence.enter({ device: "desktop" });

And then connects from their mobile app while still connected on desktop:

// Client code (device 2: mobile app)
const channel = ably.channels.get("job-map-new");
await channel.presence.enter({ device: "mobile" });

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:

// Query presence to see both devices
const members = await channel.presence.get();
for (const { clientId, connectionId, data } of members) {
  console.log(clientId, connectionId, data);
}
// Example output:
// user-123 hd67s4!abcdef-0 { device: "desktop" }
// user-123 hd67s4!ghijkl-1 { device: "mobile" }

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 the leave() 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:

// Client code
const channel = ably.channels.get("job-map-new");

// Leave presence when the user marks themselves offline
await channel.presence.leave();

Similarly, an agent can leave presence when it completes its work or shuts down:

// Agent code
const channel = ably.channels.get("job-map-new");

// Leave presence when the agent shuts down
await channel.presence.leave();

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:

// Leave with a reason
await channel.presence.leave({
  reason: "session-completed",
  timestamp: Date.now()
});

Subscribers receive the leave data in the presence message:

// Subscribe to leave events to see why members left
await channel.presence.subscribe("leave", (presenceMessage) => {
  console.log(`${presenceMessage.clientId} left`);
  if (presenceMessage.data) {
    console.log(`Reason: ${presenceMessage.data.reason}`);
  }
});

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 the transportParams 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:

// Agent code
const ably = new Ably.Realtime({
  key: "demokey:*****",
  clientId: "weather-agent",
  // Allow 30 seconds for agent resume and reconnection
  transportParams: {
    remainPresentFor: 30000
  }
});

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

Use presence.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.

// Get all currently present members
const members = await channel.presence.get();

// Display each member - the same user will appear once per distinct connection
members.forEach((member) => {
  console.log(`${member.clientId} (connection: ${member.connectionId})`);
});

Subscribing to presence changes

Use presence.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.

// Client code
const channel = ably.channels.get("job-map-new");

// Subscribe to changes to the presence set
await channel.presence.subscribe(async (presenceMessage) => {
  // Get the current synced presence set after any change
  const members = await channel.presence.get();

  // Display each member - the same user will appear once per distinct connection
  members.forEach((member) => {
    console.log(`${member.clientId} (connection: ${member.connectionId})`);
  });
});

You can also subscribe to specific presence events:

// Subscribe only to enter events
await channel.presence.subscribe("enter", (presenceMessage) => {
  console.log(`${presenceMessage.clientId} joined on connection ${presenceMessage.connectionId}`);
});

// Subscribe only to leave events
await channel.presence.subscribe("leave", (presenceMessage) => {
  console.log(`${presenceMessage.clientId} left on connection ${presenceMessage.connectionId}`);
});

Detecting when a user is offline on all devices

Agents can monitor presence changes to detect when a specific user has gone completely offline across all devices. This is useful for deciding whether to pause expensive operations, cancel ongoing work, deprioritize tasks, or schedule work for later.

// Agent code
const channel = ably.channels.get("job-map-new");

await channel.presence.subscribe(async (presenceMessage) => {
  // Get the current synced presence set
  const members = await channel.presence.get();

  // Check if all clients are offline
  if (members.length === 0) {
    console.log(`All clients are offline`);
  }

  // Check if a specific client is offline
  if (!members.map(m => m.clientId).includes(targetUserId)) {
    console.log(`${targetUserId} is now offline on all devices`);
  }
});