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

Client behaviour

A client wishing to view a room without joining it should call GET /rooms/:room_id/initialSync, followed by GET /events. Clients will need to do this in parallel for each room they wish to view.

Clients can of course also call other endpoints such as GET /rooms/:room_id/messages and GET /search to access events outside the /events stream.

GET /_matrix/client/v3/events

This will listen for new events related to a particular room and return them to the caller. This will block until an event is received, or until the timeout is reached.

This API is the same as the normal /events endpoint, but can be called by users who have not joined the room.

Note that the normal /events endpoint has been deprecated. This API will also be deprecated at some point, but its replacement is not yet known.

Rate-limited:	No
Requires authentication:	Yes

Request

Request parameters

query parameters
Name	Type	Description
`from`	`string`	The token to stream from. This token is either from a previous request to this API or from the initial sync API.
`room_id`	`string`	The room ID for which events should be returned.
`timeout`	`integer`	The maximum time in milliseconds to wait for an event.

Responses

Status	Description
`200`	The events received, which may be none.
`400`	Bad pagination `from` parameter.

200 response

Name	Type	Description
`chunk`	`[Event]`	An array of events.
`end`	`string`	A token which correlates to the last value in `chunk`. This token should be used in the next request to `/events`.
`start`	`string`	A token which correlates to the first value in `chunk`. This is usually the same token supplied to `from=`.

Event
Name	Type	Description
`content`	`object`	Required: The body of this event, as created by the client which sent it.
`event_id`	`string`	Required: The globally unique identifier for this event.
`origin_server_ts`	`integer`	Required: Timestamp (in milliseconds since the unix epoch) on originating homeserver when this event was sent.
`room_id`	`string`	Required: The ID of the room associated with this event.
`sender`	`string`	Required: Contains the fully-qualified ID of the user who sent this event.
`state_key`	`string`	Present if, and only if, this event is a state event. The key making this piece of state unique in the room. Note that it is often an empty string. State keys starting with an `@` are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
`type`	`string`	Required: The type of the event.
`unsigned`	`UnsignedData`	Contains optional extra information about the event.

UnsignedData
Name	Type	Description
`age`	`integer`	The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
`prev_content`	`EventContent`	The previous `content` for this event. This field is generated by the local homeserver, and is only returned if the event is a state event, and the client has permission to see the previous content. Changed in `v1.2`: Previously, this field was specified at the top level of returned events rather than in `unsigned` (with the exception of the `GET .../notifications` endpoint), though in practice no known server implementations honoured this.
`redacted_because`	`ClientEvent`	The event that redacted this event, if any.
`transaction_id`	`string`	The client-supplied transaction ID, for example, provided via `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`, if the client being given the event is the same one which sent it.

{
  "chunk": [
    {
      "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "<b>This is an example text message</b>",
        "msgtype": "m.text"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!somewhere:over.the.rainbow",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "end": "s3457_9_0",
  "start": "s3456_9_0"
}

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.