Event Context

This API returns a number of events that happened just before and after the specified event. This allows clients to get the context surrounding an event.

Client behaviour

There is a single HTTP API for retrieving event context, documented below.

GET /_matrix/client/v3/rooms/{roomId}/context/{eventId}

This API returns a number of events that happened just before and after the specified event. This allows clients to get the context surrounding an event.

Note: This endpoint supports lazy-loading of room member events. See Lazy-loading room members for more information.
Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventId string Required: The event to get context around.
roomId string Required: The room to get events from.
query parameters
Name Type Description
filter string

A JSON RoomEventFilter to filter the returned events with. The filter is only applied to events_before, events_after, and state. It is not applied to the event itself. The filter may be applied before or/and after the limit parameter - whichever the homeserver prefers.

See Filtering for more information.
limit integer The maximum number of events to return. Default: 10.

Responses

Status Description
200 The events and state surrounding the requested event.

200 response

Name Type Description
end string A token that can be used to paginate forwards with.
event ClientEvent Details of the requested event.
events_after [ClientEvent] A list of room events that happened just after the requested event, in chronological order.
events_before [ClientEvent] A list of room events that happened just before the requested event, in reverse-chronological order.
start string A token that can be used to paginate backwards with.
state [ClientEvent] The state of the room at the last event returned.
ClientEvent
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. 
{
  "end": "t29-57_2_0_2",
  "event": {
    "content": {
      "body": "filename.jpg",
      "info": {
        "h": 398,
        "mimetype": "image/jpeg",
        "size": 31037,
        "w": 394
      },
      "msgtype": "m.image",
      "url": "mxc://example.org/JWEIFJgwEIhweiWJE"
    },
    "event_id": "$f3h4d129462ha:example.com",
    "origin_server_ts": 1432735824653,
    "room_id": "!636q39766251:example.com",
    "sender": "@example:example.org",
    "type": "m.room.message",
    "unsigned": {
      "age": 1234
    }
  },
  "events_after": [
    {
      "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": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "events_before": [
    {
      "content": {
        "body": "something-important.doc",
        "filename": "something-important.doc",
        "info": {
          "mimetype": "application/msword",
          "size": 46144
        },
        "msgtype": "m.file",
        "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "start": "t27-54_2_0_2",
  "state": [
    {
      "content": {
        "creator": "@example:example.org",
        "m.federate": true,
        "predecessor": {
          "event_id": "$something:example.org",
          "room_id": "!oldroom:example.org"
        },
        "room_version": "1"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "",
      "type": "m.room.create",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "membership": "join",
        "reason": "Looking for support"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "@alice:example.org",
      "type": "m.room.member",
      "unsigned": {
        "age": 1234
      }
    }
  ]
}

Security considerations

The server must only return results that the user has permission to see.