Skip to content
CCS Chat Docs

Presence

Presence tells you whether a user is online. A user’s app sends a heartbeat while it is open, and Chat reports a user as online as long as heartbeats keep arriving. There is no connection to keep and no status to set.

The heartbeat model

Section titled “The heartbeat model”

Presence is derived, not stored as a status. Chat records when it last heard from a user, and a user counts as online while that moment is recent.

  • Heartbeat. The app calls the heartbeat route about every 30 seconds while it is in the foreground. Your app schedules it. The SDK exposes chat.presence.heartbeat().
  • Online. A user with a heartbeat in the last 30 seconds is online. Anyone else is offline. Nothing has to disconnect for a user to go offline.
  • Going offline at once. On sign-out or when the tab closes, the app can call the offline route. The user is offline immediately.
  • Last seen. last_seen_at is the time of the last heartbeat. It is null for a user Chat has never heard from, and after an explicit offline.

Presence belongs to the tenant

Section titled “Presence belongs to the tenant”

Presence describes a person in a tenant, not in one application. The routes are tenant-level:

POST /api/v1/tenants/{tenant_id}/presence/heartbeat
POST /api/v1/tenants/{tenant_id}/presence/offline
GET  /api/v1/tenants/{tenant_id}/presence?user_ids=coach-ana,client-john

A heartbeat from the Fitness app and one from another application of the same tenant describe the same person. Presence routes are for users only. A machine token answers 403 principal_not_allowed.

The lookup returns user_id, status and last_seen_at per user. Ids that are not members of the tenant are dropped from the answer, so a caller cannot learn who exists.

Updates through realtime

Section titled “Updates through realtime”

Polling is optional. When a user goes from offline to online, or reports offline, Chat sends a presence.updated event to the user’s fellow members. It carries tenant_id, user_id and status. Delivery is best effort, so look statuses up again when your app opens. See Realtime.

How push uses presence

Section titled “How push uses presence”

Presence decides who gets a push. When a message arrives, Chat sends push only to recipients who are offline. A user whose app is open and sending heartbeats receives the message over realtime and no push. See Push notifications.

Presence is per account, not per conversation. A user who is online but reading another conversation gets no push for a new message in this one.

Section titled “Related guides”
Section titled “Related reference”