matrix-spec/api/client-server/message_pagination.yaml

# 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.
swagger: '2.0'
info:
  title: "Matrix Client-Server Rooms API"
  version: "1.0.0"
host: localhost:8008
schemes:
  - https
  - http
basePath: /_matrix/client/%CLIENT_MAJOR_VERSION%
consumes:
  - application/json
produces:
  - application/json
securityDefinitions:
  $ref: definitions/security.yaml
paths:
  "/rooms/{roomId}/messages":
    get:
      summary: Get a list of events for this room
      description: |-
        This API returns a list of message and state events for a room. It uses
        pagination query parameters to paginate history in the room.
      operationId: getRoomEvents
      security:
        - accessToken: []
      parameters:
        - in: path
          type: string
          name: roomId
          description: The room to get events from.
          required: true
          x-example: "!636q39766251:example.com"
        - in: query
          type: string
          name: from
          description: |-
            The token to start returning events from. This token can be obtained
            from a ``prev_batch`` token returned for each room by the sync API,
            or from a ``start`` or ``end`` token returned by a previous request
            to this endpoint.
          required: true
          x-example: "s345_678_333"
        - in: query
          type: string
          name: to
          description: |-
            The token to stop returning events at. This token can be obtained from
            a ``prev_batch`` token returned for each room by the sync endpoint,
            or from a ``start`` or ``end`` token returned by a previous request to
            this endpoint.
          required: false
        - in: query
          type: string
          enum: ["b", "f"]
          name: dir
          description: |-
            The direction to return events from.
          required: true
          x-example: "b"
        - in: query
          type: integer
          name: limit
          description: |-
            The maximum number of events to return. Default: 10.
          x-example: "3"
        - in: query
          type: string
          name: filter
          description: |-
            A JSON RoomEventFilter to filter returned events with.
          x-example: |-
            {"contains_url":true}
      responses:
        200:
          description: A list of messages with a new token to request more.
          schema:
            type: object
            description: A list of messages with a new token to request more.
            properties:
              start:
                type: string
                description: |-
                  The token the pagination starts from. If ``dir=b`` this will be
                  the token supplied in ``from``.
              end:
                type: string
                description: |-
                  The token the pagination ends at. If ``dir=b`` this token should
                  be used again to request even earlier events.
              chunk:
                type: array
                description: |-
                  A list of room events.
                items:
                  type: object
                  title: RoomEvent
                  "$ref": "definitions/event-schemas/schema/core-event-schema/room_event.yaml"
              state:
                type: array
                description: |-
                  A list of state events relevant to showing the ``chunk``. For example, if
                  lazy-loading members is enabled in the filter then this will contain any
                  applicable membership events. Servers should be careful to not exclude
                  membership events which are older than ones already sent to the client.
                  Likewise, clients should be cautious and avoid using older membership
                  events as the current membership event when paginating backwards.

                  Unless ``include_redundant_members`` is ``true``, the server should remove
                  redundant members which would have already been sent to clients in prior calls
                  to ``/messages`` or ``/sync`` with the same filter.
                items:
                  type: object
                  title: RoomStateEvent
                  $ref: "definitions/event-schemas/schema/core-event-schema/state_event.yaml"
          examples:
            application/json: {
                "start": "t47429-4392820_219380_26003_2265",
                "end": "t47409-4357353_219380_26003_2265",
                "chunk": [
                  {
                    "origin_server_ts": 1444812213737,
                    "sender": "@alice:example.com",
                    "event_id": "$1444812213350496Caaaa:example.com",
                    "content": {
                      "body": "hello world",
                      "msgtype":"m.text"
                    },
                    "room_id":"!Xq3620DUiqCaoxq:example.com",
                    "type":"m.room.message",
                    "age": 1042
                  },
                  {
                    "origin_server_ts": 1444812194656 ,
                    "sender": "@bob:example.com",
                    "event_id": "$1444812213350496Cbbbb:example.com",
                    "content": {
                      "body": "the world is big",
                      "msgtype":"m.text"
                    },
                    "room_id":"!Xq3620DUiqCaoxq:example.com",
                    "type":"m.room.message",
                    "age": 20123
                  },
                  {
                    "origin_server_ts": 1444812163990,
                    "sender": "@bob:example.com",
                    "event_id": "$1444812213350496Ccccc:example.com",
                    "content": {
                      "name": "New room name"
                    },
                    "prev_content": {
                      "name": "Old room name"
                    },
                    "state_key": "",
                    "room_id":"!Xq3620DUiqCaoxq:example.com",
                    "type":"m.room.name",
                    "age": 50789
                  }
                ]
              }
        403:
          description: >
            You aren't a member of the room.
      tags:
        - Room participation