Spec `/relations` and aggregations (#1062)
* Commit to show changes to rich replies section * Move rich replies to a module * Add remainder of MSC2674 * Pivot away from MSC3440: Threads * Add changelog entries so far * Make a note for why we have aggregations/relations if nothing uses it * Outright remove threads references Apparently this breaks the table of contents * Define MSC2675 * Define MSC3666 * Add note for rich replies? * Update content/client-server-api/_index.md Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Clarify how ignoring works for aggregations. * Try to clarify redactions a bit * Clarify using parent/child language * Add missing bits of MSC2675 * Add changelog for aggregations * Appease the linters * Update data/api/client-server/relations.yaml Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Try to clarify the return of /relations * Fix required attribute * Fix wording round 1 * Try to fix pagination * Copy/paste the endpoint to make Open API happy * Fix code block examples for rich replies * Apply suggestions from code review Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> * Apply suggestions on all 3 endpoints * Fix description of relationships API * Fix warning about server-side aggregation/bundling Co-authored-by: Patrick Cloke <clokep@users.noreply.github.com> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com>pull/1114/head
Travis Ralston
3 years ago
committed by
GitHub
parent
f14e18131b
commit
c4db688af8
@ -0,0 +1 @@
|
||||
Relax the restrictions on Rich Replies, as per [MSC3676](https://github.com/matrix-org/matrix-spec-proposals/pull/3676).
|
||||
@ -0,0 +1 @@
|
||||
Describe a structured system for event relationships, as per [MSC2674](https://github.com/matrix-org/matrix-spec-proposals/pull/2674).
|
||||
@ -0,0 +1 @@
|
||||
Describe how relationships between events can be "aggregated", as per [MSC2675](https://github.com/matrix-org/matrix-spec-proposals/pull/2675) and [MSC3666](https://github.com/matrix-org/matrix-spec-proposals/pull/3666).
|
||||
@ -0,0 +1,182 @@
|
||||
---
|
||||
type: module
|
||||
---
|
||||
|
||||
### Rich replies
|
||||
|
||||
{{% changed-in v="1.3" %}}
|
||||
|
||||
Rich replies are a
|
||||
special kind of [relationship](#forming-relationships-between-events) which
|
||||
effectively quotes the referenced event for the client to render/process how
|
||||
it wishes. They are normally used with [`m.room.message`](#mroommessage) events.
|
||||
|
||||
{{% boxes/note %}}
|
||||
Until v1.3 of the spec, rich replies were limited to `m.room.message` events
|
||||
which could represent an HTML-formatted body. As of v1.3 this is now expanded
|
||||
to *all* event types by dropping the requirement that an HTML-formatted body
|
||||
be included.
|
||||
|
||||
Additionally, a rich reply can reference any other event type as of v1.3.
|
||||
Previously, a rich reply could only reference another `m.room.message` event.
|
||||
{{% /boxes/note %}}
|
||||
|
||||
When possible, events SHOULD include a [fallback representation](#fallbacks-for-rich-replies)
|
||||
to allow clients which do not render rich replies to still see something which
|
||||
appears to be a quoted reply.
|
||||
|
||||
Though rich replies form a relationship to another event, they do not
|
||||
use `rel_type` to create this relationship. Instead, a subkey named `m.in_reply_to`
|
||||
is used to describe the reply's relationship, leaving the other properties of
|
||||
`m.relates_to` to describe the primary relationship of the event. This means
|
||||
that if an event is simply in reply to another event, without further relationship,
|
||||
the `rel_type` and `event_id` properties of `m.relates_to` become *optional*.
|
||||
|
||||
An example reply would be:
|
||||
|
||||
```json5
|
||||
{
|
||||
"content": {
|
||||
"m.relates_to": {
|
||||
"m.in_reply_to": {
|
||||
"event_id": "$another_event"
|
||||
}
|
||||
},
|
||||
"body": "That sounds like a great idea!"
|
||||
},
|
||||
// other fields as required by events
|
||||
}
|
||||
```
|
||||
|
||||
Note that the `event_id` of the `m.in_reply_to` object has the same requirements
|
||||
as if it were to be under `m.relates_to` directly instead.
|
||||
|
||||
#### Fallbacks for rich replies
|
||||
|
||||
Some clients may not have support for rich replies and therefore need a
|
||||
fallback to use instead. Clients that do not support rich replies should
|
||||
render the event as if rich replies were not special.
|
||||
|
||||
Clients that do support rich replies SHOULD provide the fallback format on
|
||||
replies, and MUST strip the fallback before rendering the reply. The
|
||||
specific fallback text is different for each `msgtype`, however the
|
||||
general format for the `body` is:
|
||||
|
||||
```text
|
||||
> <@alice:example.org> This is the original body
|
||||
|
||||
This is where the reply goes
|
||||
```
|
||||
|
||||
The `formatted_body`, if present and using an associated `format` of
|
||||
`org.matrix.custom.html`, should use the following template:
|
||||
|
||||
```html
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
<!-- This is where the related event's HTML would be. -->
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
```
|
||||
|
||||
If the related event does not have a `formatted_body`, the event's
|
||||
`body` should be considered after encoding any HTML special characters.
|
||||
Note that the `href` in both of the anchors use a [matrix.to
|
||||
URI](/appendices#matrixto-navigation).
|
||||
|
||||
##### Stripping the fallback
|
||||
|
||||
Clients which support rich replies MUST strip the fallback from the
|
||||
event before rendering the event. This is because the text provided in
|
||||
the fallback cannot be trusted to be an accurate representation of the
|
||||
event. After removing the fallback, clients are recommended to represent
|
||||
the event referenced by `m.in_reply_to` similar to the fallback's
|
||||
representation, although clients do have creative freedom for their user
|
||||
interface. Clients should prefer the `formatted_body` over the `body`,
|
||||
just like with other `m.room.message` events.
|
||||
|
||||
To strip the fallback on the `body`, the client should iterate over each
|
||||
line of the string, removing any lines that start with the fallback
|
||||
prefix ("> ", including the space, without quotes) and stopping when
|
||||
a line is encountered without the prefix. This prefix is known as the
|
||||
"fallback prefix sequence".
|
||||
|
||||
To strip the fallback on the `formatted_body`, the client should remove
|
||||
the entirety of the `mx-reply` tag.
|
||||
|
||||
##### Fallback for `m.text`, `m.notice`, and unrecognised message types
|
||||
|
||||
Using the prefix sequence, the first line of the related event's `body`
|
||||
should be prefixed with the user's ID, followed by each line being
|
||||
prefixed with the fallback prefix sequence. For example:
|
||||
|
||||
```text
|
||||
> <@alice:example.org> This is the first line
|
||||
> This is the second line
|
||||
|
||||
This is the reply
|
||||
```
|
||||
|
||||
The `formatted_body` uses the template defined earlier in this section.
|
||||
|
||||
##### Fallback for `m.emote`
|
||||
|
||||
Similar to the fallback for `m.text`, each line gets prefixed with the
|
||||
fallback prefix sequence. However an asterisk should be inserted before
|
||||
the user's ID, like so:
|
||||
|
||||
```text
|
||||
> * <@alice:example.org> feels like today is going to be a great day
|
||||
|
||||
This is the reply
|
||||
```
|
||||
|
||||
The `formatted_body` has a subtle difference for the template where the
|
||||
asterisk is also inserted ahead of the user's ID:
|
||||
|
||||
```html
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
* <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
<!-- This is where the related event's HTML would be. -->
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
```
|
||||
|
||||
##### Fallback for `m.image`, `m.video`, `m.audio`, and `m.file`
|
||||
|
||||
The related event's `body` would be a file name, which may not be very
|
||||
descriptive. The related event should additionally not have a `format`
|
||||
or `formatted_body` in the `content` - if the event does have a `format`
|
||||
and/or `formatted_body`, those fields should be ignored. Because the
|
||||
filename alone may not be descriptive, the related event's `body` should
|
||||
be considered to be `"sent a file."` such that the output looks similar
|
||||
to the following:
|
||||
|
||||
```text
|
||||
> <@alice:example.org> sent a file.
|
||||
|
||||
This is the reply
|
||||
```
|
||||
```html
|
||||
<mx-reply>
|
||||
<blockquote>
|
||||
<a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
|
||||
<a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
|
||||
<br />
|
||||
sent a file.
|
||||
</blockquote>
|
||||
</mx-reply>
|
||||
This is where the reply goes.
|
||||
```
|
||||
|
||||
For `m.image`, the text should be `"sent an image."`. For `m.video`, the
|
||||
text should be `"sent a video."`. For `m.audio`, the text should be
|
||||
`"sent an audio file"`.
|
||||
@ -0,0 +1,43 @@
|
||||
# Copyright 2022 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# 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.
|
||||
|
||||
type: object
|
||||
title: m.relates_to
|
||||
description: |-
|
||||
Describes the relationship of an event to its parent. This is contained
|
||||
within the event's `content` alongside other fields for the relevant event type.
|
||||
example: {
|
||||
# We deliberately "break" the example by including the top-level field so it renders
|
||||
# sensibly for readers of the spec.
|
||||
"m.relates_to": {
|
||||
"rel_type": "org.example.relationship",
|
||||
"event_id": "$an_event"
|
||||
}
|
||||
}
|
||||
properties:
|
||||
rel_type:
|
||||
type: string
|
||||
description: |-
|
||||
The namespaced relationship type. Values must use the
|
||||
[Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
|
||||
|
||||
The relationship type determines how clients should perceive the event, and in what
|
||||
context. Some relationship types are processed server-side for "bundling", though not
|
||||
all relationships require such behaviour. For example, an `m.thread` relationship type
|
||||
might denote that the event is part of a "thread" of messages and should be rendered as
|
||||
such.
|
||||
event_id:
|
||||
type: string
|
||||
description: The event ID of the event that this event relates to.
|
||||
required: ['rel_type', 'event_id']
|
||||
@ -0,0 +1,425 @@
|
||||
# Copyright 2022 The Matrix.org Foundation C.I.C.
|
||||
#
|
||||
# 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 Relations API"
|
||||
version: "1.0.0"
|
||||
host: localhost:8008
|
||||
schemes:
|
||||
- https
|
||||
- http
|
||||
basePath: /_matrix/client/v1
|
||||
consumes:
|
||||
- application/json
|
||||
produces:
|
||||
- application/json
|
||||
securityDefinitions:
|
||||
$ref: definitions/security.yaml
|
||||
paths:
|
||||
"/rooms/{roomId}/relations/{eventId}":
|
||||
get:
|
||||
summary: Get the child events for a given parent event.
|
||||
description: |-
|
||||
Retrieve all of the child events for a given parent event.
|
||||
|
||||
Note that when paginating the `from` token should be "after" the `to` token in
|
||||
terms of topological ordering, because it is only possible to paginate "backwards"
|
||||
through events, starting at `from`.
|
||||
|
||||
For example, passing a `from` token from page 2 of the results, and a `to` token
|
||||
from page 1, would return the empty set. The caller can use a `from` token from
|
||||
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
||||
operationId: getRelatingEvents
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room containing the parent event.
|
||||
required: true
|
||||
x-example: "!636q39766251:matrix.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventId
|
||||
description: The ID of the parent event whose child events are to be returned.
|
||||
required: true
|
||||
x-example: "$asfDuShaf7Gafaw"
|
||||
- in: query
|
||||
type: string
|
||||
name: from
|
||||
description: |-
|
||||
The pagination token to start returning results from. If not supplied, results
|
||||
start at the most recent topological event known to the server.
|
||||
|
||||
Can be a `next_batch` token from a previous call, or a returned
|
||||
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
|
||||
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
|
||||
required: false
|
||||
x-example: "page2_token"
|
||||
- in: query
|
||||
type: string
|
||||
name: to
|
||||
description: |-
|
||||
The pagination token to stop returning results at. If not supplied, results
|
||||
continue up to `limit` or until there are no more events.
|
||||
|
||||
Like `from`, this can be a previous token from a prior call to this endpoint
|
||||
or from `/messages` or `/sync`.
|
||||
required: false
|
||||
x-example: "page3_token"
|
||||
- in: query
|
||||
type: integer
|
||||
name: limit
|
||||
description: |-
|
||||
The maximum number of results to return in a single `chunk`. The server can
|
||||
and should apply a maximum value to this parameter to avoid large responses.
|
||||
|
||||
Similarly, the server should apply a default value when not supplied.
|
||||
required: false
|
||||
x-example: 20
|
||||
responses:
|
||||
# note: this endpoint deliberately does not support rate limiting, therefore a
|
||||
# 429 error response is not included.
|
||||
|
||||
200:
|
||||
description: |-
|
||||
The paginated child events which point to the parent. If no events are
|
||||
pointing to the parent or the pagination yields no results, an empty `chunk`
|
||||
is returned.
|
||||
examples:
|
||||
application/json: {
|
||||
"chunk": [{
|
||||
"room_id": "!636q39766251:matrix.org",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
|
||||
"content": {
|
||||
"m.relates_to": {
|
||||
"rel_type": "org.example.my_relation",
|
||||
"event_id": "$asfDuShaf7Gafaw"
|
||||
}
|
||||
}
|
||||
}],
|
||||
"next_batch": "page2_token",
|
||||
"prev_batch": "page1_token"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
chunk:
|
||||
title: "ChildEventsChunk"
|
||||
type: array
|
||||
description: |-
|
||||
The child events of the requested event, ordered topologically most-recent first.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "definitions/client_event.yaml"
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means there are no more results to fetch and the client should stop paginating.
|
||||
prev_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means this is the start of the result set, i.e. this is the first batch/page.
|
||||
required: ['chunk']
|
||||
404:
|
||||
description: |-
|
||||
The parent event was not found or the user does not have permission to read
|
||||
this event (it might be contained in history that is not accessible to the user).
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Event not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Event relationships
|
||||
# The same as above, with added `/{relType}`
|
||||
"/rooms/{roomId}/relations/{eventId}/{relType}":
|
||||
get:
|
||||
summary: Get the child events for a given parent event, with a given `relType`.
|
||||
description: |-
|
||||
Retrieve all of the child events for a given parent event which relate to the parent
|
||||
using the given `relType`.
|
||||
|
||||
Note that when paginating the `from` token should be "after" the `to` token in
|
||||
terms of topological ordering, because it is only possible to paginate "backwards"
|
||||
through events, starting at `from`.
|
||||
|
||||
For example, passing a `from` token from page 2 of the results, and a `to` token
|
||||
from page 1, would return the empty set. The caller can use a `from` token from
|
||||
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
||||
operationId: getRelatingEventsWithRelType
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room containing the parent event.
|
||||
required: true
|
||||
x-example: "!636q39766251:matrix.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventId
|
||||
description: The ID of the parent event whose child events are to be returned.
|
||||
required: true
|
||||
x-example: "$asfDuShaf7Gafaw"
|
||||
- in: path
|
||||
type: string
|
||||
name: relType
|
||||
description: |-
|
||||
The [relationship type](/client-server-api/#relationship-types) to search for.
|
||||
required: true
|
||||
x-example: "org.example.my_relation"
|
||||
- in: query
|
||||
type: string
|
||||
name: from
|
||||
description: |-
|
||||
The pagination token to start returning results from. If not supplied, results
|
||||
start at the most recent topological event known to the server.
|
||||
|
||||
Can be a `next_batch` token from a previous call, or a returned
|
||||
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
|
||||
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
|
||||
required: false
|
||||
x-example: "page2_token"
|
||||
- in: query
|
||||
type: string
|
||||
name: to
|
||||
description: |-
|
||||
The pagination token to stop returning results at. If not supplied, results
|
||||
continue up to `limit` or until there are no more events.
|
||||
|
||||
Like `from`, this can be a previous token from a prior call to this endpoint
|
||||
or from `/messages` or `/sync`.
|
||||
required: false
|
||||
x-example: "page3_token"
|
||||
- in: query
|
||||
type: integer
|
||||
name: limit
|
||||
description: |-
|
||||
The maximum number of results to return in a single `chunk`. The server can
|
||||
and should apply a maximum value to this parameter to avoid large responses.
|
||||
|
||||
Similarly, the server should apply a default value when not supplied.
|
||||
required: false
|
||||
x-example: 20
|
||||
responses:
|
||||
# note: this endpoint deliberately does not support rate limiting, therefore a
|
||||
# 429 error response is not included.
|
||||
|
||||
200:
|
||||
description: |-
|
||||
The paginated child events which point to the parent. If no events are
|
||||
pointing to the parent or the pagination yields no results, an empty `chunk`
|
||||
is returned.
|
||||
examples:
|
||||
application/json: {
|
||||
"chunk": [{
|
||||
"room_id": "!636q39766251:matrix.org",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
|
||||
"content": {
|
||||
"m.relates_to": {
|
||||
"rel_type": "org.example.my_relation",
|
||||
"event_id": "$asfDuShaf7Gafaw"
|
||||
}
|
||||
}
|
||||
}],
|
||||
"next_batch": "page2_token",
|
||||
"prev_batch": "page1_token"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
chunk:
|
||||
title: "ChildEventsChunk"
|
||||
type: array
|
||||
description: |-
|
||||
The child events of the requested event, ordered topologically
|
||||
most-recent first. The events returned will match the `relType`
|
||||
supplied in the URL.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "definitions/client_event.yaml"
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means there are no more results to fetch and the client should stop paginating.
|
||||
prev_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means this is the start of the result set, i.e. this is the first batch/page.
|
||||
required: ['chunk']
|
||||
404:
|
||||
description: |-
|
||||
The parent event was not found or the user does not have permission to read
|
||||
this event (it might be contained in history that is not accessible to the user).
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Event not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Event relationships
|
||||
# The same as above, with added `/{eventType}`
|
||||
"/rooms/{roomId}/relations/{eventId}/{relType}/{eventType}":
|
||||
get:
|
||||
summary: Get the child events for a given parent event, with a given `relType` and `eventType`.
|
||||
description: |-
|
||||
Retrieve all of the child events for a given parent event which relate to the parent
|
||||
using the given `relType` and have the given `eventType`.
|
||||
|
||||
Note that when paginating the `from` token should be "after" the `to` token in
|
||||
terms of topological ordering, because it is only possible to paginate "backwards"
|
||||
through events, starting at `from`.
|
||||
|
||||
For example, passing a `from` token from page 2 of the results, and a `to` token
|
||||
from page 1, would return the empty set. The caller can use a `from` token from
|
||||
page 1 and a `to` token from page 2 to paginate over the same range, however.
|
||||
operationId: getRelatingEventsWithRelTypeAndEventType
|
||||
security:
|
||||
- accessToken: []
|
||||
parameters:
|
||||
- in: path
|
||||
type: string
|
||||
name: roomId
|
||||
description: The ID of the room containing the parent event.
|
||||
required: true
|
||||
x-example: "!636q39766251:matrix.org"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventId
|
||||
description: The ID of the parent event whose child events are to be returned.
|
||||
required: true
|
||||
x-example: "$asfDuShaf7Gafaw"
|
||||
- in: path
|
||||
type: string
|
||||
name: relType
|
||||
description: |-
|
||||
The [relationship type](/client-server-api/#relationship-types) to search for.
|
||||
required: true
|
||||
x-example: "org.example.my_relation"
|
||||
- in: path
|
||||
type: string
|
||||
name: eventType
|
||||
description: |-
|
||||
The event type of child events to search for.
|
||||
|
||||
Note that in encrypted rooms this will typically always be `m.room.encrypted`
|
||||
regardless of the event type contained within the encrypted payload.
|
||||
required: true
|
||||
x-example: "m.room.message"
|
||||
- in: query
|
||||
type: string
|
||||
name: from
|
||||
description: |-
|
||||
The pagination token to start returning results from. If not supplied, results
|
||||
start at the most recent topological event known to the server.
|
||||
|
||||
Can be a `next_batch` token from a previous call, or a returned
|
||||
`start` token from [`/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages),
|
||||
or a `next_batch` token from [`/sync`](/client-server-api/#get_matrixclientv3sync).
|
||||
required: false
|
||||
x-example: "page2_token"
|
||||
- in: query
|
||||
type: string
|
||||
name: to
|
||||
description: |-
|
||||
The pagination token to stop returning results at. If not supplied, results
|
||||
continue up to `limit` or until there are no more events.
|
||||
|
||||
Like `from`, this can be a previous token from a prior call to this endpoint
|
||||
or from `/messages` or `/sync`.
|
||||
required: false
|
||||
x-example: "page3_token"
|
||||
- in: query
|
||||
type: integer
|
||||
name: limit
|
||||
description: |-
|
||||
The maximum number of results to return in a single `chunk`. The server can
|
||||
and should apply a maximum value to this parameter to avoid large responses.
|
||||
|
||||
Similarly, the server should apply a default value when not supplied.
|
||||
required: false
|
||||
x-example: 20
|
||||
responses:
|
||||
# note: this endpoint deliberately does not support rate limiting, therefore a
|
||||
# 429 error response is not included.
|
||||
|
||||
200:
|
||||
description: |-
|
||||
The paginated child events which point to the parent. If no events are
|
||||
pointing to the parent or the pagination yields no results, an empty `chunk`
|
||||
is returned.
|
||||
examples:
|
||||
application/json: {
|
||||
"chunk": [{
|
||||
"room_id": "!636q39766251:matrix.org",
|
||||
"$ref": "../../event-schemas/examples/m.room.message$m.text.yaml",
|
||||
"content": {
|
||||
"m.relates_to": {
|
||||
"rel_type": "org.example.my_relation",
|
||||
"event_id": "$asfDuShaf7Gafaw"
|
||||
}
|
||||
}
|
||||
}],
|
||||
"next_batch": "page2_token",
|
||||
"prev_batch": "page1_token"
|
||||
}
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
chunk:
|
||||
title: "ChildEventsChunk"
|
||||
type: array
|
||||
description: |-
|
||||
The child events of the requested event, ordered topologically most-recent
|
||||
first. The events returned will match the `relType` and `eventType` supplied
|
||||
in the URL.
|
||||
items:
|
||||
allOf:
|
||||
- "$ref": "definitions/client_event.yaml"
|
||||
next_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means there are no more results to fetch and the client should stop paginating.
|
||||
prev_batch:
|
||||
type: string
|
||||
description: |-
|
||||
An opaque string representing a pagination token. The absence of this token
|
||||
means this is the start of the result set, i.e. this is the first batch/page.
|
||||
required: ['chunk']
|
||||
404:
|
||||
description: |-
|
||||
The parent event was not found or the user does not have permission to read
|
||||
this event (it might be contained in history that is not accessible to the user).
|
||||
examples:
|
||||
application/json: {
|
||||
"errcode": "M_NOT_FOUND",
|
||||
"error": "Event not found."
|
||||
}
|
||||
schema:
|
||||
"$ref": "definitions/errors/error.yaml"
|
||||
tags:
|
||||
- Event relationships
|
||||
|
||||
Loading…
Reference in New Issue