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-proposals/specification/modules/room_previews.rst

45 lines
1.7 KiB
ReStructuredText

Room Previews
=============
.. _module:room-previews:
It is sometimes desirable to offer a preview of a room, where a user can "lurk"
and read messages posted to the room, without joining the room. This can be
particularly effective when combined with `Guest Access`_.
Previews are implemented via the ``world_readable`` `Room History Visibility`_.
setting, along with a special version of the
`GET /events <#get-matrix-client-%CLIENT_MAJOR_VERSION%-events>`_ endpoint.
Client behaviour
----------------
A client wishing to view a room without joining it should call
`GET /rooms/:room_id/initialSync <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-initialsync>`_,
followed by `GET /events`__. Clients will need to do this
in parallel for each room they wish to view.
__ `peeking_events_api`_
Clients can of course also call other endpoints such as
`GET /rooms/:room_id/messages <#get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-messages>`_
and `GET /search <#get-matrix-client-%CLIENT_MAJOR_VERSION%-search>`_ to access
events outside the ``/events`` stream.
.. _peeking_events_api:
{{peeking_events_cs_http_api}}
Server behaviour
----------------
For clients which have not joined a room, servers are required to only return
events where the room state at the event had the ``m.room.history_visibility``
state event present with ``history_visibility`` value ``world_readable``.
Security considerations
-----------------------
Clients may wish to display to their users that rooms which are
``world_readable`` *may* be showing messages to non-joined users. There is no
way using this module to find out whether any non-joined guest users *do* see
events in the room, or to list or count any lurking users.