matrix-spec-proposals/content/client-server-api/modules/presence.md

type
module

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.