Presence
========

.. _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. This is one of the few events which
are sent *outside the context of a room*. Presence events are sent to all users
who subscribe to this user's presence through a presence list or by sharing
membership of a room.

A presence list is a list of user IDs whose presence the user wants to follow.
To be added to this list, the user being added must be invited by the list owner
who must accept the invitation.

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
------

{{presence_events}}

Client behaviour
----------------

Clients can manually set/get their presence/presence list using the HTTP APIs
listed below.

{{presence_http_api}}

Server behaviour
----------------

Each user's homeserver stores a "presence list" per user. Once a user accepts
a presence list, both user's HSes must track the subscription.

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 to
disable as opposed to disabling last active tracking. 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 users presence to ``unavailable`` if their
last active time was over 5 minutes ago. Clients can manually set a users
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.