!opaque_id:domain

 { @alice:matrix.org }                             { @bob:domain.com }
         |                                                 ^
         |                                                 |
[HTTP POST]                                  [HTTP GET]
Room ID: !qporfwt:matrix.org                 Room ID: !qporfwt:matrix.org
Event type: m.room.message                   Event type: m.room.message
Content: { JSON object }                     Content: { JSON object }
         |                                                 |
         V                                                 |
 +------------------+                          +------------------+
 |   Home Server    |                          |   Home Server    |
 |   matrix.org     |                          |   domain.com     |
 +------------------+                          +------------------+
         |                                                 ^
         |         [HTTP PUT]                              |
         |         Room ID: !qporfwt:matrix.org            |
         |         Event type: m.room.message              |
         |         Content: { JSON object }                |
         `-------> Pointer to the preceding message  ------`
                   PKI signature from matrix.org
                   Transaction-layer metadata
                   PKI Authorization header

               ...................................
              |           Shared Data             |
              | State:                            |
              |   Room ID: !qporfwt:matrix.org    |
              |   Servers: matrix.org, domain.com |
              |   Members:                        |
              |    - @alice:matrix.org            |
              |    - @bob:domain.com              |
              | Messages:                         |
              |   - @alice:matrix.org             |
              |     Content: { JSON object }      |
              |...................................|

3.1.4.1   Room Aliases

Each room can also have multiple "Room Aliases", which look like:

#room_alias:domain

A room alias "points" to a room ID and is the human-readable label by which rooms are publicised and discovered. The room ID the alias is pointing to can be obtained by visiting the domain specified. Note that the mapping from a room alias to a room ID is not fixed, and may change over time to point to a different room ID. For this reason, Clients SHOULD resolve the room alias to a room ID once and then use that ID on subsequent requests. Room aliases MUST NOT exceed 255 bytes (including the domain).

When resolving a room alias the server will also respond with a list of servers that are in the room that can be used to join via.

     HTTP GET
#matrix:domain.com      !aaabaa:matrix.org
        |                    ^
        |                    |
 _______V____________________|____
|          domain.com            |
| Mappings:                      |
| #matrix >> !aaabaa:matrix.org  |
| #golf   >> !wfeiofh:sport.com  |
| #bike   >> !4rguxf:matrix.org  |
|________________________________|

{
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

{
  "a_request_parameter": "something",
  "another_request_parameter": "something else",
  "auth": {
      "type": "example.type.foo",
      "session", "xxxxxx",
      "example_credential": "verypoorsharedsecret"
  }
}

{
  "completed": [ "example.type.foo" ],
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

{
  "errcode": "M_EXAMPLE_ERROR",
  "error": "Something was wrong"
}

4.1.1.1   Example

At a high level, the requests made for an API call completing an auth flow with three stages will resemble the following diagram:

 _______________________
|       Stage 1         |
| type: "<stage type1>" |
|  ___________________  |
| |_Request_1_________| | <-- Returns "session" key which is used throughout.
|  ___________________  |
| |_Request_2_________| |
|_______________________|
          |
          |
 _________V_____________
|       Stage 2         |
| type: "<stage type2>" |
|  ___________________  |
| |_Request_1_________| |
|  ___________________  |
| |_Request_2_________| |
|  ___________________  |
| |_Request_3_________| |
|_______________________|
          |
          |
 _________V_____________
|       Stage 3         |
| type: "<stage type3>" |
|  ___________________  |
| |_Request_1_________| | <-- Returns API response
|_______________________|

This specification defines the following login types:

• m.login.password
• m.login.recaptcha
• m.login.oauth2
• m.login.email.identity
• m.login.token
• m.login.dummy

4.1.1.2   Password-based

Type:	m.login.password
Description:	The client submits a username and secret password, both sent in plain-text.

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.password",
  "user": "<user_id or user localpart>",
  "password": "<password>"
}

4.1.1.3   Google ReCaptcha

Type:	m.login.recaptcha
Description:	The user completes a Google ReCaptcha 2.0 challenge

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.recaptcha",
  "response": "<captcha response>"
}

4.1.1.4   Token-based

Type:	m.login.token
Description:	The client submits a username and token.

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.token",
  "user": "<user_id or user localpart>",
  "token": "<token>",
  "txn_id": "<client generated nonce>"
}

The nonce should be a random string generated by the client for the request. The same nonce should be used if retrying the request.

There are many ways a client may receive a token, including via an email or from an existing logged in device.

The txn_id may be used by the server to disallow other devices from using the token, thus providing "single use" tokens while still allowing the device to retry the request. This would be done by tying the token to the txn_id server side, as well as potentially invalidating the token completely once the device has successfully logged in (e.g. when we receive a request from the newly provisioned access_token).

The token must be a macaroon.

4.1.1.5   OAuth2-based

Type:	m.login.oauth2
Description:	Authentication is supported via OAuth2 URLs. This login consists of multiple requests.
Parameters:	uri: Authorization Request URI OR service selection URI. Both contain an encoded redirect URI.

The home server acts as a 'confidential' client for the purposes of OAuth2. If the uri is a service selection URI, it MUST point to a webpage which prompts the user to choose which service to authorize with. On selection of a service, this MUST link through to an Authorization Request URI. If there is only one 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 then visits the Authorization Request URI, which then shows the OAuth2 Allow/Deny prompt. Hitting 'Allow' redirects to the redirect URI with the auth code. Home servers can choose any path for the redirect URI. Once the OAuth flow has completed, the client retries the request with the session only, as above.

4.1.1.6   Email-based (identity server)

Type:	m.login.email.identity
Description:	Authentication is supported by authorising an email address with an identity server.

Prior to submitting this, the client should authenticate with an identity server. After authenticating, the session information should be submitted to the home server.

To respond to this type, reply with an auth dict as follows:

{
  "type": "m.login.email.identity",
  "threepidCreds": [
    {
      "sid": "<identity server session id>",
      "client_secret": "<identity server client secret>",
      "id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
    }
  ]
}

4.1.1.7   Dummy Auth

Type:	m.login.dummy
Description:	Dummy authentication always succeeds and requires no extra parameters. Its purpose is to allow servers to not require any form of User-Interactive Authentication to perform a request.

To respond to this type, reply with an auth dict with just the type and session, if provided:

{
  "type": "m.login.dummy",
}

4.1.1.8   Fallback

Clients cannot be expected to be able to know how to process every single login type. If a client does not know how to handle a given login type, it can direct the user to a web browser with the URL of a fallback page which will allow the user to complete that login step out-of-band in their web browser. The URL it should open is the Home Server base URL plus prefix, plus:

/auth/<stage type>/fallback/web?session=<session ID>

Where stage type is the type name of the stage it is attempting and session id is the ID of the session given by the home server.

This MUST return an HTML page which can perform this authentication stage. This page must attempt to call the JavaScript function window.onAuthDone when the authentication has been completed.

4.1.2.1   POST /_matrix/client/api/v2_alpha/register

Register for an account on this homeserver.

There are two kinds of user account:

• user accounts. These accounts may use the full API described in this specification.
• guest accounts. These accounts may have limited permissions and may not be supported by all servers.

Rate-limited:	Yes.

Request format:

Parameter	Type	Description
query parameters
kind	enum	The kind of account to register. Defaults to user. One of: ["guest", "user"]
JSON body parameters
username	string	The local part of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part.
bind_email	boolean	If true, the server binds the email used for authentication to the Matrix ID with the ID Server.
password	string	Required. The desired password for the account.

Response format:

Parameter	Type	Description
access_token	string	An access token for the account. This access token can then be used to authorize other requests. The access token may expire at some point, and if so, it SHOULD come with a refresh_token. There is no specific error message to indicate that a request has failed because an access token has expired; instead, if a client has reason to believe its access token is valid, and it receives an auth error, they should attempt to refresh for a new token on failure, and retry the request with the new token.
home_server	string	The hostname of the Home Server on which the account has been registered.
refresh_token	string	(optional) A refresh_token may be exchanged for a new access_token using the /tokenrefresh API endpoint.
user_id	string	The fully-qualified Matrix ID that has been registered.

Example request:

POST /_matrix/client/api/v2_alpha/register?kind=guest HTTP/1.1
Content-Type: application/json

{
  "username": "cheeky_monkey",
  "password": "ilovebananas",
  "bind_email": false
}

Responses:

Status code 200:

The account has been registered.

Example

{
  "user_id": "@cheeky_monkey:matrix.org",
  "access_token": "abc123",
  "home_server": "matrix.org",
  "refresh_token": "def456"
}

Status code 400:

Part of the request was invalid. This may include one of the following error codes:

• M_USER_IN_USE : The desired user ID is already taken.
• M_EXCLUSIVE : The desired user ID is in the exclusive namespace claimed by an application service.

These errors may be returned at any stage of the registration process, including after authentication if the requested user ID was registered whilst the client was performing authentication.

Home Servers MUST perform the relevant checks and return these codes before performing User-Interactive Authentication, although they may also return them after authentication is completed if, for example, the requested user ID was registered whilst the client was performing authentication.

Example

{
    "errcode": "M_USER_IN_USE",
    "error": "Desired user ID is already taken."
}

Old V1 API docs: /register

4.1.2.2   POST /_matrix/client/api/v1/login

Authenticates the user by password, and issues an access token they can use to authorize themself in subsequent requests.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
JSON body parameters
password	string	Required. The user's password.
type	string	Required. The login type being used. Currently only "m.login.password" is supported.
user	string	Required. The fully qualified user ID or just local part of the user ID, to log in.

Response format:

Parameter	Type	Description
access_token	string	An access token for the account. This access token can then be used to authorize other requests. The access token may expire at some point, and if so, it SHOULD come with a refresh_token. There is no specific error message to indicate that a request has failed because an access token has expired; instead, if a client has reason to believe its access token is valid, and it receives an auth error, they should attempt to refresh for a new token on failure, and retry the request with the new token.
home_server	string	The hostname of the Home Server on which the account has been registered.
refresh_token	string	(optional) A refresh_token may be exchanged for a new access_token using the /tokenrefresh API endpoint.
user_id	string	The fully-qualified Matrix ID that has been registered.

Example request:

POST /_matrix/client/api/v1/login HTTP/1.1
Content-Type: application/json

{
  "type": "m.login.pasword",
  "user": "cheeky_monkey",
  "password": "ilovebananas"
}

Responses:

Status code 200:

The user has been authenticated.

Example

{
  "user_id": "@cheeky_monkey:matrix.org",
  "access_token": "abc123",
  "home_server": "matrix.org"
}

Status code 400:

Part of the request was invalid. For example, the login type may not be recognised.

Example

{
    "errcode": "M_UNKNOWN",
    "error": "Bad login type."
}

Status code 403:

The login attempt failed. For example, the password may have been incorrect.

Example

{"errcode": "M_FORBIDDEN"}

4.1.2.3   POST /_matrix/client/api/v1/tokenrefresh

Exchanges a refresh token for a new access token. This is intended to be used if the access token has expired.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
JSON body parameters
refresh_token	string	Required. The refresh token which was issued by the server.

Response format:

Parameter	Type	Description
access_token	string	An access token for the account. This access token can then be used to authorize other requests. The access token may expire at some point, and if so, it SHOULD come with a refresh_token.
refresh_token	string	(optional) A refresh_token may be exchanged for a new access_token using the TODO Linkify /tokenrefresh API endpoint.

Example request:

POST /_matrix/client/api/v1/tokenrefresh HTTP/1.1
Content-Type: application/json

{
  "refresh_token": "a1b2c3"
}

Responses:

Status code 200:

The refresh token was accepted, and a new access token has been issued. The passed refresh token is no longer valid and cannot be used. A new refresh token will have been returned unless some policy does not allow the user to continue to renew their session.

Example

{
  "access_token": "bearwithme123",
  "refresh_token": "exchangewithme987"
}

Status code 403:

The exchange attempt failed. For example, the refresh token may have already been used.

Example

{"errcode": "M_FORBIDDEN"}

4.1.2.4   Login Fallback

If a client does not recognize any or all login flows it can use the fallback login API:

GET /_matrix/static/client/login/

This returns an HTML and JavaScript page which can perform the entire login process. The page will attempt to call the JavaScript function window.onLogin when login has been successfully completed.

4.1.2.5   Changing Password

Request:

POST $V2PREFIX/account/password

This API endpoint uses the User-Interactive Authentication API. An access token should be submitted to this endpoint if the client has an active session. The Home Server may change the flows available depending on whether a valid access token is provided.

The body of the POST request is a JSON object containing:

new_password

The new password for the account.

On success, an empty JSON object is returned.

The error code M_NOT_FOUND is returned if the user authenticated with a third party identifier but the Home Server could not find a matching account in its database.

4.1.2.6   Adding Account Administrative Contact Information

Request:

POST $V2PREFIX/account/3pid

Used to add contact information to the user's account.

The body of the POST request is a JSON object containing:

threePidCreds

An object containing contact information.

bind

Optional. A boolean indicating whether the Home Server should also bind this third party identifier to the account's matrix ID with the Identity Server. If supplied and true, the Home Server must bind the 3pid accordingly.

The contact information object comprises:

id_server

The colon-separated hostname and port of the Identity Server used to authenticate the third party identifier. If the port is the default, it and the colon should be omitted.

sid

The session ID given by the Identity Server

client_secret

The client secret used in the session with the Identity Server.

On success, the empty JSON object is returned.

May also return error codes:

M_THREEPID_AUTH_FAILED

If the credentials provided could not be verified with the ID Server.

4.1.2.7   Fetching Currently Associated Contact Information

Request:

GET $V2PREFIX/account/3pid

This returns a list of third party identifiers that the Home Server has associated with the user's account. This is not the same as the list of third party identifiers bound to the user's Matrix ID in Identity Servers. Identifiers in this list may be used by the Home Server as, for example, identifiers that it will accept to reset the user's account password.

Returns a JSON object with the key threepids whose contents is an array of objects with the following keys:

medium

The medium of the 3pid (eg, email)

address

The textual address of the 3pid, eg. the email address

4.3.2.1   GET /_matrix/client/api/v1/events

This will listen for new events and return them to the caller. This will block until an event is received, or until the timeout is reached.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
query parameters
from	string	The token to stream from. This token is either from a previous request to this API or from the initial sync API.
timeout	integer	The maximum time in milliseconds to wait for an event.

Response format:

Parameter	Type	Description
chunk	[Event]	An array of events.
end	string	A token which correlates to the last value in chunk. This token should be used in the next request to /events.
start	string	A token which correlates to the first value in chunk. This is usually the same token supplied to from=.

Event

Parameter	Type	Description
event_id	string	The globally unique event identifier.
room_id	string	The ID of the room associated with this event.
user_id	string	Contains the fully-qualified ID of the user who sent this event.

Example request:

GET /_matrix/client/api/v1/events?from=s3456_9_0&timeout=35000 HTTP/1.1

Response:

Status code 200:

The events received, which may be none.

Example

{
  "start": "s3456_9_0",
  "end": "s3457_9_0",
  "chunk": [
    {
      "age": 32,
      "content": {
          "body": "incoming message",
          "msgtype": "m.text"
      },
      "event_id": "$14328055551tzaee:localhost",
      "origin_server_ts": 1432804485886,
      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
      "type": "m.room.message",
      "user_id": "@bob:localhost"
    }
  ]
}

4.3.2.2   GET /_matrix/client/api/v1/events/{eventId}

Get a single event based on event_id. You must have permission to retrieve this event e.g. by being a member in the room for this event.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
eventId	string	Required. The event ID to get.

Example request:

GET /_matrix/client/api/v1/events/%24asfDuShaf7Gafaw%3Amatrix.org HTTP/1.1

Response:

Status code 200:

The full event.

Example

{
  "content": {
    "body": "Hello world!",
    "msgtype": "m.text"
  },
  "room_id:": "!wfgy43Sg4a:matrix.org",
  "user_id": "@bob:matrix.org",
  "event_id": "$asfDuShaf7Gafaw:matrix.org",
  "type": "m.room.message"
}

4.3.2.3   GET /_matrix/client/api/v1/initialSync

This returns the full state for this user, with an optional limit on the number of messages per room to return.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
query parameters
limit	integer	The maximum number of messages to return for each room.
archived	boolean	Whether to include rooms that the user has left. If false then only rooms that the user has been invited to or has joined are included. If set to true then rooms that the user has left are included as well. By default this is false.

Response format:

Parameter	Type	Description
end	string	A token which correlates to the last value in chunk. This token should be used with the /events API to listen for new events.
presence	[Event]	A list of presence events.
rooms	[RoomInfo]

Event

Parameter	Type	Description
content	{EventContent}	The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
type	string	The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. 'com.example.subdomain.event.type'

RoomInfo

Parameter	Type	Description
invite	{InviteEvent}	The invite event if membership is invite
membership	enum	The user's membership state in this room. One of: ["invite", "join", "leave", "ban"]
messages	{PaginationChunk}	The pagination chunk for this room.
room_id	string	The ID of this room.
state	[StateEvent]	If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room this will be the state of the room when they left it.
visibility	enum	Whether this room is visible to the /publicRooms API or not." One of: ["private", "public"]

InviteEvent

Parameter	Type	Description
content	{EventContent}
invite_room_state	[StrippedState]	A subset of the state of the room at the time of the invite, if membership is invite
state_key	string	The user_id this membership event relates to.
type	string	Must be 'm.room.member'.

EventContent

Parameter	Type	Description
avatar_url	string	The avatar URL for this user, if any. This is added by the homeserver.
displayname	string or null	The display name for this user, if any. This is added by the homeserver.
membership	enum	The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"]
third_party_invite	{Invite}

Invite

Parameter	Type	Description
signed	{signed}

signed

Parameter	Type	Description
mxid	string	The invited matrix user ID. Must be equal to the user_id property of the event.
signatures	{Signatures}	A single signature from the verifying server, in the format specified by the Signing Events section.
token	string	The token property of the containing third_party_invite object.

StrippedState

Parameter	Type	Description
content	{EventContent}	The content for the event.
state_key	string	The state_key for the event.
type	enum	The type for the event. One of: ["m.room.join_rules", "m.room.canonical_alias", "m.room.avatar", "m.room.name"]

PaginationChunk

Parameter	Type	Description
chunk	[RoomEvent]	If the user is a member of the room this will be a list of the most recent messages for this room. If the user has left the room this will be the messages that preceeded them leaving. This array will consist of at most limit elements.
end	string	A token which correlates to the last value in chunk. Used for pagination.
start	string	A token which correlates to the first value in chunk. Used for pagination.

RoomEvent

Parameter	Type	Description
event_id	string	The globally unique event identifier.
room_id	string	The ID of the room associated with this event.
user_id	string	Contains the fully-qualified ID of the user who sent this event.

StateEvent

Parameter	Type	Description
prev_content	{EventContent}	Optional. The previous content for this event. If there is no previous content, this key will be missing.
state_key	string	A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.

Example request:

GET /_matrix/client/api/v1/initialSync?limit=2&archived=true HTTP/1.1

Response:

Status code 200:

The user's current state.

Example

{
    "end": "s3456_9_0",
    "presence": [
        {
            "content": {
                "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                "displayname": "Bob",
                "last_active_ago": 31053,
                "presence": "online",
                "user_id": "@bob:localhost"
            },
            "type": "m.presence"
        }
    ],
    "rooms": [
        {
            "membership": "join",
            "messages": {
                "chunk": [
                    {
                        "age": 343513403,
                        "content": {
                            "body": "foo",
                            "msgtype": "m.text"
                        },
                        "event_id": "$14328044851tzTJS:localhost",
                        "origin_server_ts": 1432804485886,
                        "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                        "type": "m.room.message",
                        "user_id": "@alice:localhost"
                    },
                    {
                        "age": 343511809,
                        "content": {
                            "body": "bar",
                            "msgtype": "m.text"
                        },
                        "event_id": "$14328044872spjFg:localhost",
                        "origin_server_ts": 1432804487480,
                        "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                        "type": "m.room.message",
                        "user_id": "@bob:localhost"
                    }
                ],
                "end": "s3456_9_0",
                "start": "t44-3453_9_0"
            },
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "state": [
                {
                    "age": 7148266897,
                    "content": {
                        "join_rule": "public"
                    },
                    "event_id": "$14259997323TLwtb:localhost",
                    "origin_server_ts": 1425999732392,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.join_rules",
                    "user_id": "@alice:localhost"
                },
                {
                    "age": 6547561012,
                    "content": {
                        "avatar_url": "mxc://localhost/fzysBrHpPEeTGANCVLXWXNMI#auto",
                        "displayname": null,
                        "membership": "join"
                    },
                    "event_id": "$1426600438280zExKY:localhost",
                    "membership": "join",
                    "origin_server_ts": 1426600438277,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "@alice:localhost",
                    "type": "m.room.member",
                    "user_id": "@alice:localhost"
                },
                {
                    "age": 7148267200,
                    "content": {
                        "creator": "@alice:localhost"
                    },
                    "event_id": "$14259997320KhbwJ:localhost",
                    "origin_server_ts": 1425999732089,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.create",
                    "user_id": "@alice:localhost"
                },
                {
                    "age": 1622568720,
                    "content": {
                        "avatar_url": "mxc://localhost/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
                        "displayname": "Bob",
                        "membership": "join"
                    },
                    "event_id": "$1431525430134MxlLX:localhost",
                    "origin_server_ts": 1431525430569,
                    "replaces_state": "$142652023736BSXcM:localhost",
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "@bob:localhost",
                    "type": "m.room.member",
                    "user_id": "@bob:localhost"
                },
                {
                    "age": 7148267004,
                    "content": {
                        "ban": 50,
                        "events": {
                            "m.room.name": 100,
                            "m.room.power_levels": 100
                        },
                        "events_default": 0,
                        "kick": 50,
                        "redact": 50,
                        "state_default": 50,
                        "users": {
                            "@alice:localhost": 100
                        },
                        "users_default": 0
                    },
                    "event_id": "$14259997322mqfaq:localhost",
                    "origin_server_ts": 1425999732285,
                    "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
                    "state_key": "",
                    "type": "m.room.power_levels",
                    "user_id": "@alice:localhost"
                }
            ],
            "visibility": "private"
        }
    ]
}

4.3.2.4   GET /_matrix/client/v2_alpha/sync

Synchronise the client's state with the latest state on the server. Clients use this API when they first log in to get an initial snapshot of the state on the server, and then continue to call this API to get incremental deltas to the state, and to receive new messages.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
query parameters
filter	string	The ID of a filter created using the filter API.
since	string	A point in time to continue a sync from.
full_state	boolean	Controls whether to include the full state for all rooms the user is a member of. If this is set to true, then all state events will be returned, even if since is non-empty. The timeline will still be limited by the since parameter. In this case, the timeout parameter will be ignored and the query will return immediately, possibly with an empty timeline. If false, and since is non-empty, only state which has changed since the point indicated by since will be returned. By default, this is false.
set_presence	enum	Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is automatically marked as online when it uses this API. Otherwise if the parameter is set to "offline" then the client is not marked as being online when it uses this API. One of: ["offline"]
timeout	integer	The maximum time to poll in milliseconds before returning this request.

Response format:

Parameter	Type	Description
next_batch	string	The batch token to supply in the since param of the next /sync request.
presence	{Presence}	The updates to the presence status of other users.
rooms	{Rooms}	Updates to rooms.

Presence

Parameter	Type	Description
events	[NO_TITLE]	List of events

NO_TITLE

Parameter	Type	Description
content	{EventContent}	The content of this event. The fields in this object will vary depending on the type of event.
origin_server_ts	integer	Timestamp in milliseconds on originating homeserver when this event was sent.
sender	string	The MXID of the user who sent this event.
state_key	string	Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state.
type	string	The type of event.
unsigned	{Unsigned}	Information about this event which was not sent by the originating homeserver

Unsigned

Parameter	Type	Description
age	integer	Time in milliseconds since the event was sent.
prev_content	{EventContent}	Optional. The previous content for this state. This will be present only for state events appearing in the timeline. If this is not a state event, or there is no previous content, this key will be missing.
replaces_state	string	Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the timeline. If this is not a state event, or there is no previous content, this key will be missing.
transaction_id	string	Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API.

Rooms

Parameter	Type	Description
invite	{string: Invited Room}	The rooms that the user has been invited to.
join	{string: Joined Room}	The rooms that the user has joined.
leave	{string: Left Room}	The rooms that the user has left or been banned from.

Invited Room

Parameter	Type	Description
invite_state	{InviteState}	The state of a room that the user has been invited to. These state events may only have the sender, type, state_key and content keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. Instead the client should keep two separate copies of the state: the one from the invite_state and one from the archived state. If the client joins the room then the current state will be given as a delta against the archived state not the invite_state.

InviteState

Parameter	Type	Description
events	[NO_TITLE]	List of events

Joined Room

Parameter	Type	Description
ephemeral	{Ephemeral}	The ephemeral events in the room that aren't recorded in the timeline or state of the room. e.g. typing.
state	{State}	Updates to the state, between the time indicated by the since parameter, and the start of the timeline (or all state up to the start of the timeline, if since is not given, or full_state is true).
timeline	{Timeline}	The timeline of messages and state changes in the room.

Ephemeral

Parameter	Type	Description
events	[NO_TITLE]	List of events

State

Parameter	Type	Description
events	[NO_TITLE]	List of events

Timeline

Parameter	Type	Description
limited	boolean	True if the number of events returned was limited by the limit on the filter
prev_batch	string	If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events

Left Room

Parameter	Type	Description
state	{State}	The state updates for the room up to the start of the timeline.
timeline	{Timeline}	The timeline of messages and state changes in the room up to the point when the user left.

Example request:

GET /_matrix/client/v2_alpha/sync?filter=66696p746572&since=s72594_4483_1934&full_state=false&set_presence=offline&timeout=30000 HTTP/1.1

Response:

Status code 200:

The initial snapshot or delta for the client to use to update their state.

Example

{
  "next_batch": "s72595_4483_1934",
  "presence": {
    "events": [
      {
        "sender": "@alice:example.com",
        "type": "m.presence",
        "content": {"presence": "online"}
      }
    ]
  },
  "rooms": {
    "join": {
      "!726s6s6q:example.com": {
        "state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@alice:example.com",
              "content": {"membership": "join"},
              "origin_server_ts": 1417731086795,
              "event_id": "$66697273743031:example.com"
            }
          ]
        },
        "timeline": {
          "events": [
            {
              "sender": "@bob:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {"membership": "join"},
              "prev_content": {"membership": "invite"},
              "origin_server_ts": 1417731086795,
              "event_id": "$7365636s6r6432:example.com"
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.message",
              "age": 124524,
              "txn_id": "1234",
              "content": {
                "body": "I am a fish",
                "msgtype": "m.text"
              },
              "origin_server_ts": 1417731086797,
              "event_id": "$74686972643033:example.com"
            }
          ],
          "limited": true,
          "prev_batch": "t34-23535_0_0"
        },
        "ephemeral": {
          "events": [
            {
              "type": "m.typing",
              "content": {"user_ids": ["@alice:example.com"]}
            }
          ]
        }
      }
    },
    "invite": {
      "!696r7674:example.com": {
        "invite_state": {
          "events": [
            {
              "sender": "@alice:example.com",
              "type": "m.room.name",
              "state_key": "",
              "content": {"name": "My Room Name"}
            },
            {
              "sender": "@alice:example.com",
              "type": "m.room.member",
              "state_key": "@bob:example.com",
              "content": {"membership": "invite"}
            }
          ]
        }
      }
    },
    "leave": {}
  }
}

4.3.3.1   GET /_matrix/client/api/v1/rooms/{roomId}/initialSync

Get a copy of the current state and the most recent messages in a room.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to get the data.

Response format:

RoomInfo

Parameter	Type	Description
membership	enum	The user's membership state in this room. One of: ["invite", "join", "leave", "ban"]
messages	{PaginationChunk}	The pagination chunk for this room.
room_id	string	The ID of this room.
state	[StateEvent]	If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room this will be the state of the room when they left it.
visibility	enum	Whether this room is visible to the /publicRooms API or not." One of: ["private", "public"]

PaginationChunk

Parameter	Type	Description
chunk	[RoomEvent]	If the user is a member of the room this will be a list of the most recent messages for this room. If the user has left the room this will be the messages that preceeded them leaving. This array will consist of at most limit elements.
end	string	A token which correlates to the last value in chunk. Used for pagination.
start	string	A token which correlates to the first value in chunk. Used for pagination.

RoomEvent

Parameter	Type	Description
event_id	string	The globally unique event identifier.
room_id	string	The ID of the room associated with this event.
user_id	string	Contains the fully-qualified ID of the user who sent this event.

StateEvent

Parameter	Type	Description
prev_content	{EventContent}	Optional. The previous content for this event. If there is no previous content, this key will be missing.
state_key	string	A unique key which defines the overwriting semantics for this piece of room state. This value is often a zero-length string. The presence of this key makes this event a State Event. The key MUST NOT start with '_'.

Example request:

GET /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/initialSync HTTP/1.1

Response:

Status code 200:

The current state of the room

Example

{
  "membership": "join",
  "messages": {
    "chunk": [
      {
        "age": 343513403,
        "content": {
          "body": "foo",
          "msgtype": "m.text"
        },
        "event_id": "$14328044851tzTJS:example.com",
        "origin_server_ts": 1432804485886,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "user_id": "@alice:example.com"
      },
      {
        "age": 343511809,
        "content": {
          "body": "bar",
          "msgtype": "m.text"
        },
        "event_id": "$14328044872spjFg:example.com",
        "origin_server_ts": 1432804487480,
        "room_id": "!636q39766251:example.com",
        "type": "m.room.message",
        "user_id": "@bob:example.com"
      }
    ],
    "end": "s3456_9_0",
    "start": "t44-3453_9_0"
  },
  "room_id": "!636q39766251:example.com",
  "state": [
    {
      "age": 7148266897,
      "content": {
        "join_rule": "public"
      },
      "event_id": "$14259997323TLwtb:example.com",
      "origin_server_ts": 1425999732392,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.join_rules",
      "user_id": "@alice:example.com"
    },
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "displayname": null,
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "user_id": "@alice:example.com"
    },
    {
      "age": 7148267200,
      "content": {
          "creator": "@alice:example.com"
      },
      "event_id": "$14259997320KhbwJ:example.com",
      "origin_server_ts": 1425999732089,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.create",
      "user_id": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "user_id": "@bob:example.com"
    },
    {
      "age": 7148267004,
      "content": {
        "ban": 50,
        "events": {
          "m.room.name": 100,
          "m.room.power_levels": 100
        },
        "events_default": 0,
        "kick": 50,
        "redact": 50,
        "state_default": 50,
        "users": {
          "@alice:example.com": 100
        },
        "users_default": 0
      },
      "event_id": "$14259997322mqfaq:example.com",
      "origin_server_ts": 1425999732285,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.power_levels",
      "user_id": "@alice:example.com"
    }
  ],
  "visibility": "private"
}

4.3.3.2   GET /_matrix/client/api/v1/rooms/{roomId}/members

Get the list of members for this room.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to get the member events for.

Response format:

Parameter	Type	Description
chunk	[MemberEvent]

MemberEvent

Parameter	Type	Description
content	{EventContent}
invite_room_state	[StrippedState]	A subset of the state of the room at the time of the invite, if membership is invite
state_key	string	The user_id this membership event relates to.
type	string	Must be 'm.room.member'.

EventContent

Parameter	Type	Description
avatar_url	string	The avatar URL for this user, if any. This is added by the homeserver.
displayname	string or null	The display name for this user, if any. This is added by the homeserver.
membership	enum	The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"]
third_party_invite	{Invite}

Invite

Parameter	Type	Description
signed	{signed}

signed

Parameter	Type	Description
mxid	string	The invited matrix user ID. Must be equal to the user_id property of the event.
signatures	{Signatures}	A single signature from the verifying server, in the format specified by the Signing Events section.
token	string	The token property of the containing third_party_invite object.

StrippedState

Parameter	Type	Description
content	{EventContent}	The content for the event.
state_key	string	The state_key for the event.
type	enum	The type for the event. One of: ["m.room.join_rules", "m.room.canonical_alias", "m.room.avatar", "m.room.name"]

Example request:

GET /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/members HTTP/1.1

Response:

Status code 200:

A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left te room then this will be the members of the room when you left.

Example

{
  "chunk": [
    {
      "age": 6547561012,
      "content": {
        "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
        "displayname": null,
        "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "user_id": "@alice:example.com"
    },
    {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "user_id": "@bob:example.com"
    }
  ]
}

4.3.3.3   GET /_matrix/client/api/v1/rooms/{roomId}/state

Get the state events for the current state of a room.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to look up the state for.

Response format:

RoomState

Parameter	Type	Description
N/A	[StateEvent]	If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room then this will be the state of the room when they left as a list of events.

Example request:

GET /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/state HTTP/1.1

Response:

Status code 200:

The current state of the room

Example

[
  {
      "age": 7148266897,
      "content": {
          "join_rule": "public"
      },
      "event_id": "$14259997323TLwtb:example.com",
      "origin_server_ts": 1425999732392,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.join_rules",
      "user_id": "@alice:example.com"
  },
  {
      "age": 6547561012,
      "content": {
          "avatar_url": "mxc://example.com/fzysBrHpPEeTGANCVLXWXNMI#auto",
          "displayname": null,
          "membership": "join"
      },
      "event_id": "$1426600438280zExKY:example.com",
      "membership": "join",
      "origin_server_ts": 1426600438277,
      "room_id": "!636q39766251:example.com",
      "state_key": "@alice:example.com",
      "type": "m.room.member",
      "user_id": "@alice:example.com"
  },
  {
      "age": 7148267200,
      "content": {
          "creator": "@alice:example.com"
      },
      "event_id": "$14259997320KhbwJ:example.com",
      "origin_server_ts": 1425999732089,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.create",
      "user_id": "@alice:example.com"
  },
  {
      "age": 1622568720,
      "content": {
          "avatar_url": "mxc://example.com/GCmhgzMPRjqgpODLsNQzVuHZ#auto",
          "displayname": "Bob",
          "membership": "join"
      },
      "event_id": "$1431525430134MxlLX:example.com",
      "origin_server_ts": 1431525430569,
      "replaces_state": "$142652023736BSXcM:example.com",
      "room_id": "!636q39766251:example.com",
      "state_key": "@bob:example.com",
      "type": "m.room.member",
      "user_id": "@bob:example.com"
  },
  {
      "age": 7148267004,
      "content": {
          "ban": 50,
          "events": {
              "m.room.name": 100,
              "m.room.power_levels": 100
           },
           "events_default": 0,
           "kick": 50,
           "redact": 50,
           "state_default": 50,
           "users": {
               "@alice:example.com": 100
           },
           "users_default": 0
      },
      "event_id": "$14259997322mqfaq:example.com",
      "origin_server_ts": 1425999732285,
      "room_id": "!636q39766251:example.com",
      "state_key": "",
      "type": "m.room.power_levels",
      "user_id": "@alice:example.com"
  }
]

4.3.3.4   GET /_matrix/client/api/v1/rooms/{roomId}/state/{eventType}/{stateKey}

Looks up the contents of a state event in a room. If the user is joined to the room then the state is taken from the current state of the room. If the user has left the room then the state is taken from the state of the room when they left.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to look up the state in.
eventType	string	Required. The type of state to look up.
stateKey	string	Required. The key of the state to look up. Defaults to the empty string.

Example request:

GET /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1

Response:

Status code 200:

The content of the state event.

Example

{"name": "Example room name"}

4.3.3.5   GET /_matrix/client/api/v1/rooms/{roomId}/messages

This API returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to get events from.
query parameters
from	string	Required. The token to start returning events from. This token can be obtained from the initial sync API.
dir	enum	Required. The direction to return events from. One of: ["b", "f"]
limit	integer	The maximum number of events to return. Default: 10.

Response format:

Parameter	Type	Description
chunk	[RoomEvent]	A list of room events.
end	string	The token the pagination ends at. If dir=b this token should be used again to request even earlier events.
start	string	The token to start paginating from. If dir=b this will be the token supplied in from.

Example request:

GET /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/messages?from=s345_678_333&dir=b&limit=3 HTTP/1.1

Response:

Status code 200:

A list of messages with a new token to request more.

Example

{
  "start": "t47429-4392820_219380_26003_2265",
  "end": "t47409-4357353_219380_26003_2265",
  "chunk": [
    {
      "origin_server_ts": 1444812213737,
      "user_id": "@alice:example.com",
      "event_id": "$1444812213350496Caaaa:example.com",
      "content": {
        "body": "hello world",
        "msgtype":"m.text"
      },
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.message",
      "age": 1042
    },
    {
      "origin_server_ts": 1444812194656 ,
      "user_id": "@bob:example.com",
      "event_id": "$1444812213350496Cbbbb:example.com",
      "content": {
        "body": "the world is big",
        "msgtype":"m.text"
      },
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.message",
      "age": 20123
    },
    {
      "origin_server_ts": 1444812163990,
      "user_id": "@bob:example.com",
      "event_id": "$1444812213350496Ccccc:example.com",
      "content": {
        "name": "New room name"
      },
      "prev_content": {
        "name": "Old room name"
      },
      "state_key": "",
      "room_id":"!Xq3620DUiqCaoxq:example.com",
      "type":"m.room.name",
      "age": 50789
    }
  ]
}

4.3.4.1   PUT /_matrix/client/api/v1/rooms/{roomId}/state/{eventType}/{stateKey}

State events can be sent using this endpoint. These events will be overwritten if <room id>, <event type> and <state key> all match. If the state event has an empty state_key, it can be omitted from the path.

Requests to this endpoint cannot use transaction IDs like other PUT paths because they cannot be differentiated from the state_key. Furthermore, POST is unsupported on state paths.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to set the state in
eventType	string	Required. The type of event to send.
stateKey	string	Required. The state_key for the state to send. Defaults to the empty string.

Response format:

Parameter	Type	Description
event_id	string	A unique identifier for the event.

Example request:

PUT /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1
Content-Type: application/json

{
    "name": "New name for the room"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

Examples

Valid requests look like:

PUT /rooms/!roomid:domain/state/m.example.event
{ "key" : "without a state key" }

PUT /rooms/!roomid:domain/state/m.another.example.event/foo
{ "key" : "with 'foo' as the state key" }

In contrast, these requests are invalid:

POST /rooms/!roomid:domain/state/m.example.event/
{ "key" : "cannot use POST here" }

PUT /rooms/!roomid:domain/state/m.another.example.event/foo/11
{ "key" : "txnIds are not supported" }

Care should be taken to avoid setting the wrong state key:

PUT /rooms/!roomid:domain/state/m.another.example.event/11
{ "key" : "with '11' as the state key, but was probably intended to be a txnId" }

The state_key is often used to store state about individual users, by using the user ID as the state_key value. For example:

PUT /rooms/!roomid:domain/state/m.favorite.animal.event/%40my_user%3Adomain.com
{ "animal" : "cat", "reason": "fluffy" }

In some cases, there may be no need for a state_key, so it can be omitted:

PUT /rooms/!roomid:domain/state/m.room.bgd.color
{ "color": "red", "hex": "#ff0000" }

4.3.4.2   POST /_matrix/client/api/v1/rooms/{roomId}/send/{eventType}

This endpoint can be used to send a message event to a room; however the lack of a transaction ID means that it is possible to cause message duplication if events are resent on error, so it is preferable to use PUT /_matrix/client/api/v1/rooms/{roomId}/send/{eventType}/{txnId}.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to send the event to.
eventType	string	Required. The type of event to send.

Response format:

Parameter	Type	Description
event_id	string	A unique identifier for the event.

Example request:

POST /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/send/m.room.message HTTP/1.1
Content-Type: application/json

{
  "msgtype": "m.text",
  "body": "hello"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

4.3.4.3   PUT /_matrix/client/api/v1/rooms/{roomId}/send/{eventType}/{txnId}

This endpoint is used to send a message event to a room. Message events allow access to historical events and pagination, making them suited for "once-off" activity in a room.

The body of the request should be the content object of the event; the fields in this object will vary depending on the type of event. See Room Events for the m. event specification.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room to send the event to.
eventType	string	Required. The type of event to send.
txnId	string	Required. The transaction ID for this event. Clients should generate a unique ID; it will be used by the server to ensure idempotency of requests.

Response format:

Parameter	Type	Description
event_id	string	A unique identifier for the event.

Example request:

PUT /_matrix/client/api/v1/rooms/%21636q39766251%3Aexample.com/send/m.room.message/35 HTTP/1.1
Content-Type: application/json

{
  "msgtype": "m.text",
  "body": "hello"
}

Response:

Status code 200:

An ID for the sent event.

Example

{
    "event_id": "YUwRidLecu"
}

4.4.1.1   POST /_matrix/client/api/v1/createRoom

Create a new room with various configuration options.

Requires auth:	Yes.

Request format:

Parameter	Type	Description
JSON body parameters
invite	array[string]	A list of user IDs to invite to the room. This will tell the server to invite everyone in the list to the newly created room.
room_alias_name	string	The desired room alias local part. If this is included, a room alias will be created and mapped to the newly created room. The alias will belong on the same home server which created the room. For example, if this was set to "foo" and sent to the homeserver "example.com" the complete room alias would be #foo:example.com.
visibility	string	A public visibility indicates that the room will be shown in the published room list. A private visibility will hide the room from the published room list. Rooms default to private visibility if this key is not included. NB: This should not be confused with join_rules which also uses the word public.
topic	string	If this is included, an m.room.topic event will be sent into the room to indicate the topic for the room. See Room Events for more information on m.room.topic.
preset	string	Convenience parameter for setting various default state events based on a preset. Must be either: private_chat => join_rules is set to invite. history_visibility is set to shared. trusted_private_chat => join_rules is set to invite. history_visibility is set to shared. All invitees are given the same power level as the room creator. public_chat: => join_rules is set to public. history_visibility is set to shared.
creation_content	object	Extra keys to be added to the content of the m.room.create. The server will clober the following keys: creator. Future versions of the specification may allow the server to clobber other keys.
initial_state	array[object]	A list of state events to set in the new room. This allows the user to override the default state events set in the new room. The expected format of the state events are an object with type, state_key and content keys set. Takes precedence over events set by presets, but gets overriden by name and topic keys.
initial_state[0].content	string
initial_state[0].state_key	string
initial_state[0].type	string
name	string	If this is included, an m.room.name event will be sent into the room to indicate the name of the room. See Room Events for more information on m.room.name.

Response format:

Parameter	Type	Description
room_id	string	The created room's ID.

Example request:

POST /_matrix/client/api/v1/createRoom HTTP/1.1
Content-Type: application/json

{
  "preset": "public_chat",
  "room_alias_name": "thepub",
  "name": "The Grand Duke Pub",
  "topic": "All about happy hour",
  "creation_content": {
      "m.federate": false
  }
}

Response:

Status code 200:

Information about the newly created room.

Example

{
  "room_id": "!sefiuhWgwghwWgh:example.com"
}

4.4.4.1   POST /_matrix/client/api/v1/rooms/{roomId}/invite

Note that there are two forms of this API, which are documented separately. This version of the API requires that the inviter knows the Matrix identifier of the invitee. The other is documented in the third party invites section.

This API invites a user to participate in a particular room. They do not start participating in the room until they actually join the room.

Only users currently in a particular room can invite other users to join that room.

If the user was invited to the room, the home server will append a m.room.member event to the room.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room identifier (not alias) to which to invite the user.
JSON body parameters
user_id	string	Required. The fully qualified user ID of the invitee.

Example request:

POST /_matrix/client/api/v1/rooms/%21d41d8cd%3Amatrix.org/invite  HTTP/1.1
Content-Type: application/json

{
  "user_id": "@cheeky_monkey:matrix.org"
}

Responses:

Status code 200:

The user has been invited to join the room.

Example

{}

Status code 403:

You do not have permission to invite the user to the room. A meaningful errcode and description error text will be returned. Example reasons for rejections are:

• The invitee has been banned from the room.
• The invitee is already a member of the room.
• The inviter is not currently in the room.
• The inviter's power level is insufficient to invite users to the room.

Example

{"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"}

4.4.4.2   POST /_matrix/client/api/v1/rooms/{roomId}/join

This API starts a user participating in a particular room, if that user is allowed to participate in that room. After this call, the client is allowed to see all current state events in the room, and all subsequent events associated with the room until the user leaves the room.

After a user has joined a room, the room will appear as an entry in the response of the /initialSync API.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room identifier or room alias to join.

Example request:

POST /_matrix/client/api/v1/rooms/%23monkeys%3Amatrix.org/join HTTP/1.1

Responses:

Status code 200:

The room has been joined.

The joined room ID must be returned in the room_id field.

Example

{"room_id": "!d41d8cd:matrix.org"}

Status code 403:

You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are:

• The room is invite-only and the user was not invited.
• The user has been banned from the room.

Example

{"errcode": "M_FORBIDDEN", "error": "You are not invited to this room."}

4.4.4.3   POST /join/{roomId}

/join/{roomId} is an alias for /_matrix/client/api/v1/rooms/{roomId}/join.

4.4.5.1   POST /_matrix/client/api/v1/rooms/{roomId}/forget

This API stops a user remembering about a particular room.

In general, history is a first class citizen in Matrix. After this API is called, however, a user will no longer be able to retrieve history for this room. If all users on a homeserver forget a room, the room is eligible for deletion from that homeserver.

If the user is currently joined to the room, they will implicitly leave the room as part of this API call.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room identifier to forget.

Example request:

POST /_matrix/client/api/v1/rooms/%21au1ba7o%3Amatrix.org/forget HTTP/1.1

Response:

Status code 200:

The room has been forgotten.

Example

{}

4.4.5.2   POST /_matrix/client/api/v1/rooms/{roomId}/leave

This API stops a user participating in a particular room.

If the user was already in the room, they will no longer be able to see new events in the room. If the room requires an invite to join, they will need to be re-invited before they can re-join.

If the user was invited to the room, but had not joined, this call serves to reject the invite.

The user will still be allowed to retrieve history from the room which they were previously allowed to see.

Rate-limited:	Yes.
Requires auth:	Yes.

Request format:

Parameter	Type	Description
path parameters
roomId	string	Required. The room identifier to leave.

Example request:

POST /_matrix/client/api/v1/rooms/%21nkl290a%3Amatrix.org/leave HTTP/1.1

Response:

Status code 200:

The room has been left.

Example

{}

4.4.7.1   GET /_matrix/client/api/v1/publicRooms

Lists the public rooms on the server.

This API returns paginated responses.

Request format:

No parameters

Response format:

Parameter	Type	Description
chunk	[PublicRoomsChunk]	A paginated chunk of public rooms.
end	string	A pagination token for the response.
start	string	A pagination token for the response.

PublicRoomsChunk

Parameter	Type	Description
aliases	[string]	Aliases of the room. May be empty.
guest_can_join	boolean	Whether guest users may join the room and participate in it. If they can, they will be subject to ordinary power level rules like any other user.
name	string	The name of the room, if any. May be null.
num_joined_members	number	The number of members joined to the room.
room_id	string	The ID of the room.
topic	string	The topic of the room, if any. May be null.
world_readable	boolean	Whether the room may be viewed by guest users without joining.

Example request:

GET /_matrix/client/api/v1/publicRooms HTTP/1.1

Response:

Status code 200:

A list of the rooms on the server.

Example

{
  "chunk": [
    {
      "aliases": ["#murrays:cheese.bar"],
      "guest_can_join": false,
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "start": "p190q",
  "end": "p1902"
}

4.7.6.1   m.room.aliases

State Event

state_key: The homeserver domain which owns these room aliases.

This event is sent by a homeserver directly to inform of changes to the list of aliases it knows about for that room. The state_key for this event is set to the homeserver which owns the room alias. The entire set of known aliases for the room is the union of all the m.room.aliases events, one for each homeserver. Clients should check the validity of any room alias given in this list before presenting it to the user as trusted fact. The lists given by this event should be considered simply as advice on which aliases might exist, for which the client can perform the lookup to confirm whether it receives the correct room ID.

Content Key	Type	Description
aliases	[string]	A list of room aliases.

Example:

{
    "age": 242352,
    "content": {
        "aliases": [
            "#somewhere:localhost",
            "#another:localhost"
        ]
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "localhost",
    "type": "m.room.aliases",
    "user_id": "@example:localhost"
}

4.7.6.2   m.room.canonical_alias

State Event

state_key: A zero-length string.

This event is used to inform the room about which alias should be considered the canonical one. This could be for display purposes or as suggestion to users which alias to use to advertise the room.

Content Key	Type	Description
alias	string	The canonical alias.

Example:

{
    "age": 242352,
    "content": {
        "alias": "#somewhere:localhost"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "",
    "type": "m.room.canonical_alias",
    "user_id": "@example:localhost"
}

4.7.6.3   m.room.create

State Event

state_key: A zero-length string.

This is the first event in a room and cannot be changed. It acts as the root of all other events.

Content Key	Type	Description
creator	string	The user_id of the room creator. This is set by the homeserver.
m.federate	boolean	Whether users on other servers can join this room. Defaults to true if key does not exist.

Example:

{
    "age": 242352,
    "content": {
        "creator": "@example:localhost"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "",
    "type": "m.room.create",
    "user_id": "@example:localhost"
}

4.7.6.4   m.room.join_rules

State Event

state_key: A zero-length string.

A room may be public meaning anyone can join the room without any prior action. Alternatively, it can be invite meaning that a user who wishes to join the room must first receive an invite to the room from someone already inside of the room. Currently, knock and private are reserved keywords which are not implemented.

Content Key	Type	Description
join_rule	enum	The type of rules used for users wishing to join this room. One of: ["public", "knock", "invite", "private"]

Example:

{
    "age": 242352,
    "content": {
        "join_rule": "public"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "",
    "type": "m.room.join_rules",
    "user_id": "@example:localhost"
}

4.7.6.5   m.room.member

State Event

state_key: The user_id this membership event relates to.

Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (/rooms/<room id>/invite etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.

The third_party_invite property will be set if this invite is an invite event and is the successor of an m.room.third_party_invite event, and absent otherwise.

This event may also include an invite_room_state key outside the content key. If present, this contains an array of StrippedState Events. These events provide information on a few select state events such as the room name. EventContent

EventContent Key	Type	Description
avatar_url	string	The avatar URL for this user, if any. This is added by the homeserver.
displayname	string or null	The display name for this user, if any. This is added by the homeserver.
membership	enum	The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"]
third_party_invite	{Invite}

Invite

Invite Key	Type	Description
signed	{signed}

signed

signed Key	Type	Description
mxid	string	The invited matrix user ID. Must be equal to the user_id property of the event.
signatures	{Signatures}	A single signature from the verifying server, in the format specified by the Signing Events section.
token	string	The token property of the containing third_party_invite object.

StrippedState

StrippedState Key	Type	Description
content	{EventContent}	The content for the event.
state_key	string	The state_key for the event.
type	enum	The type for the event. One of: ["m.room.join_rules", "m.room.canonical_alias", "m.room.avatar", "m.room.name"]

Example:

{
    "age": 242352,
    "content": {
        "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF#auto",
        "displayname": "Alice Margatroid",
        "membership": "join"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "invite_room_state": [
        {
            "content": {
                "name": "Forest of Magic"
            },
            "state_key": "",
            "type": "m.room.name"
        },
        {
            "content": {
                "join_rules": "invite"
            },
            "state_key": "",
            "type": "m.room.join_rules"
        }
    ],
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "@alice:localhost",
    "type": "m.room.member",
    "user_id": "@example:localhost"
}

4.7.6.6   m.room.power_levels

State Event

state_key: A zero-length string.

This event specifies the minimum level a user must have in order to perform a certain action. It also specifies the levels of each user in the room. If a user_id is in the users list, then that user_id has the associated power level. Otherwise they have the default level users_default. If users_default is not supplied, it is assumed to be 0. The level required to send a certain event is governed by events, state_default and events_default. If an event type is specified in events, then the user must have at least the level specified in order to send that event. If the event type is not supplied, it defaults to events_default for Message Events and state_default for State Events.

Content Key	Type	Description
ban	number	The level required to ban a user.
events	{string: number}	The level required to send specific event types. This is a mapping from event type to power level required.
events_default	number	The default level required to send message events. Can be overridden by the events key.
kick	number	The level required to kick a user.
redact	number	The level required to redact an event.
state_default	number	The default level required to send state events. Can be overridden by the events key.
users	{string: number}	The power levels for specific users. This is a mapping from user_id to power level for that user.
users_default	number	The default power level for every user in the room, unless their user_id is mentioned in the users key.

Example:

{
    "age": 242352,
    "content": {
        "ban": 50,
        "events": {
            "m.room.name": 100,
            "m.room.power_levels": 100
        },
        "events_default": 0,
        "kick": 50,
        "redact": 50,
        "state_default": 50,
        "users": {
            "@example:localhost": 100
        },
        "users_default": 0
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "",
    "type": "m.room.power_levels",
    "user_id": "@example:localhost"
}

4.7.6.7   m.room.redaction

Message Event

Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the redacts event level key.

Content Key	Type	Description
reason	string	The reason for the redaction, if any.

Example:

{
    "age": 242352,
    "content": {
        "reason": "Spamming"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "redacts": "!fukweghifu23:localhost",
    "room_id": "!Cuyf34gef24t:localhost",
    "type": "m.room.redaction",
    "user_id": "@example:localhost"
}

import json

def canonical_json(value):
    return json.dumps(
        value,
        # Encode code-points outside of ASCII as UTF-8 rather than \u escapes
        ensure_ascii=False,
        # Remove unnecessary white space.
        separators=(',',':'),
        # Sort the keys of dictionaries.
        sort_keys=True,
        # Encode the resulting unicode as UTF-8 bytes.
    ).encode("UTF-8")

4.8.1.1   Grammar

Adapted from the grammar in http://tools.ietf.org/html/rfc7159 removing insignificant whitespace, fractions, exponents and redundant character escapes

value     = false / null / true / object / array / number / string
false     = %x66.61.6c.73.65
null      = %x6e.75.6c.6c
true      = %x74.72.75.65
object    = %x7B [ member *( %x2C member ) ] %7D
member    = string %x3A value
array     = %x5B [ value *( %x2C value ) ] %5B
number    = [ %x2D ] int
int       = %x30 / ( %x31-39 *digit )
digit     = %x30-39
string    = %x22 *char %x22
char      = unescaped / %x5C escaped
unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
escaped   = %x22 ; "    quotation mark  U+0022
          / %x5C ; \    reverse solidus U+005C
          / %x62 ; b    backspace       U+0008
          / %x66 ; f    form feed       U+000C
          / %x6E ; n    line feed       U+000A
          / %x72 ; r    carriage return U+000D
          / %x74 ; t    tab             U+0009
          / %x75.30.30.30 (%x30-37 / %x62 / %x65-66) ; u000X
          / %x75.30.30.31 (%x30-39 / %x61-66)        ; u001X

4.8.2.1   Signing Details

JSON is signed by encoding the JSON object without signatures or keys grouped as unsigned, using the canonical encoding described above. The JSON bytes are then signed using the signature algorithm and the signature encoded using base64 with the padding stripped. The resulting base64 signature is added to an object under the signing key identifier which is added to the signatures object under the name of the server signing it which is added back to the original JSON object along with the unsigned object.

The signing key identifier is the concatenation of the signing algorithm and a key version. The signing algorithm identifies the algorithm used to sign the JSON. The currently support value for signing algorithm is ed25519 as implemented by NACL (http://nacl.cr.yp.to/). The key version is used to distinguish between different signing keys used by the same entity.

The unsigned object and the signatures object are not covered by the signature. Therefore intermediate servers can add unsigned data such as timestamps and additional signatures.

{
   "name": "example.org",
   "signing_keys": {
     "ed25519:1": "XSl0kuyvrXNj6A+7/tkrB9sxSbRi08Of5uRhxOqZtEQ"
   },
   "unsigned": {
      "age_ts": 922834800000
   },
   "signatures": {
      "example.org": {
         "ed25519:1": "s76RUgajp8w172am0zQb/iPTHsRnb4SkrzGoeCOSFfcBY2V/1c8QfrmdXHpvnc2jK5BD1WiJIxiMW95fMjK7Bw"
      }
   }
}

def sign_json(json_object, signing_key, signing_name):
    signatures = json_object.pop("signatures", {})
    unsigned = json_object.pop("unsigned", None)

    signed = signing_key.sign(encode_canonical_json(json_object))
    signature_base64 = encode_base64(signed.signature)

    key_id = "%s:%s" % (signing_key.alg, signing_key.version)
    signatures.setdefault(signing_name, {})[key_id] = signature_base64

    json_object["signatures"] = signatures
    if unsigned is not None:
        json_object["unsigned"] = unsigned

    return json_object

4.8.2.2   Checking for a Signature

To check if an entity has signed a JSON object a server does the following

1. Checks if the signatures object contains an entry with the name of the entity. If the entry is missing then the check fails.
2. Removes any signing key identifiers from the entry with algorithms it doesn't understand. If there are no signing key identifiers left then the check fails.
3. Looks up verification keys for the remaining signing key identifiers either from a local cache or by consulting a trusted key server. If it cannot find a verification key then the check fails.
4. Decodes the base64 encoded signature bytes. If base64 decoding fails then the check fails.
5. Checks the signature bytes using the verification key. If this fails then the check fails. Otherwise the check succeeds.

5.1.2.1   Stand-alone web (Web)

This is a web page which heavily uses Matrix for communication. Single-page web apps would be classified as a stand-alone web client, as would multi-page web apps which use Matrix on nearly every page.

5.1.2.2   Mobile (Mobile)

This is a Matrix client specifically designed for consumption on mobile devices. This is typically a mobile app but need not be so provided the feature set can be reached (e.g. if a mobile site could display push notifications it could be classified as a mobile client).

5.1.2.3   Desktop (Desktop)

This is a native GUI application which can run in its own environment outside a browser.

5.1.2.4   Command Line Interface (CLI)

This is a client which is used via a text-based terminal.

5.1.2.5   Embedded (Embedded)

This is a client which is embedded into another application or an embedded device.

5.2.1.1   m.room.message

Message Event

This event is used when sending messages in a room. Messages are not limited to be text. The msgtype key outlines the type of message, e.g. text, audio, image, video, etc. The body key is text and MUST be used with every kind of msgtype as a fallback mechanism for when a client cannot render a message. This allows clients to display something even if it is just plain text. For more information on msgtypes, see m.room.message msgtypes.

Content Key	Type	Description
body	string	The textual representation of this message.
msgtype	string	The type of message, e.g. m.image, m.text

Example:

{
    "age": 242352,
    "content": {
        "body": "This is an example text message",
        "msgtype": "m.text"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "type": "m.room.message",
    "user_id": "@example:localhost"
}

5.2.1.2   m.room.message.feedback

Message Event

NB: Usage of this event is discouraged in favour of the receipts module. Most clients will not recognise this event. Feedback events are events sent to acknowledge a message in some way. There are two supported acknowledgements: delivered (sent when the event has been received) and read (sent when the event has been observed by the end-user). The target_event_id should reference the m.room.message event being acknowledged.

Content Key	Type	Description
target_event_id	string	The event that this feedback is related to.
type	enum	The type of feedback. One of: ["delivered", "read"]

Example:

{
    "age": 242352,
    "content": {
        "target_event_id": "$WEIGFHFW:localhost",
        "type": "delivered"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "type": "m.room.message.feedback",
    "user_id": "@example:localhost"
}

Usage of this event is discouraged for several reasons:

• The number of feedback events will grow very quickly with the number of users in the room. This event provides no way to "batch" feedback, unlike the receipts module.
• Pairing feedback to messages gets complicated when paginating as feedback arrives before the message it is acknowledging.
• There are no guarantees that the client has seen the event ID being acknowledged.

5.2.1.3   m.room.name

State Event

state_key: A zero-length string.

A room has an opaque room ID which is not human-friendly to read. A room alias is human-friendly, but not all rooms have room aliases. The room name is a human-friendly string designed to be displayed to the end-user. The room name is not unique, as multiple rooms can have the same room name set. The room name can also be set when creating a room using /createRoom with the name key.

Content Key	Type	Description
name	string	The name of the room. This MUST NOT exceed 255 bytes.

Example:

{
    "age": 242352,
    "content": {
        "name": "The room name"
    },
    "event_id": "$WLGTSEFSEF:localhost",
    "origin_server_ts": 1431961217939,
    "room_id": "!Cuyf34gef24t:localhost",
    "state_key": "",
    "type": "m.room.name",
    "user_id": "@example:localhost"
}