diff options
Diffstat (limited to 'docs/specification.rst')
| -rw-r--r-- | docs/specification.rst | 168 |
1 files changed, 146 insertions, 22 deletions
diff --git a/docs/specification.rst b/docs/specification.rst index 9a494a4c0f..23c6b12091 100644 --- a/docs/specification.rst +++ b/docs/specification.rst @@ -417,7 +417,7 @@ State events can be sent by ``PUT`` ing to ``/rooms/<room id>/state/<event type> These events will be overwritten if ``<room id>``, ``<event type>`` and ``<state key>`` all match. If the state event has no ``state_key``, it can be omitted from the path. These requests **cannot use transaction IDs** like other ``PUT`` paths because they cannot be differentiated -from the ``state key``. Furthermore, ``POST`` is unsupported on state paths. Valid requests +from the ``state_key``. Furthermore, ``POST`` is unsupported on state paths. Valid requests look like:: PUT /rooms/!roomid:domain/state/m.example.event @@ -440,7 +440,7 @@ Care should be taken to avoid setting the wrong ``state key``:: { "key" : "with '11' as the state key, but was probably intended to be a txnId" } The ``state_key`` is often used to store state about individual users, by using the user ID as the -value. For example:: +``state_key`` value. For example:: PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Adomain.com { "animal" : "cat", "reason": "fluffy" } @@ -471,7 +471,8 @@ Syncing rooms ------------- When a client logs in, they may have a list of rooms which they have already joined. These rooms may also have a list of events associated with them. The purpose of 'syncing' is to present the -current room and event information in a convenient, compact manner. There are two APIs provided: +current room and event information in a convenient, compact manner. The events returned are not +limited to room events; presence events will also be returned. There are two APIs provided: - ``/initialSync`` : A global sync which will present room and event information for all rooms the user has joined. @@ -482,10 +483,40 @@ current room and event information in a convenient, compact manner. There are tw - TODO: JSON response format for both types - TODO: when would you use global? when would you use scoped? -Getting grouped state events for a room ---------------------------------------- -- ``/members`` and ``/messages`` and the event types they return. Spec JSON response format. -- ``/state`` and it returns ALL THE THINGS. +Getting events for a room +------------------------- +There are several APIs provided to ``GET`` events for a room: + +``/rooms/<room id>/state/<event type>/<state key>`` + Description: + Get the state event identified. + Response format: + A JSON object representing the state event **content**. + Example: + ``/rooms/!room:domain.com/state/m.room.name`` returns ``{ "name": "Room name" }`` + +``/rooms/<room id>/state`` + Description: + Get all state events for a room. + Response format: + ``[ { state event }, { state event }, ... ]`` + Example: + TODO + + +``/rooms/<room id>/members`` + Description: + Get all ``m.room.member`` state events. + Response format: + ``{ "start": "token", "end": "token", "chunk": [ { m.room.member event }, ... ] }`` + Example: + TODO + + + +- ``/rooms/<room id>/messages`` : Get all ``m.room.message`` events. +- ``/rooms/<room id>/initialSync`` : Get all relevant events for a room. + Room Events =========== @@ -493,24 +524,109 @@ Room Events This specification outlines several standard event types, all of which are prefixed with ``m.`` -State messages --------------- -- m.room.name -- m.room.topic -- m.room.member -- m.room.config -- m.room.invite_join +``m.room.name`` + Summary: + Set the human-readable name for the room. + Type: + State event + JSON format: + ``{ "name" : "string" }`` + Example: + ``{ "name" : "My Room" }`` + Description: + A room has an opaque room ID which is not human-friendly to read. A room alias is + human-friendly, but not all rooms have room aliases. The room name is a human-friendly + string designed to be displayed to the end-user. The room name is not *unique*, as + multiple rooms can have the same room name set. The room name can also be set when + creating a room using ``/createRoom`` with the ``name`` key. + +``m.room.topic`` + Summary: + Set a topic for the room. + Type: + State event + JSON format: + ``{ "topic" : "string" }`` + Example: + ``{ "topic" : "Welcome to the real world." }`` + Description: + A topic is a short message detailing what is currently being discussed in the room. + It can also be used as a way to display extra information about the room, which may + not be suitable for the room name. -What are they, when are they used, what do they contain, how should they be used. -Link back to explanatory sections (e.g. invite/join/leave sections for m.room.member) +``m.room.member`` + Summary: + The current membership state of a user in the room. + Type: + State event + JSON format: + ``{ "membership" : "enum[ invite|join|leave|ban ]" }`` + Example: + ``{ "membership" : "join" }`` + Description: + Adjusts the membership state for a user in a room. It is preferable to use the + membership APIs (``/rooms/<room id>/invite`` etc) when performing membership actions + rather than adjusting the state directly as there are a restricted set of valid + transformations. For example, user A cannot force user B to join a room, and trying + to force this state change directly will fail. See the "Rooms" section for how to + use the membership APIs. + +``m.room.config`` + Summary: + The room config. + Type: + State event + JSON format: + TODO + Example: + TODO + Description: + TODO -Non-state messages ------------------- -- m.room.message -- m.room.message.feedback (and compressed format) -- voip? +``m.room.invite_join`` + Summary: + TODO. + Type: + State event + JSON format: + TODO + Example: + TODO + Description: + TODO + +``m.room.message`` + Summary: + A message. + Type: + Non-state event + JSON format: + ``{ "msgtype": "string" }`` + Example: + ``{ "msgtype": "m.text", "body": "Testing" }`` + Description: + This event is used when sending messages in a room. Messages are not limited to be text. + The ``msgtype`` key outlines the type of message, e.g. text, audio, image, video, etc. + Whilst not required, the ``body`` key SHOULD be used with every kind of ``msgtype`` as + a fallback mechanism when a client cannot render the message. For more information on + the types of messages which can be sent, see "m.room.message msgtypes". + +``m.room.message.feedback`` + Summary: + A receipt for a message. + Type: + Non-state event + JSON format: + ``{ "type": "enum [ delivered|read ]", "target_event_id": "string" }`` + Example: + ``{ "type": "delivered", "target_event_id": "e3b2icys" }`` + Description: + Feedback events are events sent to acknowledge a message in some way. There are two + supported acknowledgements: ``delivered`` (sent when the event has been received) and + ``read`` (sent when the event has been observed by the end-user). The ``target_event_id`` + should reference the ``m.room.message`` event being acknowledged. -What are they, when are they used, what do they contain, how should they be used +- voip? m.room.message msgtypes ----------------------- @@ -636,6 +752,14 @@ client devices they have connected. The home server should synchronise this status choice among multiple devices to ensure the user gets a consistent experience. +In addition, the server maintains a timestamp of the last time it saw an active +action from the user; either sending a message to a room, or changing presence +state from a lower to a higher level of availability (thus: changing state from +``unavailable`` to ``online`` will count as an action for being active, whereas +in the other direction will not). This timestamp is presented via a key called +``last_active_ago``, which gives the relative number of miliseconds since the +message is generated/emitted, that the user was last seen active. + Idle Time --------- As well as the basic ``presence`` field, the presence information can also show |