forked-synapse/docs/client-server/specification.rst

========================
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"
}