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.
90 lines
3.5 KiB
ReStructuredText
90 lines
3.5 KiB
ReStructuredText
Presence
|
|
========
|
|
|
|
Each user has presence information associated with them. This encodes the
|
|
"availability" of that user, suitable for display on other clients.
|
|
This is transmitted as an ``m.presence`` event and is one of the few events
|
|
which are sent *outside the context of a room*. Their 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.
|
|
- ``free_for_chat`` : The user is generally willing to receive messages
|
|
moreso than default.
|
|
|
|
Events
|
|
------
|
|
|
|
{{presence_events}}
|
|
|
|
Client behaviour
|
|
----------------
|
|
|
|
Clients can manually set/get their presence using the HTTP APIs listed below.
|
|
|
|
{{presence_http_api}}
|
|
|
|
Idle timeout
|
|
~~~~~~~~~~~~
|
|
|
|
Clients SHOULD implement an "idle timeout". This is a timer which fires after
|
|
a period of inactivity on the client. The definition of inactivity varies
|
|
depending on the client. For example, web implementations may determine
|
|
inactivity to be not moving the mouse for a certain period of time. When this
|
|
timer fires it should set the presence state to ``unavailable``. When the user
|
|
becomes active again (e.g. by moving the mouse) the client should set the
|
|
presence state to ``online``. A timeout value between 1 and 5 minutes is
|
|
recommended.
|
|
|
|
Server behaviour
|
|
----------------
|
|
|
|
Propagating profile information
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Because the profile display name and avatar information are likely to be used in
|
|
many places of a client's display, changes to these fields SHOULD cause an
|
|
automatic propagation event to occur, informing likely-interested parties of the
|
|
new values. One of these change mechanisms SHOULD be via ``m.presence`` events.
|
|
These events should set ``displayname`` and ``avatar_url`` to the new values
|
|
along with the presence-specific keys. This SHOULD be done automatically by the
|
|
home server when a user successfully changes their display name or avatar URL.
|
|
|
|
.. admonition:: Rationale
|
|
|
|
The intention for sending this information in ``m.presence`` is so that any
|
|
"user list" can display the *current* name/presence for a user ID outside the
|
|
scope of a room (e.g. a user page which has a "start conversation" button).
|
|
This is bundled into a single event to avoid "flickering" on this page which
|
|
can occur if you received presence first and then display name later (the
|
|
user's name would flicker from their user ID to the display name).
|
|
|
|
|
|
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 a higher level of availability. Levels of
|
|
availability are defined from low to high as follows:
|
|
|
|
- ``offline``
|
|
- ``unavailable``
|
|
- ``online``
|
|
- ``free_for_chat``
|
|
|
|
Based on this list, changing state from ``unavailable`` to ``online`` counts as
|
|
a pro-active event, whereas ``online`` to ``unavailable`` does not. This
|
|
timestamp is presented via a key called ``last_active_ago`` which gives the
|
|
relative number of milliseconds since the pro-active event.
|
|
|
|
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.
|
|
|