You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
matrix-spec/content/client-server-api/modules/presence.md

73 lines
2.9 KiB
Markdown

### Presence
Each user has the concept of presence information. This encodes:
- Whether the user is currently online
- How recently the user was last active (as seen by the server)
- Whether a given client considers the user to be currently idle
- Arbitrary information about the user's current status (e.g. "in a
meeting").
This information is collated from both per-device (`online`, `idle`,
`last_active`) and per-user (status) data, aggregated by the user's
homeserver and transmitted as an `m.presence` event. Presence events are
sent to interested parties where users share a room membership.
User's presence state is represented by the `presence` key, which is an
enum of one of the following:
- `online` : The default state when the user is connected to an event
stream.
- `unavailable` : The user is not reachable at this time e.g. they are
idle.
- `offline` : The user is not connected to an event stream or is
explicitly suppressing their profile information from being sent.
#### Events
{{% event-group group_name="m.presence" %}}
#### Client behaviour
Clients can manually set/get their presence using the HTTP APIs listed
below.
{{% http-api spec="client-server" api="presence" %}}
##### Last active ago
The server maintains a timestamp of the last time it saw a pro-active
event from the user. A pro-active event may be sending a message to a
room or changing presence state to `online`. This timestamp is presented
via a key called `last_active_ago` which gives the relative number of
milliseconds since the pro-active event.
To reduce the number of presence updates sent to clients the server may
include a `currently_active` boolean field when the presence state is
`online`. When true, the server will not send further updates to the
last active time until an update is sent to the client with either a)
`currently_active` set to false or b) a presence state other than
`online`. During this period clients must consider the user to be
currently active, irrespective of the last active time.
The last active time must be up to date whenever the server gives a
presence event to the client. The `currently_active` mechanism should
purely be used by servers to stop sending continuous presence updates,
as opposed to disabling last active tracking entirely. Thus clients can
fetch up to date last active times by explicitly requesting the presence
for a given user.
##### Idle timeout
The server will automatically set a user's presence to `unavailable` if
their last active time was over a threshold value (e.g. 5 minutes).
Clients can manually set a user's presence to `unavailable`. Any
activity that bumps the last active time on any of the user's clients
will cause the server to automatically set their presence to `online`.
#### Security considerations
Presence information is shared with all users who share a room with the
target user. In large public rooms this could be undesirable.