synapse/docs/client-server/specification.rst

Synapse 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 | | | | _____| | ___________________| | | | 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 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" }

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.

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.textm.imagem.videom.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 : [02|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" }