mirror of
https://github.com/matrix-org/matrix-spec
synced 2026-04-24 11:44:08 +02:00
a7b808c5cd
invite. This is kept separate from the actual state for the room as it may be derived from an incomplete, unverified copy of the state that was bundled with an invite event received over federation.
247 lines
9.9 KiB
YAML
247 lines
9.9 KiB
YAML
swagger: '2.0'
|
|
info:
|
|
title: "Matrix Client-Server v2 sync API"
|
|
version: "1.0.0"
|
|
host: localhost:8008
|
|
schemes:
|
|
- https
|
|
basePath: /_matrix/client/v2_alpha
|
|
consumes:
|
|
- application/json
|
|
produces:
|
|
- application/json
|
|
securityDefinitions:
|
|
accessToken:
|
|
type: apiKey
|
|
description: The user_id or application service access_token
|
|
name: access_token
|
|
in: query
|
|
paths:
|
|
"/sync":
|
|
get:
|
|
summary: Synchronise the client's state and receive new messages.
|
|
description: |-
|
|
Synchronise the client's state with the latest state on the server.
|
|
Client's use this API when they first log in to get an initial snapshot
|
|
of the state on the server, and then continue to call this API to get
|
|
incremental deltas to the state, and to receive new messages.
|
|
security:
|
|
- accessToken: []
|
|
parameters:
|
|
- in: query
|
|
name: filter
|
|
type: string
|
|
description: |-
|
|
The ID of a filter created using the filter API.
|
|
x-example: "66696p746572"
|
|
- in: query
|
|
name: since
|
|
type: string
|
|
description: |-
|
|
A point in time to continue a sync from.
|
|
x-example: "s72594_4483_1934"
|
|
- in: query
|
|
name: set_presence
|
|
type: string
|
|
enum: ["offline"]
|
|
description: |-
|
|
Controls whether the client is automatically marked as online by
|
|
polling this API. If this parameter is omitted then the client is
|
|
automatically marked as online when it uses this API. Otherwise if
|
|
the parameter is set to "offline" then the client is not marked as
|
|
being online when it uses this API.
|
|
x-example: "offline"
|
|
- in: query
|
|
name: timeout
|
|
type: integer
|
|
description: |-
|
|
The maximum time to poll in milliseconds before returning this
|
|
request.
|
|
x-example: 30000
|
|
responses:
|
|
200:
|
|
description:
|
|
The initial snapshot or delta for the client to use to update their
|
|
state.
|
|
schema:
|
|
type: object
|
|
properties:
|
|
next_batch:
|
|
type: string
|
|
description: |-
|
|
The batch token to supply in the ``since`` param of the next
|
|
``/sync`` request.
|
|
rooms:
|
|
type: object
|
|
description: |-
|
|
The updates to rooms, grouped according to the filter. By
|
|
default there is a single ``default`` group.
|
|
additionalProperties:
|
|
joined:
|
|
type: array
|
|
description: |-
|
|
A list of room ids that the user is a member of that
|
|
have updates.
|
|
items:
|
|
type: string.
|
|
invited:
|
|
type: array
|
|
description: |-
|
|
A list of room ids that the user has been invited to.
|
|
The entries in the room_map will have an
|
|
``invite_state`` key. But will lack the ``ephemeral``
|
|
key, the ``timeline`` key and the ``state`` key.
|
|
items:
|
|
type: string.
|
|
archived:
|
|
type: array
|
|
description: |-
|
|
A list of room ids that the user has left or been
|
|
banned from. The entries in the room_map will have a
|
|
``state`` key and a ``timeline`` key. But will lack the
|
|
``ephemeral`` key.
|
|
items:
|
|
type: string.
|
|
room_map:
|
|
description: |-
|
|
Map from room id to the updates for that room. The room ids
|
|
are referenced from the ``rooms`` key.
|
|
type: object
|
|
additionalProperties:
|
|
type: object
|
|
properties:
|
|
event_map:
|
|
type: object
|
|
description: |-
|
|
A map from event ID to events for this room. The events
|
|
are referenced from the ``timeline`` and ``state`` keys
|
|
for this room.
|
|
additionalProperties:
|
|
description: An event object.
|
|
type: object
|
|
state:
|
|
description: |-
|
|
The state updates for the room.
|
|
allOf:
|
|
- $ref: "definitions/room_event_batch.json"
|
|
timeline:
|
|
description: |-
|
|
The timeline of messages and state changes in the room.
|
|
allOf:
|
|
- $ref: "definitions/timeline_batch.json"
|
|
ephemeral:
|
|
description: |-
|
|
The ephemeral events in the room that aren't recorded
|
|
in the timeline or state of the room. E.g. typing.
|
|
allOf:
|
|
- $ref: "definitions/event_batch.json"
|
|
invite_state:
|
|
description: |-
|
|
The state of a room that the user has been invited to.
|
|
These state events may only have the ``type``,
|
|
``state_key`` and ``content`` keys present.
|
|
These events do not replace any state that the client
|
|
already has for the room, for example if the client has
|
|
archived the room. Instead the client should keep two
|
|
separate copies of the state: the one from the
|
|
``invite_state`` and one from the archived ``state``.
|
|
If the client joins the room then the current state
|
|
will be given as a delta against the archived ``state``
|
|
not the ``invite_state``.
|
|
allOf:
|
|
- $ref: "definitions/event_batch.json"
|
|
presence:
|
|
description: |-
|
|
The updates to the presence status of other users.
|
|
allOf:
|
|
- $ref: "definitions/event_batch.json"
|
|
examples:
|
|
application/json: |-
|
|
{
|
|
"next_batch": "s72595_4483_1934",
|
|
"presence": {
|
|
"events": [
|
|
{
|
|
"sender": "@alice:example.com",
|
|
"type": "m.presence",
|
|
"content": {"presence": "online"}
|
|
}
|
|
]
|
|
},
|
|
"rooms": {
|
|
"default": {
|
|
"invited": ["!696r7674:example.com"],
|
|
"archived": [],
|
|
"joined": ["!726s6s6q:example.com"]
|
|
}
|
|
},
|
|
"room_map": {
|
|
"!726s6s6q:example.com": {
|
|
"event_map": {
|
|
"$66697273743031:example.com": {
|
|
"sender": "@alice:example.com",
|
|
"type": "m.room.member",
|
|
"state_key": "@alice:example.com",
|
|
"content": {"membership": "join"},
|
|
"origin_server_ts": 1417731086795
|
|
},
|
|
"$7365636s6r6432:example.com": {
|
|
"sender": "@bob:example.com",
|
|
"type": "m.room.member",
|
|
"state_key": "@bob:example.com",
|
|
"content": {"membership": "join"},
|
|
"origin_server_ts": 1417731086795
|
|
},
|
|
"$74686972643033:example.com": {
|
|
"sender": "@alice:example.com",
|
|
"type": "m.room.message",
|
|
"unsigned": {"age": "124524", "txn_id": "1234"},
|
|
"content": {"body": "I am a fish", "msgtype": "m.text"},
|
|
"origin_server_ts": 1417731086797
|
|
}
|
|
},
|
|
"state": {
|
|
"events": [
|
|
"$66697273743031:example.com",
|
|
"$7365636s6r6432:example.com"
|
|
]
|
|
},
|
|
"timeline": {
|
|
"events": [
|
|
"$7365636s6r6432:example.com",
|
|
"$74686972643033:example.com"
|
|
],
|
|
"limited": true,
|
|
"prev_batch": "t34-23535_0_0"
|
|
},
|
|
"ephemeral": {
|
|
"events": [
|
|
{
|
|
"room_id": "!726s6s6q:example.com",
|
|
"type": "m.typing",
|
|
"content": {"user_ids": ["@alice:example.com"]}
|
|
}
|
|
]
|
|
}
|
|
},
|
|
"!696r7674:example.com": {
|
|
"invite_state": {
|
|
"events": [
|
|
{
|
|
"sender": "@alice:example.com",
|
|
"type": "m.room.name",
|
|
"state_key": "@alice:example.com",
|
|
"content": {"name": "My Room Name"}
|
|
},
|
|
{
|
|
"sender": "@alice:example.com",
|
|
"type": "m.room.name",
|
|
"state_key": "",
|
|
"content": {"membership": "invite"}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|