MirrorHub/synapse
0
0
Fork 1
mirror of https://mau.dev/maunium/synapse.git synced 2024-12-15 06:33:50 +01:00
Code Issues Projects Releases Wiki Activity
synapse/docs/client-server/specification.rst

1280 lines
42 KiB
ReStructuredText
Raw Blame History

========================
Matrix Client-Server API
========================
The following specification outlines how a client can send and receive data from
a home server.
[[TODO(kegan): 4/7/14 Grilling
- Mechanism for getting historical state changes (e.g. topic updates) - add
query param flag?
- Generic mechanism for linking first class events (e.g. feedback) with other s
first class events (e.g. messages)?
- Generic mechanism for updating 'stuff about the room' (e.g. favourite coffee)
AND specifying clobbering rules (clobber/add to list/etc)?
- How to ensure a consistent view for clients paginating through room lists?
They aren't really ordered in any way, and if you're paginating
through them, how can you show them a consistent result set? Temporary 'room
list versions' akin to event version? How does that work?
]]
[[TODO(kegan):
Outstanding problems / missing spec:
- Push
- Typing notifications
]]
Terminology
-----------
Stream Tokens:
An opaque token used to make further streaming requests. When using any
pagination streaming API, responses will contain a start and end stream token.
When reconnecting to the stream, these tokens can be used to tell the server
where the client got up to in the stream.
Event ID:
Every event that comes down the event stream or that is returned from the REST
API has an associated event ID (event_id). This ID will be the same between the
REST API and the event stream, so any duplicate events can be clobbered
correctly without knowing anything else about the event.
Message ID:
The ID of a message sent by a client in a room. Clients send IMs to each other
in rooms. Each IM sent by a client must have a unique message ID which is unique
for that particular client.
User ID:
The @username:host style ID of the client. When registering for an account, the
client specifies their username. The user_id is this username along with the
home server's unique hostname. When federating between home servers, the user_id
is used to uniquely identify users across multiple home servers.
Room ID:
The room_id@host style ID for the room. When rooms are created, the client either
specifies or is allocated a room ID. This room ID must be used to send messages
in that room. Like with clients, there may be multiple rooms with the same ID
across multiple home servers. The room_id is used to uniquely identify a room
when federating.
Global message ID:
The globally unique ID for a message. This ID is formed from the msg_id, the
client's user_id and the room_id. This uniquely identifies any
message. It is represented with '-' as the delimeter between IDs. The
global_msg_id is of the form: room_id-user_id-msg_id
REST API and the Event Stream
-----------------------------
Clients send data to the server via a RESTful API. They can receive data via
this API or from an event stream. An event stream is a special path which
streams all events the client may be interested in. This makes it easy to
immediately receive updates from the REST API. All data is represented as JSON.
Pagination streaming API
========================
Clients are often interested in very large datasets. The data itself could
be 1000s of messages in a given room, 1000s of rooms in a public room list, or
1000s of events (presence, typing, messages, etc) in the system. It is not
practical to send vast quantities of data to the client every time they
request a list of public rooms for example. There needs to be a way to show a
subset of this data, and apply various filters to it. This is what the pagination
streaming API is. This API defines standard request/response parameters which
can be used when navigating this stream of data.
Pagination Request Query Parameters
-----------------------------------
Clients may wish to paginate results from the event stream, or other sources of
information where the amount of information may be a problem,
e.g. in a room with 10,000s messages. The pagination query parameters provide a
way to navigate a 'window' around a large set of data. These
parameters are only valid for GET requests.
S e r v e r - s i d e d a t a
|-------------------------------------------------|
START ^ ^ END
|_______________|
|
Client-extraction
'START' and 'END' are magic token values which specify the start and end of the
dataset respectively.
Query parameters:
from : $streamtoken - The opaque token to start streaming from.
to : $streamtoken - The opaque token to end streaming at. Typically,
clients will not know the item of data to end at, so this will usually be
START or END.
limit : integer - An integer representing the maximum number of items to
return.
For example, the event stream has events E1 -> E15. The client wants the last 5
events and doesn't know any previous events:
S E
|-E1-E2-E3-E4-E5-E6-E7-E8-E9-E10-E11-E12-E13-E14-E15-|
| | |
| _____| |
|__________________ | ___________________|
| | |
GET /events?to=START&limit=5&from=END
Returns:
E15,E14,E13,E12,E11
Another example: a public room list has rooms R1 -> R17. The client is showing 5
rooms at a time on screen, and is on page 2. They want to
now show page 3 (rooms R11 -> 15):
S E
| 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | stream token
|-R1-R2-R3-R4-R5-R6-R7-R8-R9-R10-R11-R12-R13-R14-R15-R16-R17| room
|____________| |________________|
| |
Currently |
viewing |
|
GET /rooms/list?from=9&to=END&limit=5
Returns: R11,R12,R13,R14,R15
Note that tokens are treated in an *exclusive*, not inclusive, manner. The end
token from the intial request was '9' which corresponded to R10. When the 2nd
request was made, R10 did not appear again, even though from=9 was specified. If
you know the token, you already have the data.
Pagination Response
-------------------
Responses to pagination requests MUST follow the format:
{
"chunk": [ ... , Responses , ... ],
"start" : $streamtoken,
"end" : $streamtoken
}
Where $streamtoken is an opaque token which can be used in another query to
get the next set of results. The "start" and "end" keys can only be omitted if
the complete dataset is provided in "chunk".
If the client wants earlier results, they should use from=$start_streamtoken,
to=START. Likewise, if the client wants later results, they should use
from=$end_streamtoken, to=END.
Unless specified, the default pagination parameters are from=START, to=END,
without a limit set. This allows you to hit an API like
/events without any query parameters to get everything.
The Event Stream
----------------
The event stream returns events using the pagination streaming API. When the
client disconnects for a while and wants to reconnect to the event stream, they
should specify from=$end_streamtoken. This lets the server know where in the
event stream the client is. These tokens are completely opaque, and the client
cannot infer anything from them.
GET /events?from=$LAST_STREAM_TOKEN
REST Path: /events
Returns (success): A JSON array of Event Data.
Returns (failure): An Error Response
LAST_STREAM_TOKEN is the last stream token obtained from the event stream. If the
client is connecting for the first time and does not know any stream tokens,
they can use "START" to request all events from the start. For more information
on this, see "Pagination Request Query Parameters".
The event stream supports shortpoll and longpoll with the "timeout" query
parameter. This parameter specifies the number of milliseconds the server should
hold onto the connection waiting for incoming events. If no events occur in this
period, the connection will be closed and an empty chunk will be returned. To
use shortpoll, specify "timeout=0".
Event Data
----------
This is a JSON object which looks like:
{
"event_id" : $EVENT_ID,
"type" : $EVENT_TYPE,
$URL_ARGS,
"content" : {
$EVENT_CONTENT
}
}
EVENT_ID
An ID identifying this event. This is so duplicate events can be suppressed on
the client.
EVENT_TYPE
The namespaced event type (m.*)
URL_ARGS
Path specific data from the REST API.
EVENT_CONTENT
The event content, matching the REST content PUT previously.
Events are differentiated via the event type "type" key. This is the type of
event being received. This can be expanded upon by using different namespaces.
Every event MUST have a 'type' key.
Most events will have a corresponding REST URL. This URL will generally have
data in it to represent the resource being modified,
e.g. /rooms/$room_id. The event data will contain extra top-level keys to expose
this information to clients listening on an event
stream. The event content maps directly to the contents submitted via the REST
API.
For example:
Event Type: m.example.room.members
REST Path: /examples/room/$room_id/members/$user_id
REST Content: { "membership" : "invited" }
is represented in the event stream as:
{
"event_id" : "e_some_event_id",
"type" : "m.example.room.members",
"room_id" : $room_id,
"user_id" : $user_id,
"content" : {
"membership" : "invited"
}
}
As convention, the URL variable "$varname" will map directly onto the name
of the JSON key "varname".
Error Responses
---------------
If the client sends an invalid request, the server MAY respond with an error
response. This is of the form:
{
"error" : "string",
"errcode" : "string"
}
The 'error' string will be a human-readable error message, usually a sentence
explaining what went wrong.
The 'errcode' string will be a unique string which can be used to handle an
error message e.g. "M_FORBIDDEN". These error codes should have their namespace
first in ALL CAPS, followed by a single _. For example, if there was a custom
namespace com.mydomain.here, and a "FORBIDDEN" code, the error code should look
like "COM.MYDOMAIN.HERE_FORBIDDEN". There may be additional keys depending on
the error, but the keys 'error' and 'errcode' will always be present.
Some standard error codes are below:
M_FORBIDDEN:
Forbidden access, e.g. joining a room without permission, failed login.
M_UNKNOWN_TOKEN:
The access token specified was not recognised.
M_BAD_JSON:
Request contained valid JSON, but it was malformed in some way, e.g. missing
required keys, invalid values for keys.
M_NOT_JSON:
Request did not contain valid JSON.
M_NOT_FOUND:
No resource was found for this request.
Some requests have unique error codes:
M_USER_IN_USE:
Encountered when trying to register a user ID which has been taken.
M_ROOM_IN_USE:
Encountered when trying to create a room which has been taken.
M_BAD_PAGINATION:
Encountered when specifying bad pagination values to a Pagination Streaming API.
========
REST API
========
All content must be application/json. Some keys are required, while others are
optional. Unless otherwise specified,
all HTTP PUT/POST/DELETEs will return a 200 OK with an empty response body on
success, and a 4xx/5xx with an optional Error Response on failure. When sending
data, if there are no keys to send, an empty JSON object should be sent.
All POST/PUT/GET/DELETE requests MUST have an 'access_token' query parameter to
allow the server to authenticate the client. All
POST requests MUST be submitted as application/json.
All paths MUST be namespaced by the version of the API being used. This should
be:
/matrix/client/api/v1
All REST paths in this section MUST be prefixed with this. E.g.
REST Path: /rooms/$room_id
Absolute Path: /matrix/client/api/v1/rooms/$room_id
Registration
============
Clients must register with the server in order to use the service. After
registering, the client will be given an
access token which must be used in ALL requests as a query parameter
'access_token'.
Registering for an account
--------------------------
POST /register
With: A JSON object containing the key "user_id" which contains the desired
user_id, or an empty JSON object to have the server allocate a user_id
automatically.
Returns (success): 200 OK with a JSON object:
{
"user_id" : "string [user_id]",
"access_token" : "string"
}
Returns (failure): An Error Response. M_USER_IN_USE if the user ID is taken.
Unregistering an account
------------------------
POST /unregister
With query parameters: access_token=$ACCESS_TOKEN
Returns (success): 200 OK
Returns (failure): An Error Response.
Logging in to an existing account
=================================
If the client has already registered, they need to be able to login to their
account. The home server may provide many different ways of logging in, such
as user/password auth, login via a social network (OAuth), login by confirming
a token sent to their email address, etc. This section does NOT define how home
servers should authorise their users who want to login to their existing
accounts. This section defines the standard interface which implementations
should follow so that ANY client can login to ANY home server.
The login process breaks down into the following:
1: Get login process info.
2: Submit the login stage credentials.
3: Get access token or be told the next stage in the login process and repeat
step 2.
Getting login process info:
GET /login
Returns (success): 200 OK with LoginInfo.
Returns (failure): An Error Response.
Submitting the login stage credentials:
POST /login
With: LoginSubmission
Returns (success): 200 OK with LoginResult
Returns (failure): An Error Response
Where LoginInfo is a JSON object which MUST have a "type" key which denotes the
login type. If there are multiple login stages, this object MUST also contain a
"stages" key, which has a JSON array of login types denoting all the steps in
order to login, including the first stage which is in "type". This allows the
client to make an informed decision as to whether or not they can natively
handle the entire login process, or whether they should fallback (see below).
Where LoginSubmission is a JSON object which MUST have a "type" key.
Where LoginResult is a JSON object which MUST have either a "next" key OR an
"access_token" key, depending if the login process is over or not. This object
MUST have a "session" key if multiple POSTs need to be sent to /login.
Fallback
--------
If the client does NOT know how to handle the given type, they should:
GET /login/fallback
This MUST return an HTML page which can perform the entire login process.
Password-based
--------------
Type: "m.login.password"
LoginSubmission:
{
"type": "m.login.password",
"user": <user_id>,
"password": <password>
}
Example:
Assume you are @bob:matrix.org and you wish to login on another mobile device.
First, you GET /login which returns:
{
"type": "m.login.password"
}
Your client knows how to handle this, so your client prompts the user to enter
their username and password. This is then submitted:
{
"type": "m.login.password",
"user": "@bob:matrix.org",
"password": "monkey"
}
The server checks this, finds it is valid, and returns:
{
"access_token": "abcdef0123456789"
}
The server may optionally return "user_id" to confirm or change the user's ID.
This is particularly useful if the home server wishes to support localpart entry
of usernames (e.g. "bob" rather than "@bob:matrix.org").
OAuth2-based
------------
Type: "m.login.oauth2"
This is a multi-stage login.
LoginSubmission:
{
"type": "m.login.oauth2",
"user": <user_id>
}
Returns:
{
"uri": <Authorization Request uri OR service selection uri>
}
The home server acts as a 'confidential' Client for the purposes of OAuth2.
If the uri is a "sevice selection uri", it is a simple page which prompts the
user to choose which service to authorize with. On selection of a service, they
link through to Authorization Request URIs. If there is only 1 service which the
home server accepts when logging in, this indirection can be skipped and the
"uri" key can be the Authorization Request URI.
The client visits the Authorization Request URI, which then shows the OAuth2
Allow/Deny prompt. Hitting 'Allow' returns the redirect URI with the auth code.
Home servers can choose any path for the redirect URI. The client should visit
the redirect URI, which will then finish the OAuth2 login process, granting the
home server an access token for the chosen service. When the home server gets
this access token, it knows that the cilent has authed with the 3rd party, and
so can return a LoginResult.
The OAuth redirect URI (with auth code) MUST return a LoginResult.
Example:
Assume you are @bob:matrix.org and you wish to login on another mobile device.
First, you GET /login which returns:
{
"type": "m.login.oauth2"
}
Your client knows how to handle this, so your client prompts the user to enter
their username. This is then submitted:
{
"type": "m.login.oauth2",
"user": "@bob:matrix.org"
}
The server only accepts auth from Google, so returns the Authorization Request
URI for Google:
{
"uri": "https://accounts.google.com/o/oauth2/auth?response_type=code&
client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&scope=photos"
}
The client then visits this URI and authorizes the home server. The client then
visits the REDIRECT_URI with the auth code= query parameter which returns:
{
"access_token": "0123456789abcdef"
}
Email-based (code)
------------------
Type: "m.login.email.code"
This is a multi-stage login.
First LoginSubmission:
{
"type": "m.login.email.code",
"user": <user_id>
"email": <email address>
}
Returns:
{
"session": <session id>
}
The email contains a code which must be sent in the next LoginSubmission:
{
"type": "m.login.email.code",
"session": <session id>,
"code": <code in email sent>
}
Returns:
{
"access_token": <access token>
}
Example:
Assume you are @bob:matrix.org and you wish to login on another mobile device.
First, you GET /login which returns:
{
"type": "m.login.email.code"
}
Your client knows how to handle this, so your client prompts the user to enter
their email address. This is then submitted:
{
"type": "m.login.email.code",
"user": "@bob:matrix.org",
"email": "bob@mydomain.com"
}
The server confirms that bob@mydomain.com is linked to @bob:matrix.org, then
sends an email to this address and returns:
{
"session": "ewuigf7462"
}
The client's screen changes to a code submission page. The email arrives and it
says something to the effect of "please enter 2348623 into the app". This is
the submitted along with the session:
{
"type": "m.login.email.code",
"session": "ewuigf7462",
"code": "2348623"
}
The server accepts this and returns:
{
"access_token": "abcdef0123456789"
}
Email-based (url)
-----------------
Type: "m.login.email.url"
This is a multi-stage login.
First LoginSubmission:
{
"type": "m.login.email.url",
"user": <user_id>
"email": <email address>
}
Returns:
{
"session": <session id>
}
The email contains a URL which must be clicked. After it has been clicked, the
client should perform a request:
{
"type": "m.login.email.code",
"session": <session id>
}
Returns:
{
"access_token": <access token>
}
Example:
Assume you are @bob:matrix.org and you wish to login on another mobile device.
First, you GET /login which returns:
{
"type": "m.login.email.url"
}
Your client knows how to handle this, so your client prompts the user to enter
their email address. This is then submitted:
{
"type": "m.login.email.url",
"user": "@bob:matrix.org",
"email": "bob@mydomain.com"
}
The server confirms that bob@mydomain.com is linked to @bob:matrix.org, then
sends an email to this address and returns:
{
"session": "ewuigf7462"
}
The client then starts polling the server with the following:
{
"type": "m.login.email.url",
"session": "ewuigf7462"
}
(Alternatively, the server could send the device a push notification when the
email has been validated). The email arrives and it contains a URL to click on.
The user clicks on the which completes the login process with the server. The
next time the client polls, it returns:
{
"access_token": "abcdef0123456789"
}
N-Factor auth
-------------
Multiple login stages can be combined with the "next" key in the LoginResult.
Example:
A server demands an email.code then password auth before logging in. First, the
client performs a GET /login which returns:
{
"type": "m.login.email.code",
"stages": ["m.login.email.code", "m.login.password"]
}
The client performs the email login (See "Email-based (code)"), but instead of
returning an access_token, it returns:
{
"next": "m.login.password"
}
The client then presents a user/password screen and the login continues until
this is complete (See "Password-based"), which then returns the "access_token".
Rooms
=====
A room is a conceptual place where users can send and receive messages. Rooms
can be created, joined and left. Messages are sent
to a room, and all participants in that room will receive the message. Rooms are
uniquely identified via the room_id.
Creating a room (with a room ID)
--------------------------------
Event Type: m.room.create [TODO(kegan): Do we generate events for this?]
REST Path: /rooms/$room_id
Valid methods: PUT
Required keys: None.
Optional keys:
visibility : [public|private] - Set whether this room shows up in the public
room list.
Returns:
On Failure: MAY return a suggested alternative room ID if this room ID is
taken.
{
suggested_room_id : $new_room_id
error : "Room already in use."
errcode : "M_ROOM_IN_USE"
}
Creating a room (without a room ID)
-----------------------------------
Event Type: m.room.create [TODO(kegan): Do we generate events for this?]
REST Path: /rooms
Valid methods: POST
Required keys: None.
Optional keys:
visibility : [public|private] - Set whether this room shows up in the public
room list.
Returns:
On Success: The allocated room ID. Additional information about the room
such as the visibility MAY be included as extra keys in this response.
{
room_id : $room_id
}
Setting the topic for a room
----------------------------
Event Type: m.room.topic
REST Path: /rooms/$room_id/topic
Valid methods: GET/PUT
Required keys:
topic : $topicname - Set the topic to $topicname in room $room_id.
See a list of public rooms
--------------------------
REST Path: /public/rooms?pagination_query_parameters
Valid methods: GET
This API can use pagination query parameters.
Returns:
{
"chunk" : JSON array of RoomInfo JSON objects - Required.
"start" : "string (start token)" - See Pagination Response.
"end" : "string (end token)" - See Pagination Response.
"total" : integer - Optional. The total number of rooms.
}
RoomInfo: Information about a single room.
Servers MUST send the key: room_id
Servers MAY send the keys: topic, num_members
{
"room_id" : "string",
"topic" : "string",
"num_members" : integer
}
Room Members
============
Invite/Joining/Leaving a room
-----------------------------
Event Type: m.room.member
REST Path: /rooms/$room_id/members/$user_id/state
Valid methods: PUT/GET/DELETE
Required keys:
membership : [join|invite] - The membership state of $user_id in room
$room_id.
Optional keys:
displayname,
avatar_url : String fields from the member user's profile
state,
status_msg,
mtime_age : Presence information
These optional keys provide extra information that the client is likely to
be interested in so it doesn't have to perform an additional profile or
presence information fetch.
Where:
join - Indicate you ($user_id) are joining the room $room_id.
invite - Indicate that $user_id has been invited to room $room_id.
User $user_id can leave room $room_id by DELETEing this path.
Checking the user list of a room
--------------------------------
REST Path: /rooms/$room_id/members/list
This API can use pagination query parameters.
Valid methods: GET
Returns:
A pagination response with chunk data as m.room.member events.
Messages
========
Users send messages to other users in rooms. These messages may be text, images,
video, etc. Clients may also want to acknowledge messages by sending feedback,
in the form of delivery/read receipts.
Server-attached keys
--------------------
The server MAY attach additional keys to messages and feedback. If a client
submits keys with the same name, they will be clobbered by
the server.
Required keys:
from : "string [user_id]"
The user_id of the user who sent the message/feedback.
Optional keys:
hsob_ts : integer
A timestamp (ms resolution) representing when the message/feedback got to the
sender's home server ("home server outbound timestamp").
hsib_ts : integer
A timestamp (ms resolution) representing when the
message/feedback got to the receiver's home server ("home server inbound
timestamp"). This may be the same as hsob_ts if the sender/receiver are on the
same home server.
Sending messages
----------------
Event Type: m.room.message
REST Path: /rooms/$room_id/messages/$from/$msg_id
Valid methods: GET/PUT
URL parameters:
$from : user_id - The sender's user_id. This value will be clobbered by the
server before sending.
Required keys:
msgtype: [m.text|m.emote|m.image|m.audio|m.video|m.location|m.file] -
The type of message. Not to be confused with the Event 'type'.
Optional keys:
sender_ts : integer - A timestamp (ms resolution) representing the
wall-clock time when the message was sent from the client.
Reserved keys:
body : "string" - The human readable string for compatibility with clients
which cannot process a given msgtype. This key is optional, but
if it is included, it MUST be human readable text
describing the message. See individual msgtypes for more
info on what this means in practice.
Each msgtype may have required fields of their own.
msgtype: m.text
----------------
Required keys:
body : "string" - The body of the message.
Optional keys:
None.
msgtype: m.emote
-----------------
Required keys:
body : "string" - *tries to come up with a witty explanation*.
Optional keys:
None.
msgtype: m.image
-----------------
Required keys:
url : "string" - The URL to the image.
Optional keys:
body : "string" - info : JSON object (ImageInfo) - The image info for image
referred to in 'url'.
thumbnail_url : "string" - The URL to the thumbnail.
thumbnail_info : JSON object (ImageInfo) - The image info for the image
referred to in 'thumbnail_url'.
ImageInfo: Information about an image.
{
"size" : integer (size of image in bytes),
"w" : integer (width of image in pixels),
"h" : integer (height of image in pixels),
"mimetype" : "string (e.g. image/jpeg)"
}
Interpretation of 'body' key: The alt text of the image, or some kind of content
description for accessibility e.g. "image attachment".
msgtype: m.audio
-----------------
Required keys:
url : "string" - The URL to the audio.
Optional keys:
info : JSON object (AudioInfo) - The audio info for the audio referred to in
'url'.
AudioInfo: Information about a piece of audio.
{
"mimetype" : "string (e.g. audio/aac)",
"size" : integer (size of audio in bytes),
"duration" : integer (duration of audio in milliseconds)
}
Interpretation of 'body' key: A description of the audio e.g. "Bee Gees -
Stayin' Alive", or some kind of content description for accessibility e.g.
"audio attachment".
msgtype: m.video
-----------------
Required keys:
url : "string" - The URL to the video.
Optional keys:
info : JSON object (VideoInfo) - The video info for the video referred to in
'url'.
VideoInfo: Information about a video.
{
"mimetype" : "string (e.g. video/mp4)",
"size" : integer (size of video in bytes),
"duration" : integer (duration of video in milliseconds),
"w" : integer (width of video in pixels),
"h" : integer (height of video in pixels),
"thumbnail_url" : "string (URL to image)",
"thumbanil_info" : JSON object (ImageInfo)
}
Interpretation of 'body' key: A description of the video e.g. "Gangnam style",
or some kind of content description for accessibility e.g. "video attachment".
msgtype: m.location
--------------------
Required keys:
geo_uri : "string" - The geo URI representing the location.
Optional keys:
thumbnail_url : "string" - The URL to a thumnail of the location being
represented.
thumbnail_info : JSON object (ImageInfo) - The image info for the image
referred to in 'thumbnail_url'.
Interpretation of 'body' key: A description of the location e.g. "Big Ben,
London, UK", or some kind of content description for accessibility e.g.
"location attachment".
Sending feedback
----------------
When you receive a message, you may want to send delivery receipt to let the
sender know that the message arrived. You may also want to send a read receipt
when the user has read the message. These receipts are collectively known as
'feedback'.
Event Type: m.room.message.feedback
REST Path: /rooms/$room_id/messages/$msgfrom/$msg_id/feedback/$from/$feedback
Valid methods: GET/PUT
URL parameters:
$msgfrom - The sender of the message's user_id.
$from : user_id - The sender of the feedback's user_id. This value will be
clobbered by the server before sending.
$feedback : [d|r] - Specify if this is a [d]elivery or [r]ead receipt.
Required keys:
None.
Optional keys:
sender_ts : integer - A timestamp (ms resolution) representing the
wall-clock time when the receipt was sent from the client.
Receiving messages (bulk/pagination)
------------------------------------
Event Type: m.room.message
REST Path: /rooms/$room_id/messages/list
Valid methods: GET
Query Parameters:
feedback : [true|false] - Specify if feedback should be bundled with each
message.
This API can use pagination query parameters.
Returns:
A JSON array of Event Data in "chunk" (see Pagination Response). If the
"feedback" parameter was set, the Event Data will also contain a "feedback"
key which contains a JSON array of feedback, with each element as Event Data
with compressed feedback for this message.
Event Data with compressed feedback is a special type of feedback with
contextual keys removed. It is designed to limit the amount of redundant data
being sent for feedback. This removes the type, event_id, room ID,
message sender ID and message ID keys.
ORIGINAL (via event streaming)
{
"event_id":"e1247632487",
"type":"m.room.message.feedback",
"from":"string [user_id]",
"feedback":"string [d|r]",
"room_id":"$room_id",
"msg_id":"$msg_id",
"msgfrom":"$msgfromid",
"content":{
"sender_ts":139880943
}
}
COMPRESSED (via /messages/list)
{
"from":"string [user_id]",
"feedback":"string [d|r]",
"content":{
"sender_ts":139880943
}
}
When you join a room $room_id, you may want the last 10 messages with feedback.
This is represented as:
GET
/rooms/$room_id/messages/list?from=END&to=START&limit=10&feedback=true
You may want to get 10 messages even earlier than that without feedback. If the
start stream token from the previous request was stok_019173, this request would
be:
GET
/rooms/$room_id/messages/list?from=stok_019173&to=START&limit=10&
feedback=false
NOTE: Care must be taken when using this API in conjunction with event
streaming. It is possible that this will return a message which will
then come down the event stream, resulting in a duplicate message. Clients
should clobber based on the global message ID, or event ID.
Get current state for all rooms (aka IM Initial Sync API)
-------------------------------
REST Path: /im/sync
Valid methods: GET
This API can use pagination query parameters. Pagination is applied on a per
*room* basis. E.g. limit=1 means "get 1 message for each room" and not "get 1
room's messages". If there is no limit, all messages for all rooms will be
returned.
If you want 1 room's messages, see "Receiving messages (bulk/pagination)".
Additional query parameters:
feedback: [true] - Bundles feedback with messages.
Returns:
An array of RoomStateInfo.
RoomStateInfo: A snapshot of information about a single room.
{
"room_id" : "string",
"membership" : "string [join|invite]",
"messages" : {
"start": "string",
"end": "string",
"chunk":
m.room.message pagination stream events (with feedback if specified),
this is the same as "Receiving messages (bulk/pagination)".
}
}
The "membership" key is the calling user's membership state in the given
"room_id". The "messages" key may be omitted if the "membership" value is
"invite". Additional keys may be added to the top-level object, such as:
"topic" : "string" - The topic for the room in question.
"room_image_url" : "string" - The URL of the room image if specified.
"num_members" : integer - The number of members in the room.
Profiles
========
Getting/Setting your own displayname
------------------------------------
REST Path: /profile/$user_id/displayname
Valid methods: GET/PUT
Required keys:
displayname : The displayname text
Getting/Setting your own avatar image URL
-----------------------------------------
The homeserver does not currently store the avatar image itself, but offers
storage for the user to specify a web URL that points at the required image,
leaving it up to clients to fetch it themselves.
REST Path: /profile/$user_id/avatar_url
Valid methods: GET/PUT
Required keys:
avatar_url : The URL path to the required image
Getting other user's profile information
----------------------------------------
Either of the above REST methods may be used to fetch other user's profile
information by the client, either on other local users on the same homeserver or
for users from other servers entirely.
Presence
========
In the following messages, the presence state is an integer enumeration of the
following states:
0 : OFFLINE
1 : BUSY
2 : ONLINE
3 : FREE_TO_CHAT
Aside from OFFLINE, the protocol doesn't assign any special meaning to these
states; they are provided as an approximate signal for users to give to other
users and for clients to present them in some way that may be useful. Clients
could have different behaviours for different states of the user's presence, for
example to decide how much prominence or sound to use for incoming event
notifications.
Getting/Setting your own presence state
---------------------------------------
REST Path: /presence/$user_id/status
Valid methods: GET/PUT
Required keys:
state : [0|1|2|3] - The user's new presence state
Optional keys:
status_msg : text string provided by the user to explain their status
Fetching your presence list
---------------------------
REST Path: /presence_list/$user_id
Valid methods: GET/(post)
Returns:
An array of presence list entries. Each entry is an object with the
following keys:
{
"user_id" : string giving the observed user's ID
"state" : int giving their status
"status_msg" : optional text string
"displayname" : optional text string from the user's profile
"avatar_url" : optional text string from the user's profile
}
Maintaining your presence list
------------------------------
REST Path: /presence_list/$user_id
Valid methods: POST/(get)
With: A JSON object optionally containing either of the following keys:
"invite" : a list of strings giving user IDs to invite for presence
subscription
"drop" : a list of strings giving user IDs to remove from your presence
list
Receiving presence update events
--------------------------------
Event Type: m.presence
Keys of the event's content are the same as those returned by the presence
list.
Examples
========
The following example is the story of "bob", who signs up at "sy.org" and joins
the public room "room_beta@sy.org". They get the 2 most recent
messages (with feedback) in that room and then send a message in that room.
For context, here is the complete chat log for room_beta@sy.org:
Room: "Hello world" (room_beta@sy.org)
Members: (2) alice@randomhost.org, friend_of_alice@randomhost.org
Messages:
alice@randomhost.org : hi friend!
[friend_of_alice@randomhost.org DELIVERED]
alice@randomhost.org : you're my only friend
[friend_of_alice@randomhost.org DELIVERED]
alice@randomhost.org : afk
[friend_of_alice@randomhost.org DELIVERED]
[ bob@sy.org joins ]
bob@sy.org : Hi everyone
[ alice@randomhost.org changes the topic to "FRIENDS ONLY" ]
alice@randomhost.org : Hello!!!!
alice@randomhost.org : Let's go to another room
alice@randomhost.org : You're not my friend
[ alice@randomhost.org invites bob@sy.org to the room
commoners@randomhost.org]
REGISTER FOR AN ACCOUNT
POST: /register
Content: {}
Returns: { "user_id" : "bob@sy.org" , "access_token" : "abcdef0123456789" }
GET PUBLIC ROOM LIST
GET: /rooms/list?access_token=abcdef0123456789
Returns:
{
"total":3,
"chunk":
[
{ "room_id":"room_alpha@sy.org", "topic":"I am a fish" },
{ "room_id":"room_beta@sy.org", "topic":"Hello world" },
{ "room_id":"room_xyz@sy.org", "topic":"Goodbye cruel world" }
]
}
JOIN ROOM room_beta@sy.org
PUT
/rooms/room_beta%40sy.org/members/bob%40sy.org/state?
access_token=abcdef0123456789
Content: { "membership" : "join" }
Returns: 200 OK
GET LATEST 2 MESSAGES WITH FEEDBACK
GET
/rooms/room_beta%40sy.org/messages/list?from=END&to=START&limit=2&
feedback=true&access_token=abcdef0123456789
Returns:
{
"chunk":
[
{
"event_id":"01948374",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"avefifu",
"from":"alice@randomhost.org",
"hs_ts":139985736,
"content":{
"msgtype":"m.text",
"body":"afk"
}
"feedback": [
{
"from":"friend_of_alice@randomhost.org",
"feedback":"d",
"hs_ts":139985850,
"content":{
"sender_ts":139985843
}
}
]
},
{
"event_id":"028dfe8373",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"afhgfff",
"from":"alice@randomhost.org",
"hs_ts":139970006,
"content":{
"msgtype":"m.text",
"body":"you're my only friend"
}
"feedback": [
{
"from":"friend_of_alice@randomhost.org",
"feedback":"d",
"hs_ts":139970144,
"content":{
"sender_ts":139970122
}
}
]
},
],
"start": "stok_04823947",
"end": "etok_1426425"
}
SEND MESSAGE IN ROOM
PUT
/rooms/room_beta%40sy.org/messages/bob%40sy.org/m0001?
access_token=abcdef0123456789
Content: { "msgtype" : "text" , "body" : "Hi everyone" }
Returns: 200 OK
Checking the event stream for this user:
GET: /events?from=START&access_token=abcdef0123456789
Returns:
{
"chunk":
[
{
"event_id":"e10f3d2b",
"type":"m.room.member",
"room_id":"room_beta@sy.org",
"user_id":"bob@sy.org",
"content":{
"membership":"join"
}
},
{
"event_id":"1b352d32",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"m0001",
"from":"bob@sy.org",
"hs_ts":140193857,
"content":{
"msgtype":"m.text",
"body":"Hi everyone"
}
}
],
"start": "stok_9348635",
"end": "etok_1984723"
}
Client disconnects for a while and the topic is updated in this room, 3 new
messages arrive whilst offline, and bob is invited to another room.
GET /events?from=etok_1984723&access_token=abcdef0123456789
Returns:
{
"chunk":
[
{
"event_id":"feee0294",
"type":"m.room.topic",
"room_id":"room_beta@sy.org",
"from":"alice@randomhost.org",
"content":{
"topic":"FRIENDS ONLY",
}
},
{
"event_id":"a028bd9e",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"z839409",
"from":"alice@randomhost.org",
"hs_ts":140195000,
"content":{
"msgtype":"m.text",
"body":"Hello!!!"
}
},
{
"event_id":"49372d9e",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"z839410",
"from":"alice@randomhost.org",
"hs_ts":140196000,
"content":{
"msgtype":"m.text",
"body":"Let's go to another room"
}
},
{
"event_id":"10abdd01",
"type":"m.room.message",
"room_id":"room_beta@sy.org",
"msg_id":"z839411",
"from":"alice@randomhost.org",
"hs_ts":140197000,
"content":{
"msgtype":"m.text",
"body":"You're not my friend"
}
},
{
"event_id":"0018453d",
"type":"m.room.member",
"room_id":"commoners@randomhost.org",
"from":"alice@randomhost.org",
"user_id":"bob@sy.org",
"content":{
"membership":"invite"
}
},
],
"start": "stok_0184288",
"end": "etok_1348723"
}
Reference in a new issue View git blame Copy permalink