Merge branch 'master' of github.com:matrix-org/matrix-doc into erikj/disable_federation
Erik Johnston
9 years ago
commit
3b4c3522e6
@ -0,0 +1,77 @@
|
|||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server v1 Typing API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/api/v1
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
accessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The user_id or application service access_token
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
|
paths:
|
||||||
|
"/rooms/{roomId}/typing/{userId}":
|
||||||
|
put:
|
||||||
|
summary: Informs the server that the user has started or stopped typing.
|
||||||
|
description: |-
|
||||||
|
This tells the server that the user is typing for the next N
|
||||||
|
milliseconds where N is the value specified in the ``timeout`` key.
|
||||||
|
Alternatively, if ``typing`` is ``false``, it tells the server that the
|
||||||
|
user has stopped typing.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: userId
|
||||||
|
description: The user who has started to type.
|
||||||
|
required: true
|
||||||
|
x-example: "@alice:example.com"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room in which the user is typing.
|
||||||
|
required: true
|
||||||
|
x-example: "!wefh3sfukhs:example.com"
|
||||||
|
- in: body
|
||||||
|
name: typingState
|
||||||
|
description: The current typing state.
|
||||||
|
required: true
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: |-
|
||||||
|
{
|
||||||
|
"typing": true,
|
||||||
|
"timeout": 30000
|
||||||
|
}
|
||||||
|
properties:
|
||||||
|
typing:
|
||||||
|
type: boolean
|
||||||
|
description: |-
|
||||||
|
Whether the user is typing or not. If ``false``, the ``timeout``
|
||||||
|
key can be omitted.
|
||||||
|
timeout:
|
||||||
|
type: integer
|
||||||
|
description: The length of time in milliseconds to mark this user as typing.
|
||||||
|
required: ["typing"]
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The new typing state was set.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
schema:
|
||||||
|
type: object # empty json object
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/error.yaml"
|
||||||
|
|
||||||
@ -0,0 +1,68 @@
|
|||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server v1 Voice over IP API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/api/v1
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
accessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The user_id or application service access_token
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
|
paths:
|
||||||
|
"/turnServer":
|
||||||
|
get:
|
||||||
|
summary: Obtain TURN server credentials.
|
||||||
|
description: |-
|
||||||
|
This API provides credentials for the client to use when initiating
|
||||||
|
calls.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The TURN server credentials.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{
|
||||||
|
"username":"1443779631:@user:example.com",
|
||||||
|
"password":"JlKfBy1QwLrO20385QyAtEyIv0=",
|
||||||
|
"uris":[
|
||||||
|
"turn:turn.example.com:3478?transport=udp",
|
||||||
|
"turn:10.20.30.40:3478?transport=tcp",
|
||||||
|
"turns:10.20.30.40:443?transport=tcp"
|
||||||
|
],
|
||||||
|
"ttl":86400
|
||||||
|
}
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
properties:
|
||||||
|
username:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The username to use.
|
||||||
|
password:
|
||||||
|
type: string
|
||||||
|
description: |-
|
||||||
|
The password to use.
|
||||||
|
uris:
|
||||||
|
type: array
|
||||||
|
items:
|
||||||
|
type: string
|
||||||
|
description: A list of TURN URIs
|
||||||
|
ttl:
|
||||||
|
type: integer
|
||||||
|
description: The time-to-live in seconds
|
||||||
|
required: ["username", "password", "uris", "ttl"]
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/error.yaml"
|
||||||
|
|
||||||
@ -0,0 +1,68 @@
|
|||||||
|
swagger: '2.0'
|
||||||
|
info:
|
||||||
|
title: "Matrix Client-Server v2 Receipts API"
|
||||||
|
version: "1.0.0"
|
||||||
|
host: localhost:8008
|
||||||
|
schemes:
|
||||||
|
- https
|
||||||
|
- http
|
||||||
|
basePath: /_matrix/client/v2_alpha
|
||||||
|
consumes:
|
||||||
|
- application/json
|
||||||
|
produces:
|
||||||
|
- application/json
|
||||||
|
securityDefinitions:
|
||||||
|
accessToken:
|
||||||
|
type: apiKey
|
||||||
|
description: The user_id or application service access_token
|
||||||
|
name: access_token
|
||||||
|
in: query
|
||||||
|
paths:
|
||||||
|
"/rooms/{roomId}/receipt/{receiptType}/{eventId}":
|
||||||
|
post:
|
||||||
|
summary: Send a receipt for the given event ID.
|
||||||
|
description: |-
|
||||||
|
This API updates the marker for the given receipt type to the event ID
|
||||||
|
specified.
|
||||||
|
security:
|
||||||
|
- accessToken: []
|
||||||
|
parameters:
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: roomId
|
||||||
|
description: The room in which to send the event.
|
||||||
|
required: true
|
||||||
|
x-example: "!wefuh21ffskfuh345:example.com"
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: receiptType
|
||||||
|
description: The type of receipt to send.
|
||||||
|
required: true
|
||||||
|
x-example: "m.read"
|
||||||
|
enum: ["m.read"]
|
||||||
|
- in: path
|
||||||
|
type: string
|
||||||
|
name: eventId
|
||||||
|
description: The event ID to acknowledge up to.
|
||||||
|
required: true
|
||||||
|
x-example: "$1924376522eioj:example.com"
|
||||||
|
- in: body
|
||||||
|
description: |-
|
||||||
|
Extra receipt information to attach to ``content`` if any. The
|
||||||
|
server will automatically set the ``ts`` field.
|
||||||
|
schema:
|
||||||
|
type: object
|
||||||
|
example: |-
|
||||||
|
{}
|
||||||
|
responses:
|
||||||
|
200:
|
||||||
|
description: The receipt was sent.
|
||||||
|
examples:
|
||||||
|
application/json: |-
|
||||||
|
{}
|
||||||
|
schema:
|
||||||
|
type: object # empty json object
|
||||||
|
429:
|
||||||
|
description: This request was rate-limited.
|
||||||
|
schema:
|
||||||
|
"$ref": "definitions/error.yaml"
|
||||||
@ -0,0 +1,7 @@
|
|||||||
|
{
|
||||||
|
"type": "m.typing",
|
||||||
|
"room_id": "!z0mnsuiwhifuhwwfw:matrix.org",
|
||||||
|
"content": {
|
||||||
|
"user_ids": ["@alice:matrix.org", "@bob:example.com"]
|
||||||
|
}
|
||||||
|
}
|
||||||
@ -0,0 +1,28 @@
|
|||||||
|
{
|
||||||
|
"type": "object",
|
||||||
|
"title": "Typing Event",
|
||||||
|
"description": "Informs the client of the list of users currently typing.",
|
||||||
|
"properties": {
|
||||||
|
"content": {
|
||||||
|
"type": "object",
|
||||||
|
"properties": {
|
||||||
|
"user_ids": {
|
||||||
|
"type": "array",
|
||||||
|
"items": {
|
||||||
|
"type": "string"
|
||||||
|
},
|
||||||
|
"description": "The list of user IDs typing in this room, if any."
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["user_ids"]
|
||||||
|
},
|
||||||
|
"type": {
|
||||||
|
"type": "string",
|
||||||
|
"enum": ["m.typing"]
|
||||||
|
},
|
||||||
|
"room_id": {
|
||||||
|
"type": "string"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"required": ["type", "room_id", "content"]
|
||||||
|
}
|
||||||
@ -1,3 +1,93 @@
|
|||||||
Feature Profiles
|
Feature Profiles
|
||||||
================
|
================
|
||||||
|
|
||||||
|
.. sect:feature-profiles:
|
||||||
|
|
||||||
|
Matrix supports many different kinds of clients: from embedded IoT devices to
|
||||||
|
desktop clients. Not all clients can provide the same feature sets as other
|
||||||
|
clients e.g. due to lack of physical hardware such as not having a screen.
|
||||||
|
Clients can fall into one of several profiles and each profile contains a set
|
||||||
|
of features that the client MUST support. This section details a set of
|
||||||
|
"feature profiles". Clients are expected to implement a profile in its entirety
|
||||||
|
in order for it to be classified as that profile.
|
||||||
|
|
||||||
|
Summary
|
||||||
|
-------
|
||||||
|
|
||||||
|
===================================== ========== ========== ========== ========== ==========
|
||||||
|
Module / Profile Web Mobile Desktop CLI Embedded
|
||||||
|
===================================== ========== ========== ========== ========== ==========
|
||||||
|
`Instant Messaging`_ Required Required Required Required Optional
|
||||||
|
`Presence`_ Required Required Required Required Optional
|
||||||
|
`Push Notifications`_ Optional Required Optional Optional Optional
|
||||||
|
`Receipts`_ Required Required Required Required Optional
|
||||||
|
`Typing Notifications`_ Required Required Required Required Optional
|
||||||
|
`VoIP`_ Required Required Required Optional Optional
|
||||||
|
`Content Repository`_ Required Required Required Optional Optional
|
||||||
|
`Managing History Visibility`_ Required Required Required Required Optional
|
||||||
|
`End-to-End Encryption`_ Optional Optional Optional Optional Optional
|
||||||
|
===================================== ========== ========== ========== ========== ==========
|
||||||
|
|
||||||
|
*Please see each module for more details on what clients need to implement.*
|
||||||
|
|
||||||
|
.. _End-to-End Encryption: `module:e2e`_
|
||||||
|
.. _Instant Messaging: `module:im`_
|
||||||
|
.. _Presence: `module:presence`_
|
||||||
|
.. _Push Notifications: `module:push`_
|
||||||
|
.. _Receipts: `module:receipts`_
|
||||||
|
.. _Typing Notifications: `module:typing`_
|
||||||
|
.. _VoIP: `module:voip`_
|
||||||
|
.. _Content Repository: `module:content`_
|
||||||
|
.. _Managing History Visibility: `module:history-visibility`_
|
||||||
|
|
||||||
|
Clients
|
||||||
|
-------
|
||||||
|
|
||||||
|
Stand-alone web (``Web``)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is a web page which heavily uses Matrix for communication. Single-page web
|
||||||
|
apps would be classified as a stand-alone web client, as would multi-page web
|
||||||
|
apps which use Matrix on nearly every page.
|
||||||
|
|
||||||
|
Mobile (``Mobile``)
|
||||||
|
~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is a Matrix client specifically designed for consumption on mobile devices.
|
||||||
|
This is typically a mobile app but need not be so provided the feature set can
|
||||||
|
be reached (e.g. if a mobile site could display push notifications it could be
|
||||||
|
classified as a mobile client).
|
||||||
|
|
||||||
|
Desktop (``Desktop``)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is a native GUI application which can run in its own environment outside a
|
||||||
|
browser.
|
||||||
|
|
||||||
|
Command Line Interface (``CLI``)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is a client which is used via a text-based terminal.
|
||||||
|
|
||||||
|
Embedded (``Embedded``)
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
This is a client which is embedded into another application or an embedded
|
||||||
|
device.
|
||||||
|
|
||||||
|
Application
|
||||||
|
+++++++++++
|
||||||
|
|
||||||
|
This is a Matrix client which is embedded in another website, e.g. using
|
||||||
|
iframes. These embedded clients are typically for a single purpose
|
||||||
|
related to the website in question, and are not intended to be fully-fledged
|
||||||
|
communication apps.
|
||||||
|
|
||||||
|
Device
|
||||||
|
++++++
|
||||||
|
|
||||||
|
This is a client which is typically running on an embedded device such as a
|
||||||
|
kettle, fridge or car. These clients tend to perform a few operations and run
|
||||||
|
in a resource constrained environment. Like embedded applications, they are
|
||||||
|
not intended to be fully-fledged communication systems.
|
||||||
|
|
||||||
|
|||||||
@ -0,0 +1,56 @@
|
|||||||
|
Module Heading
|
||||||
|
==============
|
||||||
|
|
||||||
|
.. _module:short-name:
|
||||||
|
|
||||||
|
A short summary of the module. What features does this module provide? An anchor
|
||||||
|
should be specified at the top of the module using the format ``module:name``.
|
||||||
|
|
||||||
|
Complicated modules may wish to have architecture diagrams or event flows
|
||||||
|
(e.g. VoIP call flows) here. Custom subsections can be included but they should
|
||||||
|
be used *sparingly* to reduce the risk of putting client or server behaviour
|
||||||
|
information in these custom sections.
|
||||||
|
|
||||||
|
Events
|
||||||
|
------
|
||||||
|
List the new event types introduced by this module, if any. If there are no
|
||||||
|
new events, this section can be omitted. Event types should be done as
|
||||||
|
subsections. This section is intended to document the "common shared event
|
||||||
|
structure" between client and server. Deviations from this shared structure
|
||||||
|
should be documented in the relevant behaviour section.
|
||||||
|
|
||||||
|
``m.example.event.type``
|
||||||
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
There should be JSON Schema docs for this event. Once there is JSON schema,
|
||||||
|
there will be a template variable with dots in the event type replaced with
|
||||||
|
underscores and the suffix ``_event``. You can insert a template like so:
|
||||||
|
|
||||||
|
{{m_example_event_type_event}}
|
||||||
|
|
||||||
|
Client behaviour
|
||||||
|
----------------
|
||||||
|
List any new HTTP endpoints. These endpoints should be documented using Swagger.
|
||||||
|
Once there is Swagger, there will be a template variable based on the name of
|
||||||
|
the YAML file with the suffix ``_http_api``. You can insert a template for
|
||||||
|
swagger docs like so:
|
||||||
|
|
||||||
|
{{name-of-yaml-file-without-file-ext_http_api}}
|
||||||
|
|
||||||
|
List the steps the client needs to take to
|
||||||
|
correctly process this module. List what data structures the client should be
|
||||||
|
storing in order to aid implementation.
|
||||||
|
|
||||||
|
Server behaviour
|
||||||
|
----------------
|
||||||
|
Does the server need to handle any of the new events in a special way (e.g.
|
||||||
|
typing timeouts, presence). Advice on how to persist events and/or requests are
|
||||||
|
recommended to aid implementation. Federation-specific logic should be included
|
||||||
|
here.
|
||||||
|
|
||||||
|
Security considerations
|
||||||
|
-----------------------
|
||||||
|
This includes privacy leaks: for example leaking presence info. How do
|
||||||
|
misbehaving clients or servers impact this module? This section should always be
|
||||||
|
included, if only to say "we've thought about it but there isn't anything to do
|
||||||
|
here".
|
||||||
|
|
||||||
@ -1,63 +1,112 @@
|
|||||||
Presence
|
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.
|
||||||
|
|
||||||
Each user has the concept of presence information. This encodes the
|
User's presence state is represented by the ``presence`` key, which is an enum
|
||||||
"availability" of that user, suitable for display on other user's clients.
|
of one of the following:
|
||||||
This is transmitted as an ``m.presence`` event and is one of the few events
|
|
||||||
which are sent *outside the context of a room*. The basic piece of presence
|
|
||||||
information 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
|
- ``online`` : The default state when the user is connected to an event
|
||||||
stream.
|
stream.
|
||||||
- ``unavailable`` : The user is not reachable at this time.
|
- ``unavailable`` : The user is not reachable at this time e.g. they are
|
||||||
- ``offline`` : The user is not connected to an event stream.
|
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
|
- ``free_for_chat`` : The user is generally willing to receive messages
|
||||||
moreso than default.
|
moreso than default.
|
||||||
- ``hidden`` : Behaves as offline, but allows the user to see the client
|
|
||||||
state anyway and generally interact with client features. (Not yet
|
|
||||||
implemented in synapse).
|
|
||||||
|
|
||||||
In addition, the server maintains a timestamp of the last time it saw a
|
|
||||||
pro-active event from the user; either sending a message to a room, or
|
|
||||||
changing presence state from a lower to a higher level of availability
|
|
||||||
(thus: changing state from ``unavailable`` to ``online`` counts as a
|
|
||||||
proactive event, whereas in the other direction it will not). This timestamp
|
|
||||||
is presented via a key called ``last_active_ago``, which gives the relative
|
|
||||||
number of milliseconds since the message is generated/emitted that the user
|
|
||||||
was last seen active.
|
|
||||||
|
|
||||||
Events
|
Events
|
||||||
------
|
------
|
||||||
|
|
||||||
{{presence_events}}
|
{{presence_events}}
|
||||||
|
|
||||||
Presence HTTP API
|
Client behaviour
|
||||||
-----------------
|
----------------
|
||||||
.. TODO-spec
|
|
||||||
- Define how users receive presence invites, and how they accept/decline them
|
Clients can manually set/get their presence/presence list using the HTTP APIs
|
||||||
|
listed below.
|
||||||
|
|
||||||
{{presence_http_api}}
|
{{presence_http_api}}
|
||||||
|
|
||||||
|
|
||||||
Events on Change of Profile Information
|
Idle timeout
|
||||||
---------------------------------------
|
~~~~~~~~~~~~
|
||||||
Because the profile displayname and avatar information are likely to be used in
|
|
||||||
many places of a client's display, changes to these fields cause an automatic
|
Clients SHOULD implement an "idle timeout". This is a timer which fires after
|
||||||
propagation event to occur, informing likely-interested parties of the new
|
a period of inactivity on the client. The definition of inactivity varies
|
||||||
values. This change is conveyed using two separate mechanisms:
|
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
|
||||||
- a ``m.room.member`` event is sent to every room the user is a member of,
|
timer fires it should set the presence state to ``unavailable``. When the user
|
||||||
to update the ``displayname`` and ``avatar_url``.
|
becomes active again (e.g. by moving the mouse) the client should set the
|
||||||
- a ``m.presence`` presence status update is sent, again containing the new values of the
|
presence state to ``online``. A timeout value between 1 and 5 minutes is
|
||||||
``displayname`` and ``avatar_url`` keys, in addition to the required
|
recommended.
|
||||||
``presence`` key containing the current presence state of the user.
|
|
||||||
|
Server behaviour
|
||||||
Both of these should be done automatically by the home server when a user
|
----------------
|
||||||
successfully changes their displayname or avatar URL fields.
|
|
||||||
|
Each user's home server stores a "presence list" per user. Once a user accepts
|
||||||
Additionally, when home servers emit room membership events for their own
|
a presence list, both user's HSes must track the subscription.
|
||||||
users, they should include the displayname and avatar URL fields in these
|
|
||||||
events so that clients already have these details to hand, and do not have to
|
Propagating profile information
|
||||||
perform extra roundtrips to query it.
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
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. for a user page. This is bundled into a single event for
|
||||||
|
several reasons. The user's display name can change per room. This
|
||||||
|
event provides the "canonical" name for the user. In addition, the name is
|
||||||
|
bundled into a single event for the ease of client implementations. If this
|
||||||
|
was not done, the client would need to search all rooms for their own
|
||||||
|
membership event to pull out 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.
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue