matrix-spec-proposals/specification/modules/room_previews.rst

.. Copyright 2016 OpenMarket Ltd
..
.. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with the License.
.. You may obtain a copy of the License at
..
..     http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS,
.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
.. See the License for the specific language governing permissions and
.. limitations under the License.

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.