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/api/client-server/message_pagination.yaml

152 lines
5.7 KiB
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.
*Note*: This endpoint supports lazy-loading of room member events. See
`Lazy-loading room members <#lazy-loading-room-members>`_ for more information.
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. The order depends on the ``dir`` parameter.
For ``dir=b`` events will be in reverse-chronological order,
for ``dir=f`` in chronological order, so that events start
at the ``from`` point.
items:
"$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_load_members`` is enabled in the filter then this may contain
the membership events for the senders of events in the ``chunk``.
Unless ``include_redundant_members`` is ``true``, the server
may remove membership events which would have already been
sent to the client in prior calls to this endpoint, assuming
the membership of those members has not changed.
items:
$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": [
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.text"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.name"
},
{
"room_id": "!636q39766251:example.com",
"$ref": "definitions/event-schemas/examples/m.room.message$m.video"
}
]
}
403:
description: >
You aren't a member of the room.
tags:
- Room participation