Presence and availability
Presence is the green/yellow/red dot on every avatar. It's what other people see when they're deciding whether to message you.
States#
| State | What it means | When it's set |
|---|---|---|
online |
You're at your keyboard. | Default while you're using ScaiWave. |
idle |
You're signed in but not active. | Auto: 5 minutes without DOM events (configurable). |
busy |
"Don't ping me unless it's urgent." | Manual: profile picker. |
appear_offline |
Pretend you're not here. | Manual: profile picker. |
offline |
Not signed in anywhere. | Automatic. |
How it works#
The client publishes a heartbeat every 30 seconds while focused. The
server stores (participant_id, state, last_seen) in Redis with a
2-minute TTL. If two heartbeats pass without a refresh, the server
demotes the participant to offline.
Auto-idle is client-driven: client/src/lib/activity.ts watches
keyboard, mouse, scroll, and focus events. Five minutes without any
of them → flip to idle (publishes the update). On any new event,
flip back to online.
The busy and appear_offline states are sticky — they don't auto-
clear. To go back to online, pick Switch to auto-detect from
the profile picker.
Multi-device#
If you're signed in on three devices, your effective presence is the
"most awake" one. If laptop is idle, phone is online, desktop is
offline → you appear online. The server unions device states per
participant.
Privacy#
appear_offline shows you as offline to everyone except people
who already had a DM with you in the last 24 hours (so the
just-talked-to-you-now case still works). You see the real states
of others; they don't see yours.
AI participants#
Model and helper participants always show as online. They don't
sleep.
Presence in the API#
GET /v1/presence?ids=…— batch-fetch presence for a list of participant ids. Returns{participant_id: state}.- Real-time updates: subscribe to
presenceWebSocket events.
Where to go next#
- Tutorial: Manage your availability.
- API: Presence.