You're looking at an old version of this specification. To view the current version, please click here.

Client-Server API

{{unstable_warning_block_CLIENT_RELEASE_LABEL}}

The client-server API provides a simple lightweight API to let clients send messages, control rooms and synchronise conversation history. It is designed to support both lightweight clients which store no state and lazy-load data from the server as required - as well as heavyweight clients which maintain a full local persistent copy of server state.

Changelog

Version: %CLIENT_RELEASE_LABEL%

{{client_server_changelog}}

This version of the specification is generated from matrix-doc as of Git commit {{git_version}}.

For the full historical changelog, see https://github.com/matrix-org/matrix-doc/blob/master/changelogs/client_server.rst

Other versions of this specification

The following other versions are also available, in reverse chronological order:

API Standards

The mandatory baseline for client-server communication in Matrix is exchanging JSON objects over HTTP APIs. HTTPS is recommended for communication, although HTTP may be supported as a fallback to support basic HTTP clients. More efficient optional transports will in future be supported as optional extensions - e.g. a packed binary encoding over stream-cipher encrypted TCP socket for low-bandwidth/low-roundtrip mobile usage. For the default HTTP transport, all API calls use a Content-Type of application/json. In addition, all strings MUST be encoded as UTF-8. Clients are authenticated using opaque access_token strings (see Client Authentication for details), passed as a query string parameter on all requests.

The names of the API endpoints for the HTTP transport follow a convention of using underscores to separate words (for example /delete_devices). The key names in JSON objects passed over the API also follow this convention.

Note

There are a few historical exceptions to this rule, such as /createRoom. A future version of this specification will address the inconsistency.

Any errors which occur at the Matrix API level MUST return a “standard error response”. This is a JSON object which looks like:

{
  "errcode": "<error code>",
  "error": "<error message>"
}

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 _ to ease separating the namespace from the error code. 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 MUST always be present.

Errors are generally best expressed by their error code rather than the HTTP status code returned. When encountering the error code M_UNKNOWN, clients should prefer the HTTP status code as a more reliable reference for what the issue was. For example, if the client receives an error code of M_NOT_FOUND but the request gave a 400 Bad Request status code, the client should treat the error as if the resource was not found. However, if the client were to receive an error code of M_UNKNOWN with a 400 Bad Request, the client should assume that the request being made was invalid.

The common error codes are:

M_FORBIDDEN
Forbidden access, e.g. joining a room without permission, failed login.

M_UNKNOWN_TOKEN
The access token specified was not recognised.

An additional response parameter, soft_logout, might be present on the response for 401 HTTP status codes. See the soft logout section for more information.

M_MISSING_TOKEN
No access token was specified for the request.

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.

M_LIMIT_EXCEEDED
Too many requests have been sent in a short period of time. Wait a while then try again.

M_UNKNOWN
An unknown error has occurred.

Other error codes the client might encounter are:

M_UNRECOGNIZED
The server did not understand the request.

M_UNAUTHORIZED
The request was not correctly authorized. Usually due to login failures.

M_USER_DEACTIVATED
The user ID associated with the request has been deactivated. Typically for endpoints that prove authentication, such as /login.

M_USER_IN_USE
Encountered when trying to register a user ID which has been taken.

M_INVALID_USERNAME
Encountered when trying to register a user ID which is not valid.

M_ROOM_IN_USE
Sent when the room alias given to the createRoom API is already in use.

M_INVALID_ROOM_STATE
Sent when the initial state given to the createRoom API is invalid.

M_THREEPID_IN_USE
Sent when a threepid given to an API cannot be used because the same threepid is already in use.

M_THREEPID_NOT_FOUND
Sent when a threepid given to an API cannot be used because no record matching the threepid was found.

M_THREEPID_AUTH_FAILED
Authentication could not be performed on the third party identifier.

M_THREEPID_DENIED
The server does not permit this third party identifier. This may happen if the server only permits, for example, email addresses from a particular domain.

M_SERVER_NOT_TRUSTED
The client’s request used a third party server, eg. identity server, that this server does not trust.

M_UNSUPPORTED_ROOM_VERSION
The client’s request to create a room used a room version that the server does not support.

M_INCOMPATIBLE_ROOM_VERSION
The client attempted to join a room that has a version the server does not support. Inspect the room_version property of the error response for the room’s version.

M_BAD_STATE
The state change requested cannot be performed, such as attempting to unban a user who is not banned.

M_GUEST_ACCESS_FORBIDDEN
The room or resource does not permit guests to access it.

M_CAPTCHA_NEEDED
A Captcha is required to complete the request.

M_CAPTCHA_INVALID
The Captcha provided did not match what was expected.

M_MISSING_PARAM
A required parameter was missing from the request.

M_INVALID_PARAM
A parameter that was specified has the wrong value. For example, the server expected an integer and instead received a string.

M_TOO_LARGE
The request or entity was too large.

M_EXCLUSIVE
The resource being requested is reserved by an application service, or the application service making the request has not created the resource.

M_RESOURCE_LIMIT_EXCEEDED
The request cannot be completed because the homeserver has reached a resource limit imposed on it. For example, a homeserver held in a shared hosting environment may reach a resource limit if it starts using too much memory or disk space. The error MUST have an admin_contact field to provide the user receiving the error a place to reach out to. Typically, this error will appear on routes which attempt to modify state (eg: sending messages, account data, etc) and not routes which only read state (eg: /sync, get account data, etc).

M_CANNOT_LEAVE_SERVER_NOTICE_ROOM
The user is unable to reject an invite to join the server notices room. See the Server Notices module for more information.

The client-server API typically uses HTTP PUT to submit requests with a client-generated transaction identifier. This means that these requests are idempotent. The scope of a transaction identifier is a particular access token. It only serves to identify new requests from retransmits. After the request has finished, the {txnId} value should be changed (how is not specified; a monotonically increasing integer is recommended).

Some API endpoints may allow or require the use of POST requests without a transaction ID. Where this is optional, the use of a PUT request is strongly recommended.

GET /_matrix/client/versions


Gets the versions of the specification supported by the server.

Values will take the form rX.Y.Z.

Only the latest Z value will be reported for each supported X.Y value. i.e. if the server implements r0.0.0, r0.0.1, and r1.2.0, it will report r0.0.1 and r1.2.0.

The server may additionally advertise experimental features it supports through unstable_features. These features should be namespaced and may optionally include version information within their name if desired. Features listed here are not for optionally toggling parts of the Matrix specification and should only be used to advertise support for a feature which has not yet landed in the spec. For example, a feature currently undergoing the proposal process may appear here and eventually be taken off this list once the feature lands in the spec and the server deems it reasonable to do so. Servers may wish to keep advertising features here after they've been released into the spec to give clients a chance to upgrade appropriately. Additionally, clients should avoid using unstable features in their stable releases.

Rate-limited: No
Requires authentication: No

Request

No request parameters or request body.

Responses

Status Description
200 The versions supported by the server.

200 response body

Name Type Description
unstable_features object Experimental features the server supports. Features not listed here, or the lack of this property all together, indicate that a feature is not supported.
versions [string] Required: The supported versions.

200 response body example

{
  "unstable_features": {
    "org.example.my_feature": true
  },
  "versions": [
    "r0.0.1"
  ]
}

Web Browser Clients

It is realistic to expect that some clients will be written to be run within a web browser or similar environment. In these cases, the homeserver should respond to pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all requests.

Servers MUST expect that clients will approach them with OPTIONS requests, allowing clients to discover the CORS headers. All endpoints in this specification s upport the OPTIONS method, however the server MUST NOT perform any logic defined for the endpoints when approached with an OPTIONS request.

When a client approaches the server with a request, the server should respond with the CORS headers for that route. The recommended CORS headers to be returned by servers on all requests are:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization

Server Discovery

In order to allow users to connect to a Matrix server without needing to explicitly specify the homeserver’s URL or other parameters, clients SHOULD use an auto-discovery mechanism to determine the server’s URL based on a user’s Matrix ID. Auto-discovery should only be done at login time.

In this section, the following terms are used with specific meanings:

PROMPT
Retrieve the specific piece of information from the user in a way which fits within the existing client user experience, if the client is inclined to do so. Failure can take place instead if no good user experience for this is possible at this point.

IGNORE
Stop the current auto-discovery mechanism. If no more auto-discovery mechanisms are available, then the client may use other methods of determining the required parameters, such as prompting the user, or using default values.

FAIL_PROMPT
Inform the user that auto-discovery failed due to invalid/empty data and PROMPT for the parameter.

FAIL_ERROR
Inform the user that auto-discovery did not return any usable URLs. Do not continue further with the current login process. At this point, valid data was obtained, but no server is available to serve the client. No further guess should be attempted and the user should make a conscientious decision what to do next.

Well-known URI

Note

Servers hosting the .well-known JSON file SHOULD offer CORS headers, as per the CORS section in this specification.

The .well-known method uses a JSON file at a predetermined location to specify parameter values. The flow for this method is as follows:

  1. Extract the server name from the user’s Matrix ID by splitting the Matrix ID at the first colon.
  2. Extract the hostname from the server name.
  3. Make a GET request to https://hostname/.well-known/matrix/client.
    1. If the returned status code is 404, then IGNORE.
    2. If the returned status code is not 200, or the response body is empty, then FAIL_PROMPT.
    3. Parse the response body as a JSON object
      1. If the content cannot be parsed, then FAIL_PROMPT.
    4. Extract the base_url value from the m.homeserver property. This value is to be used as the base URL of the homeserver.
      1. If this value is not provided, then FAIL_PROMPT.
    5. Validate the homeserver base URL:
      1. Parse it as a URL. If it is not a URL, then FAIL_ERROR.
      2. Clients SHOULD validate that the URL points to a valid homeserver before accepting it by connecting to the /_matrix/client/versions_ endpoint, ensuring that it does not return an error, and parsing and validating that the data conforms with the expected response format. If any step in the validation fails, then FAIL_ERROR. Validation is done as a simple check against configuration errors, in order to ensure that the discovered address points to a valid homeserver.
    6. If the m.identity_server property is present, extract the base_url value for use as the base URL of the identity server. Validation for this URL is done as in the step above, but using /_matrix/identity/api/v1 as the endpoint to connect to. If the m.identity_server property is present, but does not have a base_url value, then FAIL_ERROR.

GET /.well-known/matrix/client


Gets discovery information about the domain. The file may include additional keys, which MUST follow the Java package naming convention, e.g. ``com.example.myapp.property``. This ensures property names are suitably namespaced for each application and reduces the risk of clashes.

Note that this endpoint is not necessarily handled by the homeserver, but by another webserver, to be used for discovering the homeserver URL.

Rate-limited: No
Requires authentication: No

Request

No request parameters or request body.

Responses

Status Description
200 Server discovery information.
404 No server discovery information available.

200 response body

Discovery Information
Name Type Description
m.homeserver Homeserver Information Required: Used by clients to discover homeserver information.
m.identity_server Identity Server Information Used by clients to discover identity server information.
Homeserver Information
Name Type Description
base_url string Required: The base URL for the homeserver for client-server connections.
Identity Server Information
Name Type Description
base_url string Required: The base URL for the identity server for client-server connections.

200 response body example

{
  "m.homeserver": {
    "base_url": "https://matrix.example.com"
  },
  "m.identity_server": {
    "base_url": "https://identity.example.com"
  },
  "org.example.custom.property": {
    "app_url": "https://custom.app.example.org"
  }
}

Client Authentication

Most API endpoints require the user to identify themselves by presenting previously obtained credentials in the form of an access_token query parameter or through an Authorization Header of Bearer $access_token. An access token is typically obtained via the Login or Registration processes.

Note

This specification does not mandate a particular format for the access token. Clients should treat it as an opaque byte sequence. Servers are free to choose an appropriate format. Server implementors may like to investigate macaroons.

Using access tokens

Access tokens may be provided in two ways, both of which the homeserver MUST support:

  1. Via a query string parameter, access_token=TheTokenHere.
  2. Via a request header, Authorization: Bearer TheTokenHere.

Clients are encouraged to use the Authorization header where possible to prevent the access token being leaked in access/HTTP logs. The query string should only be used in cases where the Authorization header is inaccessible for the client.

When credentials are required but missing or invalid, the HTTP call will return with a status of 401 and the error code, M_MISSING_TOKEN or M_UNKNOWN_TOKEN respectively.

Relationship between access tokens and devices

Client devices are closely related to access tokens. Matrix servers should record which device each access token is assigned to, so that subsequent requests can be handled correctly.

By default, the Login and Registration processes auto-generate a new device_id. A client is also free to generate its own device_id or, provided the user remains the same, reuse a device: in either case the client should pass the device_id in the request body. If the client sets the device_id, the server will invalidate any access token previously assigned to that device. There is therefore at most one active access token assigned to each device at any one time.

Soft logout

When a request fails due to a 401 status code per above, the server can include an extra response parameter, soft_logout, to indicate if the client’s persisted information can be retained. This defaults to false, indicating that the server has destroyed the session. Any persisted state held by the client, such as encryption keys and device information, must not be reused and must be discarded.

When soft_logout is true, the client can acquire a new access token by specifying the device ID it is already using to the login API. In most cases a soft_logout: true response indicates that the user’s session has expired on the server-side and the user simply needs to provide their credentials again.

In either case, the client’s previously known access token will no longer function.

User-Interactive Authentication API

Overview

Some API endpoints require authentication that interacts with the user. The homeserver may provide many different ways of authenticating, such as user/password auth, login via a single-sign-on server (SSO), etc. This specification does not define how homeservers should authorise their users but instead defines the standard interface which implementations should follow so that ANY client can login to ANY homeserver.

The process takes the form of one or more ‘stages’. At each stage the client submits a set of data for a given authentication type and awaits a response from the server, which will either be a final success or a request to perform an additional stage. This exchange continues until the final success.

For each endpoint, a server offers one or more ‘flows’ that the client can use to authenticate itself. Each flow comprises a series of stages, as described above. The client is free to choose which flow it follows, however the flow’s stages must be completed in order. Failing to follow the flows in order must result in an HTTP 401 response, as defined below. When all stages in a flow are complete, authentication is complete and the API call succeeds.

User-interactive API in the REST API

In the REST API described in this specification, authentication works by the client and server exchanging JSON dictionaries. The server indicates what authentication data it requires via the body of an HTTP 401 response, and the client submits that authentication data via the auth request parameter.

A client should first make a request with no auth parameter[1]. The homeserver returns an HTTP 401 response, with a JSON body, as follows:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "flows": [
    {
      "stages": [ "example.type.foo", "example.type.bar" ]
    },
    {
      "stages": [ "example.type.foo", "example.type.baz" ]
    }
  ],
  "params": {
      "example.type.baz": {
          "example_key": "foobar"
      }
  },
  "session": "xxxxxx"
}

In addition to the flows, this object contains some extra information:

params
This section contains any information that the client will need to know in order to use a given type of authentication. For each authentication type presented, that type may be present as a key in this dictionary. For example, the public part of an OAuth client ID could be given here.

session
This is a session identifier that the client must pass back to the homeserver, if one is provided, in subsequent attempts to authenticate in the same API call.

The client then chooses a flow and attempts to complete the first stage. It does this by resubmitting the same request with the addition of an auth key in the object that it submits. This dictionary contains a type key whose value is the name of the authentication type that the client is attempting to complete. It must also contain a session key with the value of the session key given by the homeserver, if one was given. It also contains other keys dependent on the auth type being attempted. For example, if the client is attempting to complete auth type example.type.foo, it might submit something like this:

POST /_matrix/client/r0/endpoint HTTP/1.1
Content-Type: application/json
{
  "a_request_parameter": "something",
  "another_request_parameter": "something else",
  "auth": {
      "type": "example.type.foo",
      "session": "xxxxxx",
      "example_credential": "verypoorsharedsecret"
  }
}

If the homeserver deems the authentication attempt to be successful but still requires more stages to be completed, it returns HTTP status 401 along with the same object as when no authentication was attempted, with the addition of the completed key which is an array of auth types the client has completed successfully:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "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"
}

Individual stages may require more than one request to complete, in which case the response will be as if the request was unauthenticated with the addition of any other keys as defined by the auth type.

If the homeserver decides that an attempt on a stage was unsuccessful, but the client may make a second attempt, it returns the same HTTP status 401 response as above, with the addition of the standard errcode and error fields describing the error. For example:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "errcode": "M_FORBIDDEN",
  "error": "Invalid password",
  "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"
}

If the request fails for a reason other than authentication, the server returns an error message in the standard format. For example:

HTTP/1.1 400 Bad request
Content-Type: application/json
{
  "errcode": "M_EXAMPLE_ERROR",
  "error": "Something was wrong"
}

If the client has completed all stages of a flow, the homeserver performs the API call and returns the result as normal. Completed stages cannot be retried by clients, therefore servers must return either a 401 response with the completed stages, or the result of the API call if all stages were completed when a client retries a stage.

Some authentication types may be completed by means other than through the Matrix client, for example, an email confirmation may be completed when the user clicks on the link in the email. In this case, the client retries the request with an auth dict containing only the session key. The response to this will be the same as if the client were attempting to complete an auth state normally, i.e. the request will either complete or request auth, with the presence or absence of that auth type in the ‘completed’ array indicating whether that stage is complete.

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 0         |
| No auth               |
|  ___________________  |
| |_Request_1_________| | <-- Returns "session" key which is used throughout.
|_______________________|
         |
         |
_________V_____________
|       Stage 1         |
| type: "<auth type1>"  |
|  ___________________  |
| |_Request_1_________| |
|_______________________|
         |
         |
_________V_____________
|       Stage 2         |
| type: "<auth type2>"  |
|  ___________________  |
| |_Request_1_________| |
|  ___________________  |
| |_Request_2_________| |
|  ___________________  |
| |_Request_3_________| |
|_______________________|
         |
         |
_________V_____________
|       Stage 3         |
| type: "<auth type3>"  |
|  ___________________  |
| |_Request_1_________| | <-- Returns API response
|_______________________|
Authentication types

This specification defines the following auth types:

  • m.login.password
  • m.login.recaptcha
  • m.login.sso
  • m.login.email.identity
  • m.login.msisdn
  • m.login.dummy

Password-based

Type
m.login.password

Description
The client submits an identifier and secret password, both sent in plain-text.

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.password",
  "identifier": {
    ...
  },
  "password": "<password>",
  "session": "<session ID>"
}

where the identifier property is a user identifier object, as described in Identifier types.

For example, to authenticate using the user’s Matrix ID, clients would submit:

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

Alternatively reply using a 3PID bound to the user’s account on the homeserver using the /account/3pid_ API rather then giving the user explicitly as follows:

{
  "type": "m.login.password",
  "identifier": {
    "type": "m.id.thirdparty",
    "medium": "<The medium of the third party identifier.>",
    "address": "<The third party address of the user>"
  },
  "password": "<password>",
  "session": "<session ID>"
}

In the case that the homeserver does not know about the supplied 3PID, the homeserver must respond with 403 Forbidden.

Google ReCaptcha

Type
m.login.recaptcha

Description
The user completes a Google ReCaptcha 2.0 challenge

To use this authentication type, clients should submit an auth dict as follows:

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

Single Sign-On

Type
m.login.sso

Description
Authentication is supported by authorising with an external single sign-on provider.

A client wanting to complete authentication using SSO should use the Fallback mechanism. See SSO during User-Interactive Authentication for more information.

Email-based (identity / homeserver)

Type
m.login.email.identity

Description
Authentication is supported by authorising an email address with an identity server, or homeserver if supported.

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

To use this authentication type, clients should submit 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'>",
      "id_access_token": "<access token previously registered with the identity server>"
    }
  ],
  "session": "<session ID>"
}

Note that id_server (and therefore id_access_token) is optional if the /requestToken request did not include them.

Phone number/MSISDN-based (identity / homeserver)

Type
m.login.msisdn

Description
Authentication is supported by authorising a phone number with an identity server, or homeserver if supported.

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

To use this authentication type, clients should submit an auth dict as follows:

{
  "type": "m.login.msisdn",
  "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'>",
      "id_access_token": "<access token previously registered with the identity server>"
    }
  ],
  "session": "<session ID>"
}

Note that id_server (and therefore id_access_token) is optional if the /requestToken request did not include them.

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. It can also be used to differentiate flows where otherwise one flow would be a subset of another flow. eg. if a server offers flows m.login.recaptcha and m.login.recaptcha, m.login.email.identity and the client completes the recaptcha stage first, the auth would succeed with the former flow, even if the client was intending to then complete the email auth stage. A server can instead send flows m.login.recaptcha, m.login.dummy and m.login.recaptcha, m.login.email.identity to fix the ambiguity.

To use this authentication type, clients should submit an auth dict with just the type and session, if provided:

{
  "type": "m.login.dummy",
  "session": "<session ID>"
}
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:

/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/<auth type>/fallback/web?session=<session ID>

Where auth type is the type name of the stage it is attempting and session ID is the ID of the session given by the homeserver.

This MUST return an HTML page which can perform this authentication stage. This page must use the following JavaScript when the authentication has been completed:

if (window.onAuthDone) {
    window.onAuthDone();
} else if (window.opener && window.opener.postMessage) {
    window.opener.postMessage("authDone", "*");
}

This allows the client to either arrange for the global function onAuthDone to be defined in an embedded browser, or to use the HTML5 cross-document messaging API, to receive a notification that the authentication stage has been completed.

Once a client receives the notificaton that the authentication stage has been completed, it should resubmit the request with an auth dict with just the session ID:

{
  "session": "<session ID>"
}

Example

A client webapp might use the following javascript to open a popup window which will handle unknown login types:

/**
 * Arguments:
 *     homeserverUrl: the base url of the homeserver (eg "https://matrix.org")
 *
 *     apiEndpoint: the API endpoint being used (eg
 *        "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
 *
 *     loginType: the loginType being attempted (eg "m.login.recaptcha")
 *
 *     sessionID: the session ID given by the homeserver in earlier requests
 *
 *     onComplete: a callback which will be called with the results of the request
 */
function unknownLoginType(homeserverUrl, apiEndpoint, loginType, sessionID, onComplete) {
    var popupWindow;

    var eventListener = function(ev) {
        // check it's the right message from the right place.
        if (ev.data !== "authDone" || ev.origin !== homeserverUrl) {
            return;
        }

        // close the popup
        popupWindow.close();
        window.removeEventListener("message", eventListener);

        // repeat the request
        var requestBody = {
            auth: {
                session: sessionID,
            },
        };

        request({
            method:'POST', url:apiEndpint, json:requestBody,
        }, onComplete);
    };

    window.addEventListener("message", eventListener);

    var url = homeserverUrl +
        "/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
        encodeURIComponent(loginType) +
        "/fallback/web?session=" +
        encodeURIComponent(sessionID);


   popupWindow = window.open(url);
}
Identifier types

Some authentication mechanisms use a user identifier object to identify a user. The user identifier object has a type field to indicate the type of identifier being used, and depending on the type, has other fields giving the information required to identify the user as described below.

This specification defines the following identifier types:

  • m.id.user
  • m.id.thirdparty
  • m.id.phone

Matrix User ID

Type
m.id.user

Description
The user is identified by their Matrix ID.

A client can identify a user using their Matrix ID. This can either be the fully qualified Matrix user ID, or just the localpart of the user ID.

"identifier": {
  "type": "m.id.user",
  "user": "<user_id or user localpart>"
}

Third-party ID

Type
m.id.thirdparty

Description
The user is identified by a third-party identifier in canonicalised form.

A client can identify a user using a 3PID associated with the user’s account on the homeserver, where the 3PID was previously associated using the /account/3pid_ API. See the 3PID Types Appendix for a list of Third-party ID media.

"identifier": {
  "type": "m.id.thirdparty",
  "medium": "<The medium of the third party identifier>",
  "address": "<The canonicalised third party address of the user>"
}

Phone number

Type
m.id.phone

Description
The user is identified by a phone number.

A client can identify a user using a phone number associated with the user’s account, where the phone number was previously associated using the /account/3pid_ API. The phone number can be passed in as entered by the user; the homeserver will be responsible for canonicalising it. If the client wishes to canonicalise the phone number, then it can use the m.id.thirdparty identifier type with a medium of msisdn instead.

"identifier": {
  "type": "m.id.phone",
  "country": "<The country that the phone number is from>",
  "phone": "<The phone number>"
}

The country is the two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone should be parsed as if it were dialled from.

Login

A client can obtain access tokens using the /login API.

Note that this endpoint does not currently use the User-Interactive Authentication API.

For a simple username/password login, clients should submit a /login request as follows:

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

Alternatively, a client can use a 3PID bound to the user’s account on the homeserver using the /account/3pid_ API rather then giving the user explicitly, as follows:

{
  "type": "m.login.password",
  "identifier": {
    "medium": "<The medium of the third party identifier>",
    "address": "<The canonicalised third party address of the user>"
  },
  "password": "<password>"
}

In the case that the homeserver does not know about the supplied 3PID, the homeserver must respond with 403 Forbidden.

To log in using a login token, clients should submit a /login request as follows:

{
  "type": "m.login.token",
  "token": "<login token>"
}

As with token-based interactive login, the token must encode the user ID. In the case that the token is not valid, the homeserver must respond with 403 Forbidden and an error code of M_FORBIDDEN.

If the homeserver advertises m.login.sso as a viable flow, and the client supports it, the client should redirect the user to the /redirect endpoint for client login via SSO. After authentication is complete, the client will need to submit a /login request matching m.login.token.

GET /_matrix/client/r0/login


Gets the homeserver's supported login types to authenticate users. Clients should pick one of these and supply it as the ``type`` when logging in.

Rate-limited: Yes
Requires authentication: No

Request

No request parameters or request body.

Responses

Status Description
200 The login types the homeserver supports
429 This request was rate-limited.

200 response body

Name Type Description
flows [LoginFlow] The homeserver’s supported login types
LoginFlow
Name Type Description
type string The login type. This is supplied as the type when logging in.

200 response body example

{
  "flows": [
    {
      "type": "m.login.password"
    }
  ]
}

POST /_matrix/client/r0/login


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

If the client does not supply a device_id, the server must auto-generate one.

The returned access token must be associated with the device_id supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See Relationship between access tokens and devices_.

Rate-limited: Yes
Requires authentication: No

Request

Request body

Name Type Description
address string Third party identifier for the user. Deprecated in favour of identifier.
device_id string ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate a device_id if this is not specified.
identifier User identifier Identification information for a user
initial_device_display_name string A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device.
medium string When logging in using a third party identifier, the medium of the identifier. Must be ‘email’. Deprecated in favour of identifier.
password string Required when type is m.login.password. The user’s password.
token string Required when type is m.login.token. Part of Token-based_ login.
type enum Required: The login type being used.

One of: [m.login.password m.login.token].

user string The fully qualified user ID or just local part of the user ID, to log in. Deprecated in favour of identifier.
User identifier
Name Type Description
type string Required: The type of identification. See Identifier types_ for supported values and additional property descriptions.

Request body example

{
  "identifier": {
    "type": "m.id.user",
    "user": "cheeky_monkey"
  },
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "type": "m.login.password"
}

Responses

Status Description
200 The user has been authenticated.
400 Part of the request was invalid. For example, the login type may not be recognised.
403

The login attempt failed. This can include one of the following error codes:

  • M_FORBIDDEN: The provided authentication data was incorrect.
  • M_USER_DEACTIVATED: The user has been deactivated.
429 This request was rate-limited.

200 response body

Name Type Description
access_token string An access token for the account. This access token can then be used to authorize other requests.
device_id string ID of the logged-in device. Will be the same as the corresponding parameter in the request, if one was specified.
home_server string

The server_name of the homeserver on which the account has been registered.

Deprecated. Clients should extract the server_name from user_id (by splitting at the first colon) if they require it. Note also that homeserver is not spelt this way.

user_id string The fully-qualified Matrix ID for the account.
well_known Discovery Information Optional client configuration provided by the server. If present, clients SHOULD use the provided object to reconfigure themselves, optionally validating the URLs within. This object takes the same form as the one returned from .well-known autodiscovery.
Discovery Information
Name Type Description
m.homeserver Homeserver Information Required: Used by clients to discover homeserver information.
m.identity_server Identity Server Information Used by clients to discover identity server information.
Homeserver Information
Name Type Description
base_url string Required: The base URL for the homeserver for client-server connections.
Identity Server Information
Name Type Description
base_url string Required: The base URL for the identity server for client-server connections.

200 response body example

{
  "access_token": "abc123",
  "device_id": "GHTYAJCE",
  "user_id": "@cheeky_monkey:matrix.org",
  "well_known": {
    "m.homeserver": {
      "base_url": "https://example.org"
    },
    "m.identity_server": {
      "base_url": "https://id.example.org"
    }
  }
}

POST /_matrix/client/r0/logout


Invalidates an existing access token, so that it can no longer be used for authorization. The device associated with the access token is also deleted. `Device keys <#device-keys>`_ for the device are deleted alongside the device.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The access token used in the request was successfully invalidated.

POST /_matrix/client/r0/logout/all


Invalidates all access tokens for a user, so that they can no longer be used for authorization. This includes the access token that made this request. All devices for the user are also deleted. `Device keys <#device-keys>`_ for the device are deleted alongside the device.

This endpoint does not use the User-Interactive Authentication API_ because User-Interactive Authentication is designed to protect against attacks where the someone gets hold of a single access token then takes over the account. This endpoint invalidates all access tokens for the user, including the token used in the request, and therefore the attacker is unable to take over the account in this way.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The user’s access tokens were successfully invalidated.

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.

Non-credential parameters valid for the /login endpoint can be provided as query string parameters here. These are to be forwarded to the login endpoint during the login process. For example:

GET /_matrix/static/client/login/?device_id=GHTYAJCE

Account registration and management

POST /_matrix/client/r0/account/deactivate


Deactivate the user's account, removing all ability for the user to login again.

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 homeserver may change the flows available depending on whether a valid access token is provided.

Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API.
id_server string The identity server to unbind all of the user’s 3PIDs from. If not provided, the homeserver MUST use the id_server that was originally use to bind each identifier. If the homeserver does not know which id_server that was, it must return an id_server_unbind_result of no-support.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "id_server": "example.org"
}

Responses

Status Description
200 The account has been deactivated.
401 The homeserver requires additional authentication information.
429 This request was rate-limited.

200 response body

Name Type Description
id_server_unbind_result enum Required: An indicator as to whether or not the homeserver was able to unbind the user’s 3PIDs from the identity server(s). success indicates that all identifiers have been unbound from the identity server while no-support indicates that one or more identifiers failed to unbind due to the identity server refusing the request or the homeserver being unable to determine an identity server to unbind from. This must be success if the homeserver has no identifiers to unbind for the user.

One of: [success no-support].

200 response body example

{
  "id_server_unbind_result": "success"
}

POST /_matrix/client/r0/account/password


Changes the password for an account on this homeserver.

This API endpoint uses the User-Interactive Authentication API_ to ensure the user changing the password is actually the owner of the account.

An access token should be submitted to this endpoint if the client has an active session.

The homeserver may change the flows available depending on whether a valid access token is provided. The homeserver SHOULD NOT revoke the access token provided in the request. Whether other access tokens for the user are revoked depends on the request parameters.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API.
logout_devices boolean

Whether the user’s other access tokens, and their associated devices, should be revoked if the request succeeds. Defaults to true.

When false, the server can still take advantage of the soft logout method <#soft-logout>_ for the user’s remaining devices.

new_password string Required: The new password for the account.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "logout_devices": true,
  "new_password": "ihatebananas"
}

Responses

Status Description
200 The password has been changed.
401 The homeserver requires additional authentication information.
429 This request was rate-limited.

POST /_matrix/client/r0/account/password/email/requestToken


The homeserver must check that the given email address **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``/account/password`` endpoint.

This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint, except that M_THREEPID_NOT_FOUND may be returned if no account matching the given email address could be found. The server may instead send an email to the given address prompting the user to create an account. M_THREEPID_IN_USE may not be returned.

The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.

.. |/register/email/requestToken| replace:: /register/email/requestToken

.. _/register/email/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
email string Required: The email address to validate.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
send_attempt integer Required: The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "email": "foo@example.com",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

Responses

Status Description
200 An email was sent to the given address.
400 The referenced third party identifier is not recognised by the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
403 The homeserver does not allow the third party identifier as a contact option.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

POST /_matrix/client/r0/account/password/msisdn/requestToken


The homeserver must check that the given phone number **is associated** with an account on this homeserver. This API should be used to request validation tokens when authenticating for the ``/account/password`` endpoint.

This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint, except that M_THREEPID_NOT_FOUND may be returned if no account matching the given phone number could be found. The server may instead send the SMS to the given phone number prompting the user to create an account. M_THREEPID_IN_USE may not be returned.

The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.

.. |/register/msisdn/requestToken| replace:: /register/msisdn/requestToken

.. _/register/msisdn/requestToken: #post-matrix-client-%CLIENT_MAJOR_VERSION%-register-email-requesttoken

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
country string Required: The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
phone_number string Required: The phone number to validate.
send_attempt integer Required: The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

Responses

Status Description
200 An SMS message was sent to the given phone number.
400 The referenced third party identifier is not recognised by the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
403 The homeserver does not allow the third party identifier as a contact option.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

POST /_matrix/client/r0/register


This API endpoint uses the `User-Interactive Authentication API`_, except in the cases where a guest account is being registered.

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.

If registration is successful, this endpoint will issue an access token the client can use to authorize itself in subsequent requests.

If the client does not supply a device_id, the server must auto-generate one.

The server SHOULD register an account with a User ID based on the username provided, if any. Note that the grammar of Matrix User ID localparts is restricted, so the server MUST either map the provided username onto a user_id in a logical manner, or reject username\s which do not comply to the grammar, with M_INVALID_USERNAME.

Matrix clients MUST NOT assume that localpart of the registered user_id matches the provided username.

The returned access token must be associated with the device_id supplied by the client or generated by the server. The server may invalidate any access token previously associated with that device. See Relationship between access tokens and devices_.

When registering a guest account, all parameters in the request body with the exception of initial_device_display_name MUST BE ignored by the server. The server MUST pick a device_id for the account regardless of input.

Any user ID returned by this API must conform to the grammar given in the Matrix specification &lt;../appendices.html#user-identifiers&gt;_.

Rate-limited: Yes
Requires authentication: No

Request

Request parameters

query parameters
Name Type Description
kind enum The kind of account to register. Defaults to user.

One of: [guest user].

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API. Note that this information is not used to define how the registered user should be authenticated, but is instead used to authenticate the register call itself.
device_id string ID of the client device. If this does not correspond to a known client device, a new device will be created. The server will auto-generate a device_id if this is not specified.
inhibit_login boolean If true, an access_token and device_id should not be returned from this call, therefore preventing an automatic login. Defaults to false.
initial_device_display_name string A display name to assign to the newly-created device. Ignored if device_id corresponds to a known device.
password string The desired password for the account.
username string The basis for the localpart of the desired Matrix ID. If omitted, the homeserver MUST generate a Matrix ID local part.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "device_id": "GHTYAJCE",
  "initial_device_display_name": "Jungle Phone",
  "password": "ilovebananas",
  "username": "cheeky_monkey"
}

Responses

Status Description
200 The account has been registered.
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_INVALID_USERNAME : The desired user ID is not a valid user name.
  • 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.

Homeservers 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.

401 The homeserver requires additional authentication information.
403 The homeserver does not permit registering the account. This response can be used to identify that a particular kind of account is not allowed, or that registration is generally not supported by the homeserver.
429 This request was rate-limited.

200 response body

Name Type Description
access_token string An access token for the account. This access token can then be used to authorize other requests. Required if the inhibit_login option is false.
device_id string ID of the registered device. Will be the same as the corresponding parameter in the request, if one was specified. Required if the inhibit_login option is false.
home_server string

The server_name of the homeserver on which the account has been registered.

Deprecated. Clients should extract the server_name from user_id (by splitting at the first colon) if they require it. Note also that homeserver is not spelt this way.

user_id string Required:

The fully-qualified Matrix user ID (MXID) that has been registered.

Any user ID returned by this API must conform to the grammar given in the Matrix specification <../appendices.html#user-identifiers>_.

200 response body example

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

GET /_matrix/client/r0/register/available


Checks to see if a username is available, and valid, for the server.

The server should check to ensure that, at the time of the request, the username requested is available for use. This includes verifying that an application service has not claimed the username and that the username fits the server's desired requirements (for example, a server could dictate that it does not permit usernames with underscores).

Matrix clients may wish to use this API prior to attempting registration, however the clients must also be aware that using this API does not normally reserve the username. This can mean that the username becomes unavailable between checking its availability and attempting to register it.

Rate-limited: Yes
Requires authentication: No

Request

Request parameters

query parameters
Name Type Description
username string Required: The username to check the availability of.

Responses

Status Description
200 The username is available
400

Part of the request was invalid or the username is not available. This may include one of the following error codes:

  • M_USER_IN_USE : The desired username is already taken.
  • M_INVALID_USERNAME : The desired username is not a valid user name.
  • M_EXCLUSIVE : The desired username is in the exclusive namespace claimed by an application service.
429 This request was rate-limited.

200 response body

Name Type Description
available boolean A flag to indicate that the username is available. This should always be true when the server replies with 200 OK.

200 response body example

{
  "available": true
}

POST /_matrix/client/r0/register/email/requestToken


The homeserver must check that the given email address is **not** already associated with an account on this homeserver. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
email string Required: The email address to validate.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
send_attempt integer Required: The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "email": "foo@example.com",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

Responses

Status Description
200 An email has been sent to the specified address. Note that this may be an email containing the validation token or it may be informing the user of an error.
400

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

  • M_THREEPID_IN_USE : The email address is already registered to an account on this server. However, if the homeserver has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the homeserver in question.
  • M_SERVER_NOT_TRUSTED : The id_server parameter refers to an identity server that is not trusted by this homeserver.
403 The homeserver does not permit the address to be bound.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

POST /_matrix/client/r0/register/msisdn/requestToken


The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
country string Required: The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
phone_number string Required: The phone number to validate.
send_attempt integer Required: The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

Responses

Status Description
200 An SMS message has been sent to the specified phone number. Note that this may be an SMS message containing the validation token or it may be informing the user of an error.
400

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

  • M_THREEPID_IN_USE : The phone number is already registered to an account on this server. However, if the homeserver has the ability to send SMS message, it is recommended that the server instead send an SMS message to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given phone number has an account on the homeserver in question.
  • M_SERVER_NOT_TRUSTED : The id_server parameter refers to an identity server that is not trusted by this homeserver.
403 The homeserver does not permit the address to be bound.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}
Notes on password management

Warning

Clients SHOULD enforce that the password provided is suitably complex. The password SHOULD include a lower-case letter, an upper-case letter, a number and a symbol and be at a minimum 8 characters in length. Servers MAY reject weak passwords with an error code M_WEAK_PASSWORD.

Adding Account Administrative Contact Information

A homeserver may keep some contact information for administrative use. This is independent of any information kept by any identity servers, though can be proxied (bound) to the identity server in many cases.

Note

This section deals with two terms: “add” and “bind”. Where “add” (or “remove”) is used, it is speaking about an identifier that was not bound to an identity server. As a result, “bind” (or “unbind”) references an identifier that is found in an identity server. Note that an identifer can be added and bound at the same time, depending on context.

GET /_matrix/client/r0/account/3pid


Gets a list of the third party identifiers that the homeserver 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 homeserver as, for example, identifiers that it will accept to reset the user's account password.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The lookup was successful.

200 response body

Name Type Description
threepids [Third party identifier]
Third party identifier
Name Type Description
added_at integer Required: The timestamp, in milliseconds, when the homeserver associated the third party identifier with the user.
address string Required: The third party identifier address.
medium enum Required: The medium of the third party identifier.

One of: [email msisdn].

validated_at integer Required: The timestamp, in milliseconds, when the identifier was validated by the identity server.

200 response body example

{
  "threepids": [
    {
      "added_at": 1535336848756,
      "address": "monkey@banana.island",
      "medium": "email",
      "validated_at": 1535176800000
    }
  ]
}

POST /_matrix/client/r0/account/3pid


Adds contact information to the user's account.

This endpoint is deprecated in favour of the more specific /3pid/add and /3pid/bind endpoints.

.. Note:: Previously this endpoint supported a bind parameter. This parameter has been removed, making this endpoint behave as though it was false. This results in this endpoint being an equivalent to /3pid/bind rather than dual-purpose.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
three_pid_creds ThreePidCredentials Required: The third party credentials to associate with the account.
ThreePidCredentials
Name Type Description
client_secret string Required: The client secret used in the session with the identity server.
id_access_token string Required: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
id_server string Required: The identity server to use.
sid string Required: The session identifier given by the identity server.

Request body example

{
  "three_pid_creds": {
    "client_secret": "d0n'tT3ll",
    "id_access_token": "abc123_OpaqueString",
    "id_server": "matrix.org",
    "sid": "abc123987"
  }
}

Responses

Status Description
200 The addition was successful.
403 The credentials could not be verified with the identity server.

POST /_matrix/client/r0/account/3pid/add


This API endpoint uses the `User-Interactive Authentication API`_.

Adds contact information to the user's account. Homeservers should use 3PIDs added through this endpoint for password resets instead of relying on the identity server.

Homeservers should prevent the caller from adding a 3PID to their account if it has already been added to another user's account on the homeserver.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API.
client_secret string Required: The client secret used in the session with the homeserver.
sid string Required: The session identifier given by the homeserver.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "client_secret": "d0n'tT3ll",
  "sid": "abc123987"
}

Responses

Status Description
200 The addition was successful.
401 The homeserver requires additional authentication information.
429 This request was rate-limited.

POST /_matrix/client/r0/account/3pid/bind


Binds a 3PID to the user's account through the specified identity server.

Homeservers should not prevent this request from succeeding if another user has bound the 3PID. Homeservers should simply proxy any errors received by the identity server to the caller.

Homeservers should track successful binds so they can be unbound later.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
client_secret string Required: The client secret used in the session with the identity server.
id_access_token string Required: An access token previously registered with the identity server.
id_server string Required: The identity server to use.
sid string Required: The session identifier given by the identity server.

Request body example

{
  "client_secret": "d0n'tT3ll",
  "id_access_token": "abc123_OpaqueString",
  "id_server": "example.org",
  "sid": "abc123987"
}

Responses

Status Description
200 The addition was successful.
429 This request was rate-limited.

POST /_matrix/client/r0/account/3pid/delete


Removes a third party identifier from the user's account. This might not cause an unbind of the identifier from the identity server.

Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
address string Required: The third party address being removed.
id_server string The identity server to unbind from. If not provided, the homeserver MUST use the id_server the identifier was added through. If the homeserver does not know the original id_server, it MUST return a id_server_unbind_result of no-support.
medium enum Required: The medium of the third party identifier being removed.

One of: [email msisdn].

Request body example

{
  "address": "example@example.org",
  "id_server": "example.org",
  "medium": "email"
}

Responses

Status Description
200 The homeserver has disassociated the third party identifier from the user.

200 response body

Name Type Description
id_server_unbind_result enum Required: An indicator as to whether or not the homeserver was able to unbind the 3PID from the identity server. success indicates that the indentity server has unbound the identifier whereas no-support indicates that the identity server refuses to support the request or the homeserver was not able to determine an identity server to unbind from.

One of: [no-support success].

200 response body example

{
  "id_server_unbind_result": "success"
}

POST /_matrix/client/r0/account/3pid/email/requestToken


The homeserver must check that the given email address is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding an email address to an account. This API's parameters and response are identical to that of the |/register/email/requestToken|_ endpoint. The homeserver should validate the email itself, either by sending a validation email itself or by using a service it has control over.

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
email string Required: The email address to validate.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
send_attempt integer Required: The server will only send an email if the send_attempt is a number greater than the most recent one which it has seen, scoped to that email + client_secret pair. This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. If they do not, the server should respond with success but not resend the email.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "email": "foo@example.com",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "send_attempt": 1
}

Responses

Status Description
200 An email was sent to the given address. Note that this may be an email containing the validation token or it may be informing the user of an error.
400 The third party identifier is already in use on the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
403 The homeserver does not allow the third party identifier as a contact option.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

POST /_matrix/client/r0/account/3pid/msisdn/requestToken


The homeserver must check that the given phone number is **not** already associated with an account on this homeserver. This API should be used to request validation tokens when adding a phone number to an account. This API's parameters and response are identical to that of the |/register/msisdn/requestToken|_ endpoint. The homeserver should validate the phone number itself, either by sending a validation message itself or by using a service it has control over.

Rate-limited: No
Requires authentication: No

Request

Request body

Name Type Description
client_secret string Required: A unique string generated by the client, and used to identify the validation attempt. It must be a string consisting of the characters [0-9a-zA-Z.=_-]. Its length must not exceed 255 characters and it must not be empty.
country string Required: The two-letter uppercase ISO-3166-1 alpha-2 country code that the number in phone_number should be parsed as if it were dialled from.
id_access_token string

An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.

Required if an id_server is supplied.

id_server string

The hostname of the identity server to communicate with. May optionally include a port. This parameter is ignored when the homeserver handles 3PID verification.

This parameter is deprecated with a plan to be removed in a future specification version for /account/password and /register requests.

next_link string Optional. When the validation is completed, the identity server will redirect the user to this URL. This option is ignored when submitting 3PID validation information through a POST request.
phone_number string Required: The phone number to validate.
send_attempt integer Required: The server will only send an SMS if the send_attempt is a number greater than the most recent one which it has seen, scoped to that country + phone_number + client_secret triple. This is to avoid repeatedly sending the same SMS in the case of request retries between the POSTing user and the identity server. The client should increment this value if they desire a new SMS (e.g. a reminder) to be sent.

Request body example

{
  "client_secret": "monkeys_are_GREAT",
  "country": "GB",
  "id_server": "id.example.com",
  "next_link": "https://example.org/congratulations.html",
  "phone_number": "07700900001",
  "send_attempt": 1
}

Responses

Status Description
200 An SMS message was sent to the given phone number.
400 The third party identifier is already in use on the homeserver, or the request was invalid. The error code M_SERVER_NOT_TRUSTED can be returned if the server does not trust/support the identity server provided in the request.
403 The homeserver does not allow the third party identifier as a contact option.

200 response body

Name Type Description
sid string Required: The session ID. Session IDs are opaque strings that must consist entirely of the characters [0-9a-zA-Z.=_-]. Their length must not exceed 255 characters and they must not be empty.
submit_url string

An optional field containing a URL where the client must submit the validation token to, with identical parameters to the Identity Service API’s POST /validate/email/submitToken endpoint (without the requirement for an access token). The homeserver must send this token to the user (if applicable), who should then be prompted to provide it to the client.

If this field is not present, the client can assume that verification will happen without the client’s involvement provided the homeserver advertises this specification version in the /versions response (ie: r0.5.0).

200 response body example

{
  "sid": "123abc",
  "submit_url": "https://example.org/path/to/submitToken"
}

POST /_matrix/client/r0/account/3pid/unbind


Removes a user's third party identifier from the provided identity server without removing it from the homeserver.

Unlike other endpoints, this endpoint does not take an id_access_token parameter because the homeserver is expected to sign the request to the identity server instead.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
address string Required: The third party address being removed.
id_server string The identity server to unbind from. If not provided, the homeserver MUST use the id_server the identifier was added through. If the homeserver does not know the original id_server, it MUST return a id_server_unbind_result of no-support.
medium enum Required: The medium of the third party identifier being removed.

One of: [email msisdn].

Request body example

{
  "address": "example@example.org",
  "id_server": "example.org",
  "medium": "email"
}

Responses

Status Description
200 The identity server has disassociated the third party identifier from the user.

200 response body

Name Type Description
id_server_unbind_result enum Required: An indicator as to whether or not the identity server was able to unbind the 3PID. success indicates that the identity server has unbound the identifier whereas no-support indicates that the identity server refuses to support the request or the homeserver was not able to determine an identity server to unbind from.

One of: [no-support success].

200 response body example

{
  "id_server_unbind_result": "success"
}

Current account information

GET /_matrix/client/r0/account/whoami


Gets information about the owner of a given access token.

Note that, as with the rest of the Client-Server API, Application Services may masquerade as users within their namespace by giving a user_id query parameter. In this situation, the server should verify that the given user_id is registered by the appservice, and return it in the response body.

Rate-limited: Yes
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The token belongs to a known user.
401 The token is not recognised
403 The appservice cannot masquerade as the user or has not registered them.
429 This request was rate-limited.

200 response body

Name Type Description
user_id string Required: The user id that owns the access token.

200 response body example

{
  "user_id": "@joe:example.org"
}
Notes on identity servers

Identity servers in Matrix store bindings (relationships) between a user’s third party identifier, typically email or phone number, and their user ID. Once a user has chosen an identity server, that identity server should be used by all clients.

Clients can see which identity server the user has chosen through the m.identity_server account data event, as described below. Clients SHOULD refrain from making requests to any identity server until the presence of m.identity_server is confirmed as (not) present. If present, the client SHOULD check for the presence of the base_url property in the event’s content. If the base_url is present, the client SHOULD use the identity server in that property as the identity server for the user. If the base_url is missing, or the account data event is not present, the client SHOULD use whichever default value it normally would for an identity server, if applicable. Clients SHOULD NOT update the account data with the default identity server when the user is missing an identity server in their account data.

Clients SHOULD listen for changes to the m.identity_server account data event and update the identity server they are contacting as a result.

If the client offers a way to set the identity server to use, it MUST update the value of m.identity_server accordingly. A base_url of null MUST be treated as though the user does not want to use an identity server, disabling all related functionality as a result.

Clients SHOULD refrain from populating the account data as a migration step for users who are lacking the account data, unless the user sets the identity server within the client to a value. For example, a user which has no m.identity_server account data event should not end up with the client’s default identity server in their account data, unless the user first visits their account settings to set the identity server.

m.identity_server


Persists the user’s preferred identity server, or preference to not use an identity server at all, in the user’s account data.

Event type: Message event

Content

Name Type Description
base_url string The URL of the identity server the user prefers to use, or null if the user does not want to use an identity server. This value is similar in structure to the base_url for identity servers in the .well-known/matrix/client schema.

Examples

{
  "content": {
    "base_url": "https://example.org",
    "key": "value"
  },
  "type": "m.identity_server"
}

Capabilities negotiation

A homeserver may not support certain operations and clients must be able to query for what the homeserver can and can’t offer. For example, a homeserver may not support users changing their password as it is configured to perform authentication against an external system.

The capabilities advertised through this system are intended to advertise functionality which is optional in the API, or which depend in some way on the state of the user or server. This system should not be used to advertise unstable or experimental features - this is better done by the /versions endpoint.

Some examples of what a reasonable capability could be are:

  • Whether the server supports user presence.
  • Whether the server supports optional features, such as the user or room directories.
  • The rate limits or file type restrictions imposed on clients by the server.

Some examples of what should not be a capability are:

  • Whether the server supports a feature in the unstable specification.
  • Media size limits - these are handled by the /media/%CLIENT_MAJOR_VERSION%/config API.
  • Optional encodings or alternative transports for communicating with the server.

Capabilities prefixed with m. are reserved for definition in the Matrix specification while other values may be used by servers using the Java package naming convention. The capabilities supported by the Matrix specification are defined later in this section.

GET /_matrix/client/r0/capabilities


Gets information about the server's supported feature set and other relevant capabilities.

Rate-limited: Yes
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The capabilities of the server.
429 This request was rate-limited.

200 response body

Name Type Description
capabilities Capabilities Required: The custom capabilities the server supports, using the Java package naming convention.
Capabilities
Name Type Description
m.change_password ChangePasswordCapability Capability to indicate if the user can change their password.
m.room_versions RoomVersionsCapability The room versions the server supports.
ChangePasswordCapability
Name Type Description
enabled boolean Required: True if the user can change their password, false otherwise.
RoomVersionsCapability
Name Type Description
available object Required: A detailed description of the room versions the server supports.
default string Required: The default room version the server is using for new rooms.

200 response body example

{
  "capabilities": {
    "com.example.custom.ratelimit": {
      "max_requests_per_hour": 600
    },
    "m.change_password": {
      "enabled": false
    },
    "m.room_versions": {
      "available": {
        "1": "stable",
        "2": "stable",
        "3": "unstable",
        "test-version": "unstable"
      },
      "default": "1"
    }
  }
}

m.change_password capability

This capability has a single flag, enabled, which indicates whether or not the user can use the /account/password API to change their password. If not present, the client should assume that password changes are possible via the API. When present, clients SHOULD respect the capability’s enabled flag and indicate to the user if they are unable to change their password.

An example of the capability API’s response for this capability is:

{
  "capabilities": {
    "m.change_password": {
      "enabled": false
    }
  }
}

m.room_versions capability

This capability describes the default and available room versions a server supports, and at what level of stability. Clients should make use of this capability to determine if users need to be encouraged to upgrade their rooms.

An example of the capability API’s response for this capability is:

{
  "capabilities": {
    "m.room_versions": {
      "default": "1",
      "available": {
        "1": "stable",
        "2": "stable",
        "3": "unstable",
        "custom-version": "unstable"
      }
    }
  }
}

This capability mirrors the same restrictions of room versions to describe which versions are stable and unstable. Clients should assume that the default version is stable. Any version not explicitly labelled as stable in the available versions is to be treated as unstable. For example, a version listed as future-stable should be treated as unstable.

The default version is the version the server is using to create new rooms. Clients should encourage users with sufficient permissions in a room to upgrade their room to the default version when the room is using an unstable version.

When this capability is not listed, clients should use "1" as the default and only stable available room version.

Pagination

Note

The paths referred to in this section are not actual endpoints. They only serve as examples to explain how pagination functions.

Pagination is the process of dividing a dataset into multiple discrete pages. Matrix makes use of pagination to allow clients to view extremely large datasets. These datasets are not limited to events in a room (for example clients may want to paginate a list of rooms in addition to events within those rooms). Regardless of what is being paginated, there is a common approach which is used to give clients an easy way of selecting subsets of a potentially changing dataset. Each endpoint that uses pagination may use different parameters. However the theme among them is that they take a from and to token, and occasionally a limit and dir. Together, these parameters describe the position in a data set, where from and to are known as “stream tokens” matching the regular expression [a-zA-Z0-9.=_-]+. If supported, the dir defines the direction of events to return: either forwards (f) or backwards (b). The response may contain tokens that can be used for retrieving results before or after the returned set. These tokens may be called start or prev_batch for retrieving the previous result set, or end, next_batch or next_token for retrieving the next result set.

In the following examples, ‘START’ and ‘END’ are placeholders to signify the start and end of the data sets respectively.

For example, if an endpoint had 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-|
|                               |                    |
|                          _____|  <--backwards--    |
|__________________       |         |        ________|
                   |      |         |        |
 GET /somepath?to=START&limit=5&dir=b&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 /roomslist?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 initial 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.

Responses for pagination-capable endpoints SHOULD have a chunk array alongside the applicable stream tokens to represent the result set.

In general, when the end of a result set is reached the applicable stream token will be excluded from the response. For example, if a user was backwards-paginating events in a room they’d eventually reach the first event in the room. In this scenario, the prev_batch token would be excluded from the response. Some paginated endpoints are open-ended in one direction, such as endpoints which expose an event stream for an active room. In this case, it is not possible for the client to reach the true “end” of the data set and therefore should always be presented with a token to keep moving forwards.

Filtering

Filters can be created on the server and can be passed as a parameter to APIs which return events. These filters alter the data returned from those APIs. Not all APIs accept filters.

Lazy-loading room members

Membership events often take significant resources for clients to track. In an effort to reduce the number of resources used, clients can enable “lazy-loading” for room members. By doing this, servers will attempt to only send membership events which are relevant to the client.

It is important to understand that lazy-loading is not intended to be a perfect optimisation, and that it may not be practical for the server to calculate precisely which membership events are relevant to the client. As a result, it is valid for the server to send redundant membership events to the client to ease implementation, although such redundancy should be minimised where possible to conserve bandwidth.

In terms of filters, lazy-loading is enabled by enabling lazy_load_members on a RoomEventFilter (or a StateFilter in the case of /sync only). When enabled, lazy-loading aware endpoints (see below) will only include membership events for the sender of events being included in the response. For example, if a client makes a /sync request with lazy-loading enabled, the server will only return membership events for the sender of events in the timeline, not all members of a room.

When processing a sequence of events (e.g. by looping on /sync or paginating /messages), it is common for blocks of events in the sequence to share a similar set of senders. Rather than responses in the sequence sending duplicate membership events for these senders to the client, the server MAY assume that clients will remember membership events they have already been sent, and choose to skip sending membership events for members whose membership has not changed. These are called ‘redundant membership events’. Clients may request that redundant membership events are always included in responses by setting include_redundant_members to true in the filter.

The expected pattern for using lazy-loading is currently:

  • Client performs an initial /sync with lazy-loading enabled, and receives only the membership events which relate to the senders of the events it receives.
  • Clients which support display-name tab-completion or other operations which require rapid access to all members in a room should call /members for the currently selected room, with an ?at parameter set to the /sync response’s from token. The member list for the room is then maintained by the state in subsequent incremental /sync responses.
  • Clients which do not support tab-completion may instead pull in profiles for arbitrary users (e.g. read receipts, typing notifications) on demand by querying the room state or /profile.

The current endpoints which support lazy-loading room members are:

  • /sync_
  • /rooms/<room_id>/messages_
  • /rooms/{roomId}/context/{eventId}_

API endpoints

POST /_matrix/client/r0/user/{userId}/filter


Uploads a new filter definition to the homeserver. Returns a filter ID that may be used in future requests to restrict which events are returned to the client.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
userId string Required: The id of the user uploading the filter. The access token must be authorized to make requests for this user id.

Request body

Filter
Name Type Description
account_data EventFilter The user account data that isn’t associated with rooms to include.
event_fields [string] List of event fields to include. If this list is absent then all fields are included. The entries may include ‘.’ characters to indicate sub-fields. So [‘content.body’] will include the ‘body’ field of the ‘content’ object. A literal ‘.’ character in a field name may be escaped using a ‘\’. A server may include more fields than were requested.
event_format enum The format to use for events. ‘client’ will return the events in a format suitable for clients. ‘federation’ will return the raw event as received over federation. The default is ‘client’.

One of: [client federation].

presence EventFilter The presence updates to include.
room RoomFilter Filters to be applied to room data.
EventFilter
Name Type Description
limit integer The maximum number of events to return.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.
RoomFilter
Name Type Description
account_data RoomEventFilter The per user account data to include for rooms.
ephemeral RoomEventFilter The events that aren’t recorded in the room history, e.g. typing and receipts, to include for rooms.
include_leave boolean Include rooms that the user has left in the sync, default false
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ephemeral, state, timeline or account_data
state StateFilter The state events to include for rooms.
timeline RoomEventFilter The message and state update events to include for rooms.
RoomEventFilter
Name Type Description
contains_url boolean If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering.
include_redundant_members boolean If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
lazy_load_members boolean If true, enables lazy-loading of membership events. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
limit integer The maximum number of events to return.
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.
StateFilter
Name Type Description
contains_url boolean If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering.
include_redundant_members boolean If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
lazy_load_members boolean If true, enables lazy-loading of membership events. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
limit integer The maximum number of events to return.
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.

Request body example

{
  "event_fields": [
    "type",
    "content",
    "sender"
  ],
  "event_format": "client",
  "presence": {
    "not_senders": [
      "@alice:example.com"
    ],
    "types": [
      "m.presence"
    ]
  },
  "room": {
    "ephemeral": {
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "not_senders": [
        "@spam:example.com"
      ],
      "types": [
        "m.receipt",
        "m.typing"
      ]
    },
    "state": {
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "types": [
        "m.room.*"
      ]
    },
    "timeline": {
      "limit": 10,
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "not_senders": [
        "@spam:example.com"
      ],
      "types": [
        "m.room.message"
      ]
    }
  }
}

Responses

Status Description
200 The filter was created.

200 response body

Name Type Description
filter_id string Required: The ID of the filter that was created. Cannot start with a { as this character is used to determine if the filter provided is inline JSON or a previously declared filter by homeservers on some APIs.

200 response body example

{
  "filter_id": "66696p746572"
}

GET /_matrix/client/r0/user/{userId}/filter/{filterId}


Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
filterId string Required: The filter ID to download.
userId string Required: The user ID to download a filter for.

Responses

Status Description
200 The filter definition.
404 Unknown filter.

200 response body

Filter
Name Type Description
account_data EventFilter The user account data that isn’t associated with rooms to include.
event_fields [string] List of event fields to include. If this list is absent then all fields are included. The entries may include ‘.’ characters to indicate sub-fields. So [‘content.body’] will include the ‘body’ field of the ‘content’ object. A literal ‘.’ character in a field name may be escaped using a ‘\’. A server may include more fields than were requested.
event_format enum The format to use for events. ‘client’ will return the events in a format suitable for clients. ‘federation’ will return the raw event as received over federation. The default is ‘client’.

One of: [client federation].

presence EventFilter The presence updates to include.
room RoomFilter Filters to be applied to room data.
EventFilter
Name Type Description
limit integer The maximum number of events to return.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.
RoomFilter
Name Type Description
account_data RoomEventFilter The per user account data to include for rooms.
ephemeral RoomEventFilter The events that aren’t recorded in the room history, e.g. typing and receipts, to include for rooms.
include_leave boolean Include rooms that the user has left in the sync, default false
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter. This filter is applied before the filters in ephemeral, state, timeline or account_data
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included. This filter is applied before the filters in ephemeral, state, timeline or account_data
state StateFilter The state events to include for rooms.
timeline RoomEventFilter The message and state update events to include for rooms.
RoomEventFilter
Name Type Description
contains_url boolean If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering.
include_redundant_members boolean If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
lazy_load_members boolean If true, enables lazy-loading of membership events. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
limit integer The maximum number of events to return.
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.
StateFilter
Name Type Description
contains_url boolean If true, includes only events with a url key in their content. If false, excludes those events. If omitted, url key is not considered for filtering.
include_redundant_members boolean If true, sends all membership events for all events, even if they have already been sent to the client. Does not apply unless lazy_load_members is true. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
lazy_load_members boolean If true, enables lazy-loading of membership events. See Lazy-loading room members <#lazy-loading-room-members>_ for more information. Defaults to false.
limit integer The maximum number of events to return.
not_rooms [string] A list of room IDs to exclude. If this list is absent then no rooms are excluded. A matching room will be excluded even if it is listed in the 'rooms' filter.
not_senders [string] A list of sender IDs to exclude. If this list is absent then no senders are excluded. A matching sender will be excluded even if it is listed in the 'senders' filter.
not_types [string] A list of event types to exclude. If this list is absent then no event types are excluded. A matching type will be excluded even if it is listed in the 'types' filter. A ‘*’ can be used as a wildcard to match any sequence of characters.
rooms [string] A list of room IDs to include. If this list is absent then all rooms are included.
senders [string] A list of senders IDs to include. If this list is absent then all senders are included.
types [string] A list of event types to include. If this list is absent then all event types are included. A '*' can be used as a wildcard to match any sequence of characters.

200 response body example

{
  "event_fields": [
    "type",
    "content",
    "sender"
  ],
  "event_format": "client",
  "presence": {
    "not_senders": [
      "@alice:example.com"
    ],
    "types": [
      "m.presence"
    ]
  },
  "room": {
    "ephemeral": {
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "not_senders": [
        "@spam:example.com"
      ],
      "types": [
        "m.receipt",
        "m.typing"
      ]
    },
    "state": {
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "types": [
        "m.room.*"
      ]
    },
    "timeline": {
      "limit": 10,
      "not_rooms": [
        "!726s6s6q:example.com"
      ],
      "not_senders": [
        "@spam:example.com"
      ],
      "types": [
        "m.room.message"
      ]
    }
  }
}

Events

The model of conversation history exposed by the client-server API can be considered as a list of events. The server ‘linearises’ the eventually-consistent event graph of events into an ‘event stream’ at any given point in time:

[E0]->[E1]->[E2]->[E3]->[E4]->[E5]

Warning

The format of events can change depending on room version. Check the room version specification for specific details on what to expect for event formats. Examples contained within the client-server specification are expected to be compatible with all specified room versions, however some differences may still apply.

For this version of the specification, clients only need to worry about the event ID format being different depending on room version. Clients should not be parsing the event ID, and instead be treating it as an opaque string. No changes should be required to support the currently available room versions.

Types of room events

Room events are split into two categories:

State Events
These are events which update the metadata state of the room (e.g. room topic, room membership etc). State is keyed by a tuple of event type and a state_key. State in the room with the same key-tuple will be overwritten.

Message events
These are events which describe transient “once-off” activity in a room: typically communication such as sending an instant message or setting up a VoIP call.

This specification outlines several events, all with the event type prefix m.. (See Room Events for the m. event specification.) However, applications may wish to add their own type of event, and this can be achieved using the REST API detailed in the following sections. If new events are added, the event type key SHOULD follow the Java package naming convention, e.g. com.example.myapp.event. This ensures event types are suitably namespaced for each application and reduces the risk of clashes.

Note

Events are not limited to the types defined in this specification. New or custom event types can be created on a whim using the Java package naming convention. For example, a com.example.game.score event can be sent by clients and other clients would receive it through Matrix, assuming the client has access to the com.example namespace.

Note that the structure of these events may be different than those in the server-server API.

Event fields

Event

The basic set of fields all events must have.


Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’

Room event fields

Room event

Room Events have the following fields.


Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.

State event fields

In addition to the fields of a Room Event, State Events have the following fields.

Key Type Description
state_key string Required. 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user's ID as the state key MUST only be set by that user.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.

Size limits

The complete event MUST NOT be larger than 65535 bytes, when formatted as a PDU for the Server-Server protocol, including any signatures, and encoded as Canonical JSON.

There are additional restrictions on sizes per key:

  • sender MUST NOT exceed 255 bytes (including domain).
  • room_id MUST NOT exceed 255 bytes.
  • state_key MUST NOT exceed 255 bytes.
  • type MUST NOT exceed 255 bytes.
  • event_id MUST NOT exceed 255 bytes.

Some event types have additional size restrictions which are specified in the description of the event. Additional keys have no limit other than that implied by the total 65 KB limit on events.

Room Events

Note

This section is a work in progress.

This specification outlines several standard event types, all of which are prefixed with m.

m.room.canonical_alias


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

Event type: State event
State key A zero-length string.

Content

Name Type Description
alias string The canonical alias for the room. If not present, null, or empty the room should be considered to have no canonical alias.
alt_aliases [string] Alternative aliases the room advertises. This list can have aliases despite the alias field being null, empty, or otherwise not present.

Examples

{
  "content": {
    "alias": "#somewhere:localhost",
    "alt_aliases": [
      "#somewhere:example.org",
      "#myroom:example.com"
    ],
    "key": "value"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.canonical_alias",
  "unsigned": {
    "age": 1234
  }
}

m.room.create


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

Event type: State event
State key A zero-length string.

Content

Name 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.
predecessor Previous Room A reference to the room this room replaces, if the previous room was upgraded.
room_version string The version of the room. Defaults to "1" if the key does not exist.
Previous Room
Name Type Description
event_id string The event ID of the last known event in the old room.
room_id string The ID of the old room.

Examples

{
  "content": {
    "creator": "@example:example.org",
    "key": "value",
    "m.federate": true,
    "predecessor": {
      "event_id": "$something:example.org",
      "room_id": "!oldroom:example.org"
    },
    "room_version": "1"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.create",
  "unsigned": {
    "age": 1234
  }
}

m.room.join_rules


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.

Event type: State event
State key A zero-length string.

Content

Name Type Description
join_rule enum The type of rules used for users wishing to join this room.

One of: [public knock invite private].

Examples

{
  "content": {
    "join_rule": "public",
    "key": "value"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.join_rules",
  "unsigned": {
    "age": 1234
  }
}

m.room.member


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 following membership states are specified:

  • invite - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.

  • join - The user has joined the room (possibly after accepting an invite), and may participate in it.

  • leave - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).

  • ban - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than ban).

  • knock - This is a reserved word, which currently has no meaning.

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 inside the event’s unsigned data. If present, this contains an array of StrippedState Events. These events provide information on a subset of state events such as the room name.

The user for which a membership applies is represented by the state_key. Under some conditions, the sender and state_key may not match - this may be interpreted as the sender affecting the membership state of the state_key user.

The membership for a given user can change over time. The table below represents the various changes over time and how clients and servers must interpret those changes. Previous membership can be retrieved from the prev_content object on an event. If not present, the user’s previous membership must be assumed as leave.

.. TODO: Improve how this table is written? We use a csv-table to get around vertical header restrictions.

.. csv-table:: :header-rows: 1 :stub-columns: 1

“”,“to invite”,“to join”,“to leave”,“to ban”,“to knock” “from invite”,“No change.”,“User joined the room.”,“If the state_key is the same as the sender, the user rejected the invite. Otherwise, the state_key user had their invite revoked.”,“User was banned.”,“Not implemented.” “from join”,“Must never happen.”,"displayname or avatar_url changed.",“If the state_key is the same as the sender, the user left. Otherwise, the state_key user was kicked.”,“User was kicked and banned.”,“Not implemented.” “from leave”,“New invitation sent.”,“User joined.”,“No change.”,“User was banned.”,“Not implemented.” “from ban”,“Must never happen.”,“Must never happen.”,“User was unbanned.”,“No change.”,“Not implemented.” “from knock”,“Not implemented.”,“Not implemented.”,“Not implemented.”,“Not implemented.”,“Not implemented.”

Event type: State event
State key The user_id this membership event relates to. In all cases except for when membership is join, the user ID sending the event does not need to match the user ID in the state_key, unlike other events. Regular authorisation rules still apply.

Content

EventContent
Name Type Description
avatar_url string The avatar URL for this user, if any.
displayname [string null] The display name for this user, if any.
is_direct boolean Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging_.
membership enum The membership state of the user.

One of: [invite join knock leave ban].

third_party_invite Invite
Invite
Name Type Description
display_name string A name which can be displayed to represent the user instead of their third party identifier
signed signed A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.
signed
Name 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 of the server-server API.
token string The token property of the containing third_party_invite object.

Examples

{
  "content": {
    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
    "displayname": "Alice Margatroid",
    "key": "value",
    "membership": "join"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "@alice:example.org",
  "type": "m.room.member",
  "unsigned": {
    "age": 1234
  }
}
{
  "content": {
    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
    "displayname": "Alice Margatroid",
    "membership": "invite"
  },
  "unsigned": {
    "age": 1234,
    "invite_room_state": [
      {
        "content": {
          "name": "Example Room"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.name"
      },
      {
        "content": {
          "join_rule": "invite"
        },
        "sender": "@bob:example.org",
        "state_key": "",
        "type": "m.room.join_rules"
      }
    ]
  }
}
{
  "content": {
    "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
    "displayname": "Alice Margatroid",
    "membership": "invite",
    "third_party_invite": {
      "display_name": "alice",
      "signed": {
        "mxid": "@alice:example.org",
        "signatures": {
          "magic.forest": {
            "ed25519:3": "fQpGIW1Snz+pwLZu6sTy2aHy/DYWWTspTJRPyNp0PKkymfIsNffysMl6ObMMFdIJhk6g6pwlIqZ54rxo8SLmAg"
          }
        },
        "token": "abc123"
      }
    }
  }
}

m.room.power_levels


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. If the room contains no m.room.power_levels event, the room’s creator has a power level of 100, and all other users have a power level of 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.

If there is no state_default in the m.room.power_levels event, the state_default is 50. If there is no events_default in the m.room.power_levels event, the events_default is 0. If the room contains no m.room.power_levels event, both the state_default and events_default are 0.

The power level required to invite a user to the room, kick a user from the room, ban a user from the room, or redact an event, is defined by invite, kick, ban, and redact, respectively. Each of these levels defaults to 50 if they are not specified in the m.room.power_levels event, or if the room contains no m.room.power_levels event.

.. NOTE::

As noted above, in the absence of an m.room.power_levels event, the state_default is 0, and all users are considered to have power level 0. That means that any member of the room can send an m.room.power_levels event, changing the permissions in the room.

Server implementations should therefore ensure that each room has an m.room.power_levels event as soon as it is created. See also the documentation of the /createRoom API.

Event type: State event
State key A zero-length string.

Content

Name Type Description
ban integer The level required to ban a user. Defaults to 50 if unspecified.
events Event power levels The level required to send specific event types. This is a mapping from event type to power level required.
events_default integer The default level required to send message events. Can be overridden by the events key. Defaults to 0 if unspecified.
invite integer The level required to invite a user. Defaults to 50 if unspecified.
kick integer The level required to kick a user. Defaults to 50 if unspecified.
notifications Notifications The power level requirements for specific notification types. This is a mapping from key to power level for that notifications key.
redact integer The level required to redact an event. Defaults to 50 if unspecified.
state_default integer The default level required to send state events. Can be overridden by the events key. Defaults to 50 if unspecified.
users User power levels The power levels for specific users. This is a mapping from user_id to power level for that user.
users_default integer The default power level for every user in the room, unless their user_id is mentioned in the users key. Defaults to 0 if unspecified.
Notifications
Name Type Description
room integer The level required to trigger an @room notification. Defaults to 50 if unspecified.

Examples

{
  "content": {
    "ban": 50,
    "events": {
      "m.room.name": 100,
      "m.room.power_levels": 100
    },
    "events_default": 0,
    "invite": 50,
    "key": "value",
    "kick": 50,
    "notifications": {
      "room": 20
    },
    "redact": 50,
    "state_default": 50,
    "users": {
      "@example:localhost": 100
    },
    "users_default": 0
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "state_key": "",
  "type": "m.room.power_levels",
  "unsigned": {
    "age": 1234
  }
}

m.room.redaction


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.

Event type: Message event

Content

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

Examples

{
  "content": {
    "key": "value",
    "reason": "Spamming"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "redacts": "$fukweghifu23:localhost",
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.redaction",
  "unsigned": {
    "age": 1234
  }
}
Historical events

Some events within the m. namespace might appear in rooms, however they serve no significant meaning in this version of the specification. They are:

  • m.room.aliases

Previous versions of the specification have more information on these events.

Syncing

To read events, the intended flow of operation is for clients to first call the /sync_ API without a since parameter. This returns the most recent message events for each room, as well as the state of the room at the start of the returned timeline. The response also includes a next_batch field, which should be used as the value of the since parameter in the next call to /sync. Finally, the response includes, for each room, a prev_batch field, which can be passed as a start parameter to the /rooms/<room_id>/messages_ API to retrieve earlier messages.

You can visualise the range of events being returned as:

[E0]->[E1]->[E2]->[E3]->[E4]->[E5]
           ^                      ^
           |                      |
     prev_batch: '1-2-3'        next_batch: 'a-b-c'

Clients then receive new events by “long-polling” the homeserver via the /sync API, passing the value of the next_batch field from the response to the previous call as the since parameter. The client should also pass a timeout parameter. The server will then hold open the HTTP connection for a short period of time waiting for new events, returning early if an event occurs. Only the /sync API (and the deprecated /events API) support long-polling in this way.

The response for such an incremental sync can be visualised as:

[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]
                                  ^     ^
                                  |     |
                                  |  next_batch: 'x-y-z'
                                prev_batch: 'a-b-c'

Normally, all new events which are visible to the client will appear in the response to the /sync API. However, if a large number of events arrive between calls to /sync, a “limited” timeline is returned, containing only the most recent message events. A state “delta” is also returned, summarising any state changes in the omitted part of the timeline. The client may therefore end up with “gaps” in its knowledge of the message timeline. The client can fill these gaps using the /rooms/<room_id>/messages_ API. This situation looks like this:

| gap |
| <-> |
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]->[E6]->[E7]->[E8]->[E9]->[E10]
      ^                        ^
      |                        |
 prev_batch: 'd-e-f'       next_batch: 'u-v-w'

Warning

Events are ordered in this API according to the arrival time of the event on the homeserver. This can conflict with other APIs which order events based on their partial ordering in the event graph. This can result in duplicate events being received (once per distinct API called). Clients SHOULD de-duplicate events based on the event ID when this happens.

Note

The /sync API returns a state list which is separate from the timeline. This state list allows clients to keep their model of the room state in sync with that on the server. In the case of an initial (since-less) sync, the state list represents the complete state of the room at the start of the returned timeline (so in the case of a recently-created room whose state fits entirely in the timeline, the state list will be empty).

In the case of an incremental sync, the state list gives a delta between the state of the room at the since parameter and that at the start of the returned timeline. (It will therefore be empty unless the timeline was limited.)

In both cases, it should be noted that the events returned in the state list did not necessarily take place just before the returned timeline, so clients should not display them to the user in the timeline.

Rationale

An early design of this specification made the state list represent the room state at the end of the returned timeline, instead of the start. This was unsatisfactory because it led to duplication of events between the state list and the timeline, but more importantly, it made it difficult for clients to show the timeline correctly.

In particular, consider a returned timeline [M0, S1, M2], where M0 and M2 are both messages sent by the same user, and S1 is a state event where that user changes their displayname. If the state list represents the room state at the end of the timeline, the client must take a copy of the state dictionary, and rewind S1, in order to correctly calculate the display name for M0.

GET /_matrix/client/r0/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.

Note: This endpoint supports lazy-loading. See Filtering &lt;#filtering&gt;_ for more information. Lazy-loading members is only supported on a StateFilter for this endpoint. When lazy-loading is enabled, servers MUST include the syncing user's own membership event when they join a room, or when the full state of rooms is requested, to aid discovering the user's avatar & displayname.

Further, like other members, the user's own membership event is eligible for being considered redundant by the server. When a sync is limited, the server MUST return membership events for events in the gap (between since and the start of the returned timeline), regardless as to whether or not they are redundant. This ensures that joins/leaves and profile changes which occur during the gap are not lost.

Note that the default behaviour of state is to include all membership events, alongside other state, when lazy-loading is not enabled.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
filter string

The ID of a filter created using the filter API or a filter JSON object encoded as a string. The server will detect whether it is an ID or a JSON object by whether the first character is a "{" open brace. Passing the JSON inline is best suited to one off requests. Creating a filter using the filter API is recommended for clients that reuse the same filter multiple times, for example in long poll requests.

See Filtering <#filtering>_ for more information.

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. When set to “unavailable”, the client is marked as being idle.

One of: [offline online unavailable].

since string A point in time to continue a sync from.
timeout integer

The maximum time to wait, in milliseconds, before returning this request. If no events (or other data) become available before this time elapses, the server will return a response with empty fields.

By default, this is 0, so the server will return immediately even if the response is empty.

Responses

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

200 response body

Name Type Description
account_data Account Data The global private data created by this user.
device_lists DeviceLists Information on end-to-end device updates, as specified in |device_lists_sync|_.
device_one_time_keys_count One-time keys count Information on end-to-end encryption keys, as specified in |device_lists_sync|_.
next_batch string Required: 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.
to_device ToDevice Information on the send-to-device messages for the client device, as defined in |send_to_device_sync|_.
Account Data
Name Type Description
events [object] List of events.
Event
Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
Presence
Name Type Description
events [object] List of events.
Rooms
Name Type Description
invite Invited Rooms The rooms that the user has been invited to, mapped as room ID to room information.
join Joined Rooms The rooms that the user has joined, mapped as room ID to room information.
leave Left rooms The rooms that the user has left or been banned from, mapped as room ID to room information.
Invited Room
Name 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
Name Type Description
events [StrippedState] The StrippedState events that form the invite state.
StrippedState
Name Type Description
content EventContent Required: The content for the event.
sender string Required: The sender for the event.
state_key string Required: The state_key for the event.
type string Required: The type for the event.
Joined Room
Name Type Description
account_data Account Data The private data that this user has attached to this room.
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).

N.B. state updates for m.room.member events will be incomplete if lazy_load_members is enabled in the /sync filter, and only return the member events required to display the senders of the timeline events in this response.

summary RoomSummary Information about the room which clients may need to correctly render it to users.
timeline Timeline The timeline of messages and state changes in the room.
unread_notifications Unread Notification Counts Counts of unread notifications for this room. See the Receiving notifications section <#receiving-notifications>_ for more information on how these are calculated.
Ephemeral
Name Type Description
events [object] List of events.
State
Name Type Description
events [object] List of events.
SyncStateEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
RoomSummary
Name Type Description
m.heroes [string]

The users which can be used to generate a room name if the room does not have one. Required if the room’s m.room.name or m.room.canonical_alias state events are unset or empty.

This should be the first 5 members of the room, ordered by stream ordering, which are joined or invited. The list must never include the client’s own user ID. When no joined or invited members are available, this should consist of the banned and left users. More than 5 members may be provided, however less than 5 should only be provided when there are less than 5 members to represent.

When lazy-loading room members is enabled, the membership events for the heroes MUST be included in the state, unless they are redundant. When the list of users changes, the server notifies the client by sending a fresh list of heroes. If there are no changes since the last sync, this field may be omitted.

m.invited_member_count integer The number of users with membership of invite. If this field has not changed since the last sync, it may be omitted. Required otherwise.
m.joined_member_count integer The number of users with membership of join, including the client’s own user ID. If this field has not changed since the last sync, it may be omitted. Required otherwise.
Timeline
Name Type Description
events [object] List of events.
limited boolean True if the number of events returned was limited by the limit on the filter.
prev_batch string A token that can be supplied to the from parameter of the rooms/{roomId}/messages endpoint.
SyncRoomEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
Unread Notification Counts
Name Type Description
highlight_count Highlighted notification count The number of unread notifications for this room with the highlight flag set
notification_count Total notification count The total number of unread notifications for this room
Left Room
Name Type Description
account_data Account Data The private data that this user has attached to this room.
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.

200 response body example

{
  "account_data": {
    "events": [
      {
        "content": {
          "custom_config_key": "custom_config_value"
        },
        "type": "org.example.custom.config"
      }
    ]
  },
  "next_batch": "s72595_4483_1934",
  "presence": {
    "events": [
      {
        "content": {
          "avatar_url": "mxc://localhost:wefuiwegh8742w",
          "currently_active": false,
          "key": "value",
          "last_active_ago": 2478593,
          "presence": "online",
          "status_msg": "Making cupcakes"
        },
        "sender": "@example:localhost",
        "type": "m.presence"
      }
    ]
  },
  "rooms": {
    "invite": {
      "!696r7674:example.com": {
        "invite_state": {
          "events": [
            {
              "content": {
                "name": "My Room Name"
              },
              "sender": "@alice:example.com",
              "state_key": "",
              "type": "m.room.name"
            },
            {
              "content": {
                "membership": "invite"
              },
              "sender": "@alice:example.com",
              "state_key": "@bob:example.com",
              "type": "m.room.member"
            }
          ]
        }
      }
    },
    "join": {
      "!726s6s6q:example.com": {
        "account_data": {
          "events": [
            {
              "content": {
                "key": "value",
                "tags": {
                  "u.work": {
                    "order": 0.9
                  }
                }
              },
              "type": "m.tag"
            },
            {
              "content": {
                "custom_config_key": "custom_config_value"
              },
              "type": "org.example.custom.room.config"
            }
          ]
        },
        "ephemeral": {
          "events": [
            {
              "content": {
                "key": "value",
                "user_ids": [
                  "@alice:matrix.org",
                  "@bob:example.com"
                ]
              },
              "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
              "type": "m.typing"
            }
          ]
        },
        "state": {
          "events": [
            {
              "content": {
                "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
                "displayname": "Alice Margatroid",
                "key": "value",
                "membership": "join"
              },
              "event_id": "$143273582443PhrSn:example.org",
              "origin_server_ts": 1432735824653,
              "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
              "sender": "@example:example.org",
              "state_key": "@alice:example.org",
              "type": "m.room.member",
              "unsigned": {
                "age": 1234
              }
            }
          ]
        },
        "summary": {
          "m.heroes": [
            "@alice:example.com",
            "@bob:example.com"
          ],
          "m.invited_member_count": 0,
          "m.joined_member_count": 2
        },
        "timeline": {
          "events": [
            {
              "content": {
                "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
                "displayname": "Alice Margatroid",
                "key": "value",
                "membership": "join"
              },
              "event_id": "$143273582443PhrSn:example.org",
              "origin_server_ts": 1432735824653,
              "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
              "sender": "@example:example.org",
              "state_key": "@alice:example.org",
              "type": "m.room.member",
              "unsigned": {
                "age": 1234
              }
            },
            {
              "content": {
                "body": "This is an example text message",
                "format": "org.matrix.custom.html",
                "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
                "key": "value",
                "msgtype": "m.text"
              },
              "event_id": "$143273582443PhrSn:example.org",
              "origin_server_ts": 1432735824653,
              "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
              "sender": "@example:example.org",
              "type": "m.room.message",
              "unsigned": {
                "age": 1234
              }
            }
          ],
          "limited": true,
          "prev_batch": "t34-23535_0_0"
        }
      }
    },
    "leave": {}
  }
}

GET /_matrix/client/r0/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.

This endpoint was deprecated in r0 of this specification. Clients should instead call the |/sync|_ API with a since parameter. See the migration guide &lt;https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints&gt;_.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
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.

Responses

Status Description
200 The events received, which may be none.
400 Bad pagination from parameter.

200 response body

Name 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
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.

200 response body example

{
  "chunk": [
    {
      "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
        "key": "value",
        "msgtype": "m.text"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "end": "s3457_9_0",
  "start": "s3456_9_0"
}

GET /_matrix/client/r0/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.

This endpoint was deprecated in r0 of this specification. Clients should instead call the |/rooms/{roomId}/event/{eventId}|_ API or the |/rooms/{roomId}/context/{eventId}|_ API.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

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

Responses

Status Description
200 The full event.
404 The event was not found or you do not have permission to read this event.

200 response body

Event
Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’

200 response body example

{
  "content": {
    "body": "This is an example text message",
    "format": "org.matrix.custom.html",
    "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
    "key": "value",
    "msgtype": "m.text"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.message",
  "unsigned": {
    "age": 1234
  }
}

GET /_matrix/client/r0/initialSync


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

This endpoint was deprecated in r0 of this specification. Clients should instead call the |/sync|_ API with no since parameter. See the migration guide &lt;https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints&gt;_.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
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.
limit integer The maximum number of messages to return for each room.

Responses

Status Description
200 The user’s current state.
404 There is no avatar URL for this user or this user does not exist.

200 response body

Name Type Description
account_data [Event] The global private data created by this user.
end string Required: 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] Required: A list of presence events.
rooms [RoomInfo] Required:
Event
Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
RoomInfo
Name Type Description
account_data [Event] The private data that this user has attached to this room.
invite InviteEvent The invite event if membership is invite
membership enum Required: 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 Required: 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
Name Type Description
content EventContent Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: The user_id this membership event relates to. In all cases except for when membership is join, the user ID sending the event does not need to match the user ID in the state_key, unlike other events. Regular authorisation rules still apply.
type enum Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’

One of: [m.room.member].

unsigned UnsignedData Contains optional extra information about the event.
EventContent
Name Type Description
avatar_url string The avatar URL for this user, if any.
displayname [string null] The display name for this user, if any.
is_direct boolean Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging_.
membership enum Required: The membership state of the user.

One of: [invite join knock leave ban].

third_party_invite Invite
Invite
Name Type Description
display_name string Required: A name which can be displayed to represent the user instead of their third party identifier
signed signed Required: A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.
signed
Name Type Description
mxid string Required: The invited matrix user ID. Must be equal to the user_id property of the event.
signatures Signatures Required: A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.
token string Required: The token property of the containing third_party_invite object.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
invite_room_state [StrippedState] A subset of the state of the room at the time of the invite, if membership is invite. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for m.room.avatar, m.room.canonical_alias, m.room.join_rules, and m.room.name SHOULD be included.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
StrippedState
Name Type Description
content EventContent Required: The content for the event.
sender string Required: The sender for the event.
state_key string Required: The state_key for the event.
type string Required: The type for the event.
PaginationChunk
Name Type Description
chunk [RoomEvent] Required: 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 Required: A token which correlates to the last value in chunk. Used for pagination.
start string Required: A token which correlates to the first value in chunk. Used for pagination.
RoomEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
StateEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.

200 response body example

{
  "account_data": [
    {
      "content": {
        "custom_config_key": "custom_config_value"
      },
      "type": "org.example.custom.config"
    }
  ],
  "end": "s3456_9_0",
  "presence": [
    {
      "content": {
        "avatar_url": "mxc://localhost:wefuiwegh8742w",
        "currently_active": false,
        "key": "value",
        "last_active_ago": 2478593,
        "presence": "online",
        "status_msg": "Making cupcakes"
      },
      "sender": "@example:localhost",
      "type": "m.presence"
    }
  ],
  "rooms": [
    {
      "account_data": [
        {
          "content": {
            "tags": {
              "work": {
                "order": 1
              }
            }
          },
          "type": "m.tag"
        },
        {
          "content": {
            "custom_config_key": "custom_config_value"
          },
          "type": "org.example.custom.room.config"
        }
      ],
      "membership": "join",
      "messages": {
        "chunk": [
          {
            "content": {
              "body": "This is an example text message",
              "format": "org.matrix.custom.html",
              "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
              "key": "value",
              "msgtype": "m.text"
            },
            "event_id": "$143273582443PhrSn:example.org",
            "origin_server_ts": 1432735824653,
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "sender": "@example:example.org",
            "type": "m.room.message",
            "unsigned": {
              "age": 1234
            }
          },
          {
            "content": {
              "body": "Gangnam Style",
              "info": {
                "duration": 2140786,
                "h": 320,
                "mimetype": "video/mp4",
                "size": 1563685,
                "thumbnail_info": {
                  "h": 300,
                  "mimetype": "image/jpeg",
                  "size": 46144,
                  "w": 300
                },
                "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
                "w": 480
              },
              "key": "value",
              "msgtype": "m.video",
              "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
            },
            "event_id": "$143273582443PhrSn:example.org",
            "origin_server_ts": 1432735824653,
            "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
            "sender": "@example:example.org",
            "type": "m.room.message",
            "unsigned": {
              "age": 1234
            }
          }
        ],
        "end": "s3456_9_0",
        "start": "t44-3453_9_0"
      },
      "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
      "state": [
        {
          "content": {
            "join_rule": "public",
            "key": "value"
          },
          "event_id": "$143273582443PhrSn:example.org",
          "origin_server_ts": 1432735824653,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "sender": "@example:example.org",
          "state_key": "",
          "type": "m.room.join_rules",
          "unsigned": {
            "age": 1234
          }
        },
        {
          "content": {
            "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
            "displayname": "Alice Margatroid",
            "key": "value",
            "membership": "join"
          },
          "event_id": "$143273582443PhrSn:example.org",
          "origin_server_ts": 1432735824653,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "sender": "@example:example.org",
          "state_key": "@alice:example.org",
          "type": "m.room.member",
          "unsigned": {
            "age": 1234
          }
        },
        {
          "content": {
            "creator": "@example:example.org",
            "key": "value",
            "m.federate": true,
            "predecessor": {
              "event_id": "$something:example.org",
              "room_id": "!oldroom:example.org"
            },
            "room_version": "1"
          },
          "event_id": "$143273582443PhrSn:example.org",
          "origin_server_ts": 1432735824653,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "sender": "@example:example.org",
          "state_key": "",
          "type": "m.room.create",
          "unsigned": {
            "age": 1234
          }
        },
        {
          "content": {
            "ban": 50,
            "events": {
              "m.room.name": 100,
              "m.room.power_levels": 100
            },
            "events_default": 0,
            "invite": 50,
            "key": "value",
            "kick": 50,
            "notifications": {
              "room": 20
            },
            "redact": 50,
            "state_default": 50,
            "users": {
              "@example:localhost": 100
            },
            "users_default": 0
          },
          "event_id": "$143273582443PhrSn:example.org",
          "origin_server_ts": 1432735824653,
          "room_id": "!TmaZBKYIFrIPVGoUYp:localhost",
          "sender": "@example:example.org",
          "state_key": "",
          "type": "m.room.power_levels",
          "unsigned": {
            "age": 1234
          }
        }
      ],
      "visibility": "private"
    }
  ]
}

Getting events for a room

There are several APIs provided to GET events for a room:

GET /_matrix/client/r0/rooms/{roomId}/event/{eventId}


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

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventId string Required: The event ID to get.
roomId string Required: The ID of the room the event is in.

Responses

Status Description
200 The full event.
404 The event was not found or you do not have permission to read this event.

200 response body

Event
Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’

200 response body example

{
  "content": {
    "body": "This is an example text message",
    "format": "org.matrix.custom.html",
    "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
    "key": "value",
    "msgtype": "m.text"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "room_id": "!636q39766251:matrix.org",
  "sender": "@example:example.org",
  "type": "m.room.message",
  "unsigned": {
    "age": 1234
  }
}

GET /_matrix/client/r0/rooms/{roomId}/joined_members


This API returns a map of MXIDs to member info objects for members of the room. The current user must be in the room for it to work, unless it is an Application Service in which case any of the AS's users must be in the room. This API is primarily for Application Services and should be faster to respond than ``/members`` as it can be implemented more efficiently on the server.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room to get the members of.

Responses

Status Description
200 A map of MXID to room member objects.
403 You aren’t a member of the room.

200 response body

Name Type Description
joined object A map from user ID to a RoomMember object.
RoomMember
Name Type Description
avatar_url string The mxc avatar url of the user this object is representing.
display_name string The display name of the user this object is representing.

200 response body example

{
  "joined": {
    "@bar:example.com": {
      "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK",
      "display_name": "Bar"
    }
  }
}

GET /_matrix/client/r0/rooms/{roomId}/members


Get the list of members for this room.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room to get the member events for.
query parameters
Name Type Description
at string The point in time (pagination token) to return members for in the room. This token can be obtained from a prev_batch token returned for each room by the sync API. Defaults to the current state of the room, as determined by the server.
membership enum The kind of membership to filter for. Defaults to no filtering if unspecified. When specified alongside not_membership, the two parameters create an ‘or’ condition: either the membership is the same as membership or is not the same as not_membership.

One of: [join invite leave ban].

not_membership enum The kind of membership to exclude from the results. Defaults to no filtering if unspecified.

One of: [join invite leave ban].

Responses

Status Description
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 the room then this will be the members of the room when you left.
403 You aren’t a member of the room and weren’t previously a member of the room.

200 response body

Name Type Description
chunk [MemberEvent]
MemberEvent
Name Type Description
content EventContent Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: The user_id this membership event relates to. In all cases except for when membership is join, the user ID sending the event does not need to match the user ID in the state_key, unlike other events. Regular authorisation rules still apply.
type enum Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’

One of: [m.room.member].

unsigned UnsignedData Contains optional extra information about the event.
EventContent
Name Type Description
avatar_url string The avatar URL for this user, if any.
displayname [string null] The display name for this user, if any.
is_direct boolean Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging_.
membership enum Required: The membership state of the user.

One of: [invite join knock leave ban].

third_party_invite Invite
Invite
Name Type Description
display_name string Required: A name which can be displayed to represent the user instead of their third party identifier
signed signed Required: A block of content which has been signed, which servers can use to verify the event. Clients should ignore this.
signed
Name Type Description
mxid string Required: The invited matrix user ID. Must be equal to the user_id property of the event.
signatures Signatures Required: A single signature from the verifying server, in the format specified by the Signing Events section of the server-server API.
token string Required: The token property of the containing third_party_invite object.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
invite_room_state [StrippedState] A subset of the state of the room at the time of the invite, if membership is invite. Note that this state is informational, and SHOULD NOT be trusted; once the client has joined the room, it SHOULD fetch the live state from the server and discard the invite_room_state. Also, clients must not rely on any particular state being present here; they SHOULD behave properly (with possibly a degraded but not a broken experience) in the absence of any particular events here. If they are set on the room, at least the state for m.room.avatar, m.room.canonical_alias, m.room.join_rules, and m.room.name SHOULD be included.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
StrippedState
Name Type Description
content EventContent Required: The content for the event.
sender string Required: The sender for the event.
state_key string Required: The state_key for the event.
type string Required: The type for the event.

200 response body example

{
  "chunk": [
    {
      "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "key": "value",
        "membership": "join"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "@alice:example.org",
      "type": "m.room.member",
      "unsigned": {
        "age": 1234
      }
    }
  ]
}

GET /_matrix/client/r0/rooms/{roomId}/state


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

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

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

Responses

Status Description
200 The current state of the room
403 You aren’t a member of the room and weren’t previously a member of the room.

200 response body

Array of StateEvent.

StateEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.

200 response body example

[
  {
    "content": {
      "join_rule": "public",
      "key": "value"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!636q39766251:example.com",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.join_rules",
    "unsigned": {
      "age": 1234
    }
  },
  {
    "content": {
      "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
      "displayname": "Alice Margatroid",
      "key": "value",
      "membership": "join"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!636q39766251:example.com",
    "sender": "@example:example.org",
    "state_key": "@alice:example.org",
    "type": "m.room.member",
    "unsigned": {
      "age": 1234
    }
  },
  {
    "content": {
      "creator": "@example:example.org",
      "key": "value",
      "m.federate": true,
      "predecessor": {
        "event_id": "$something:example.org",
        "room_id": "!oldroom:example.org"
      },
      "room_version": "1"
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!636q39766251:example.com",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.create",
    "unsigned": {
      "age": 1234
    }
  },
  {
    "content": {
      "ban": 50,
      "events": {
        "m.room.name": 100,
        "m.room.power_levels": 100
      },
      "events_default": 0,
      "invite": 50,
      "key": "value",
      "kick": 50,
      "notifications": {
        "room": 20
      },
      "redact": 50,
      "state_default": 50,
      "users": {
        "@example:localhost": 100
      },
      "users_default": 0
    },
    "event_id": "$143273582443PhrSn:example.org",
    "origin_server_ts": 1432735824653,
    "room_id": "!636q39766251:example.com",
    "sender": "@example:example.org",
    "state_key": "",
    "type": "m.room.power_levels",
    "unsigned": {
      "age": 1234
    }
  }
]

GET /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}


.. For backwards compatibility with older links... .. _`get-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:

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.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventType string Required: The type of state to look up.
roomId string Required: The room to look up the state in.
stateKey string Required: The key of the state to look up. Defaults to an empty string. When an empty string, the trailing slash on this endpoint is optional.

Responses

Status Description
200 The content of the state event.
403 You aren’t a member of the room and weren’t previously a member of the room.
404 The room has no state with the given type or key.

GET /_matrix/client/r0/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.

Note: This endpoint supports lazy-loading of room member events. See Lazy-loading room members &lt;#lazy-loading-room-members&gt;_ for more information.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room to get events from.
query parameters
Name Type Description
dir enum Required: The direction to return events from.

One of: [b f].

filter string A JSON RoomEventFilter to filter returned events with.
from string Required: The token to start returning events from. This token can be obtained from a prev_batch token returned for each room by the sync API, or from a start or end token returned by a previous request to this endpoint.
limit integer The maximum number of events to return. Default: 10.
to string The token to stop returning events at. This token can be obtained from a prev_batch token returned for each room by the sync endpoint, or from a start or end token returned by a previous request to this endpoint.

Responses

Status Description
200 A list of messages with a new token to request more.
403 You aren’t a member of the room.

200 response body

Name Type Description
chunk [RoomEvent] A list of room events. The order depends on the dir parameter. For dir=b events will be in reverse-chronological order, for dir=f in chronological order, so that events start at the from point.
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 the pagination starts from. If dir=b this will be the token supplied in from.
state [StateEvent]

A list of state events relevant to showing the chunk. For example, if lazy_load_members is enabled in the filter then this may contain the membership events for the senders of events in the chunk.

Unless include_redundant_members is true, the server may remove membership events which would have already been sent to the client in prior calls to this endpoint, assuming the membership of those members has not changed.

RoomEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
StateEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.

200 response body example

{
  "chunk": [
    {
      "content": {
        "body": "This is an example text message",
        "format": "org.matrix.custom.html",
        "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
        "key": "value",
        "msgtype": "m.text"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "room_id": "!636q39766251:example.com"
    },
    {
      "content": {
        "body": "Gangnam Style",
        "info": {
          "duration": 2140786,
          "h": 320,
          "mimetype": "video/mp4",
          "size": 1563685,
          "thumbnail_info": {
            "h": 300,
            "mimetype": "image/jpeg",
            "size": 46144,
            "w": 300
          },
          "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe",
          "w": 480
        },
        "key": "value",
        "msgtype": "m.video",
        "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "type": "m.room.message",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "end": "t47409-4357353_219380_26003_2265",
  "start": "t47429-4392820_219380_26003_2265"
}

GET /_matrix/client/r0/rooms/{roomId}/initialSync


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

This endpoint was deprecated in r0 of this specification. There is no direct replacement; the relevant information is returned by the |/sync|_ API. See the migration guide &lt;https://matrix.org/docs/guides/client-server-migrating-from-v1.html#deprecated-endpoints&gt;_.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

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

Responses

Status Description
200 The current state of the room
403 You aren’t a member of the room and weren’t previously a member of the room.

200 response body

RoomInfo
Name Type Description
account_data [Event] The private data that this user has attached to this room.
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 Required: 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].

Event
Name Type Description
content object Required: 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 Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
PaginationChunk
Name Type Description
chunk [RoomEvent] Required: 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 Required: A token which correlates to the last value in chunk. Used for pagination.
start string Required: A token which correlates to the first value in chunk. Used for pagination.
RoomEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.
UnsignedData
Name Type Description
age integer The time in milliseconds that has elapsed since the event was sent. This field is generated by the local homeserver, and may be incorrect if the local time on at least one of the two servers is out of sync, which can cause the age to either be negative or greater than it actually is.
redacted_because Event The event that redacted this event, if any.
transaction_id string The client-supplied transaction ID, for example, provided via PUT /_matrix/client/r0/rooms/{roomId}/send/{eventType}/{txnId}, if the client being given the event is the same one which sent it.
StateEvent
Name Type Description
content object Required: The fields in this object will vary depending on the type of event. When interacting with the REST API, this is the HTTP body.
event_id string Required: The globally unique event identifier.
origin_server_ts integer Required: Timestamp in milliseconds on originating homeserver when this event was sent.
prev_content EventContent Optional. The previous content for this event. If there is no previous content, this key will be missing.
room_id string Required: The ID of the room associated with this event. Will not be present on events that arrive through /sync, despite being required everywhere else.
sender string Required: Contains the fully-qualified ID of the user who sent this event.
state_key string Required: 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. State keys starting with an @ are reserved for referencing user IDs, such as room members. With the exception of a few events, state events set with a given user’s ID as the state key MUST only be set by that user.
type string Required: The type of event. This SHOULD be namespaced similar to Java package naming conventions e.g. ‘com.example.subdomain.event.type’
unsigned UnsignedData Contains optional extra information about the event.

200 response body example

{
  "account_data": [
    {
      "content": {
        "tags": {
          "work": {
            "order": "1"
          }
        }
      },
      "type": "m.tag"
    }
  ],
  "membership": "join",
  "messages": {
    "chunk": [
      {
        "content": {
          "body": "This is an example text message",
          "format": "org.matrix.custom.html",
          "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
          "key": "value",
          "msgtype": "m.text"
        },
        "event_id": "$143273582443PhrSn:example.org",
        "origin_server_ts": 1432735824653,
        "room_id": "!636q39766251:example.com",
        "sender": "@example:example.org",
        "type": "m.room.message",
        "unsigned": {
          "age": 1234
        }
      },
      {
        "content": {
          "body": "something-important.doc",
          "filename": "something-important.doc",
          "info": {
            "mimetype": "application/msword",
            "size": 46144
          },
          "key": "value",
          "msgtype": "m.file",
          "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe"
        },
        "event_id": "$143273582443PhrSn:example.org",
        "origin_server_ts": 1432735824653,
        "room_id": "!636q39766251:example.com",
        "sender": "@example:example.org",
        "type": "m.room.message",
        "unsigned": {
          "age": 1234
        }
      }
    ],
    "end": "s3456_9_0",
    "start": "t44-3453_9_0"
  },
  "room_id": "!636q39766251:example.com",
  "state": [
    {
      "content": {
        "join_rule": "public",
        "key": "value"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "",
      "type": "m.room.join_rules",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
        "displayname": "Alice Margatroid",
        "key": "value",
        "membership": "join"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "@alice:example.org",
      "type": "m.room.member",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "creator": "@example:example.org",
        "key": "value",
        "m.federate": true,
        "predecessor": {
          "event_id": "$something:example.org",
          "room_id": "!oldroom:example.org"
        },
        "room_version": "1"
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "",
      "type": "m.room.create",
      "unsigned": {
        "age": 1234
      }
    },
    {
      "content": {
        "ban": 50,
        "events": {
          "m.room.name": 100,
          "m.room.power_levels": 100
        },
        "events_default": 0,
        "invite": 50,
        "key": "value",
        "kick": 50,
        "notifications": {
          "room": 20
        },
        "redact": 50,
        "state_default": 50,
        "users": {
          "@example:localhost": 100
        },
        "users_default": 0
      },
      "event_id": "$143273582443PhrSn:example.org",
      "origin_server_ts": 1432735824653,
      "room_id": "!636q39766251:example.com",
      "sender": "@example:example.org",
      "state_key": "",
      "type": "m.room.power_levels",
      "unsigned": {
        "age": 1234
      }
    }
  ],
  "visibility": "private"
}

Sending events to a room

PUT /_matrix/client/r0/rooms/{roomId}/state/{eventType}/{stateKey}


.. For backwards compatibility with older links... .. _`put-matrix-client-%CLIENT_MAJOR_VERSION%-rooms-roomid-state-eventtype`:

State events can be sent using this endpoint. These events will be overwritten if &lt;room id&gt;, &lt;event type&gt; and &lt;state key&gt; all match.

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.

If the event type being sent is m.room.canonical_alias servers SHOULD ensure that any new aliases being listed in the event are valid per their grammar/syntax and that they point to the room ID where the state event is to be sent. Servers do not validate aliases which are being removed or are already present in the state event.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventType string Required: The type of event to send.
roomId string Required: The room to set the state in
stateKey string Required: The state_key for the state to send. Defaults to the empty string. When an empty string, the trailing slash on this endpoint is optional.

Request body

Request body example

{
  "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
  "displayname": "Alice Margatroid",
  "membership": "join"
}

Responses

Status Description
200 An ID for the sent event.
400

The sender’s request is malformed.

Some example error codes include:

  • M_INVALID_PARAMETER: One or more aliases within the m.room.canonical_alias event have invalid syntax.

  • M_BAD_ALIAS: One or more aliases within the m.room.canonical_alias event do not point to the room ID for which the state event is to be sent to.

403 The sender doesn’t have permission to send the event into the room.

200 response body

Name Type Description
event_id string Required: A unique identifier for the event.

200 response body example

{
  "event_id": "$YUwRidLecu:example.com"
}

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%3Aexample.org
{ "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" }

PUT /_matrix/client/r0/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.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventType string Required: The type of event to send.
roomId string Required: The room to send the event to.
txnId string Required: The transaction ID for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests.

Request body

Request body example

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

Responses

Status Description
200 An ID for the sent event.

200 response body

Name Type Description
event_id string Required: A unique identifier for the event.

200 response body example

{
  "event_id": "$YUwRidLecu:example.com"
}

Redactions

Since events are extensible it is possible for malicious users and/or servers to add keys that are, for example offensive or illegal. Since some events cannot be simply deleted, e.g. membership events, we instead ‘redact’ events. This involves removing all keys from an event that are not required by the protocol. This stripped down event is thereafter returned anytime a client or remote server requests it. Redacting an event cannot be undone, allowing server owners to delete the offending content from the databases. Events that have been redacted include a redacted_because key whose value is the event that caused it to be redacted, which may include a reason.

The exact algorithm to apply against an event is defined in the room version specification.

The server should add the event causing the redaction to the unsigned property of the redacted event, under the redacted_because key. When a client receives a redaction event it should change the redacted event in the same way a server does.

Note

Redacted events can still affect the state of the room. When redacted, state events behave as though their properties were simply not specified, except those protected by the redaction algorithm. For example, a redacted join event will still result in the user being considered joined. Similarly, a redacted topic does not necessarily cause the topic to revert to what is was prior to the event - it causes the topic to be removed from the room.

Events

m.room.redaction


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.

Event type: Message event

Content

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

Examples

{
  "content": {
    "key": "value",
    "reason": "Spamming"
  },
  "event_id": "$143273582443PhrSn:example.org",
  "origin_server_ts": 1432735824653,
  "redacts": "$fukweghifu23:localhost",
  "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
  "sender": "@example:example.org",
  "type": "m.room.redaction",
  "unsigned": {
    "age": 1234
  }
}
Client behaviour

PUT /_matrix/client/r0/rooms/{roomId}/redact/{eventId}/{txnId}


Strips all information out of an event which isn't critical to the integrity of the server-side representation of the room.

This cannot be undone.

Users may redact their own events, and any user with a power level greater than or equal to the redact power level of the room may redact events there.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventId string Required: The ID of the event to redact
roomId string Required: The room from which to redact the event.
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.

Request body

Name Type Description
reason string The reason for the event being redacted.

Request body example

{
  "reason": "Indecent material"
}

Responses

Status Description
200 An ID for the redaction event.

200 response body

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

200 response body example

{
  "event_id": "$YUwQidLecu:example.com"
}

Rooms

Creation

The homeserver will create an m.room.create event when a room is created, which serves as the root of the event graph for this room. This event also has a creator key which contains the user ID of the room creator. It will also generate several other events in order to manage permissions in this room. This includes:

  • m.room.power_levels : Sets the power levels of users and required power
    levels for various actions within the room such as sending events.

  • m.room.join_rules : Whether the room is “invite-only” or not.

See Room Events for more information on these events. To create a room, a client has to use the following API.

POST /_matrix/client/r0/createRoom


Create a new room with various configuration options.

The server MUST apply the normal state resolution rules when creating the new room, including checking power levels for each event. It MUST apply the events implied by the request in the following order:

  1. The m.room.create event itself. Must be the first event in the room.

  2. An m.room.member event for the creator to join the room. This is needed so the remaining events can be sent.

  3. A default m.room.power_levels event, giving the room creator (and not other members) permission to send state events. Overridden by the power_level_content_override parameter.

  4. Events set by the preset. Currently these are the m.room.join_rules, m.room.history_visibility, and m.room.guest_access state events.

  5. Events listed in initial_state, in the order that they are listed.

  6. Events implied by name and topic (m.room.name and m.room.topic state events).

  7. Invite events implied by invite and invite_3pid (m.room.member with membership: invite and m.room.third_party_invite).

The available presets do the following with respect to room state:

======================== ============== ====================== ================ ========= Preset join_rules history_visibility guest_access Other ======================== ============== ====================== ================ ========= private_chat invite shared can_join trusted_private_chat invite shared can_join All invitees are given the same power level as the room creator. public_chat public shared forbidden ======================== ============== ====================== ================ =========

The server will create a m.room.create event in the room with the requesting user as the creator, alongside other keys provided in the creation_content.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
creation_content CreationContent Extra keys, such as m.federate, to be added to the content of the m.room.create_ event. The server will clobber the following keys: creator, room_version. Future versions of the specification may allow the server to clobber other keys.
initial_state [StateEvent]

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 preset, but gets overriden by name and topic keys.

invite [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.
invite_3pid [Invite3pid] A list of objects representing third party IDs to invite into the room.
is_direct boolean This flag makes the server set the is_direct flag on the m.room.member events sent to the users in invite and invite_3pid. See Direct Messaging_ for more information.
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.
power_level_content_override Power Level Event Content The power level content to override in the default power level event. This object is applied on top of the generated m.room.power_levels_ event content prior to it being sent to the room. Defaults to overriding nothing.
preset enum

Convenience parameter for setting various default state events based on a preset.

If unspecified, the server should use the visibility to determine which preset to use. A visbility of public equates to a preset of public_chat and private visibility equates to a preset of private_chat.

One of: [private_chat public_chat trusted_private_chat].

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 homeserver 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.

The complete room alias will become the canonical alias for the room.

room_version string The room version to set for the room. If not provided, the homeserver is to use its configured default. If provided, the homeserver will return a 400 error with the errcode M_UNSUPPORTED_ROOM_VERSION if it does not support the room version.
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.
visibility enum 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.

One of: [public private].

StateEvent
Name Type Description
content object Required: The content of the event.
state_key string The state_key of the state event. Defaults to an empty string.
type string Required: The type of event to send.
Invite3pid
Name Type Description
address string Required: The invitee’s third party identifier.
id_access_token string Required: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
id_server string Required: The hostname+port of the identity server which should be used for third party identifier lookups.
medium string Required: The kind of address being passed in the address field, for example email.

Request body example

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

Responses

Status Description
200 Information about the newly created room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • The room alias specified is already taken (errcode set to M_ROOM_IN_USE).

  • The initial state implied by the parameters to the request is invalid: for example, the user’s power_level is set below that necessary to set the room name (errcode set to M_INVALID_ROOM_STATE).

  • The homeserver doesn’t support the requested room version, or one or more users being invited to the new room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

200 response body

Name Type Description
room_id string Required: The created room’s ID.

200 response body example

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

Room aliases

Servers may host aliases for rooms with human-friendly names. Aliases take the form #friendlyname:server.name.

As room aliases are scoped to a particular homeserver domain name, it is likely that a homeserver will reject attempts to maintain aliases on other domain names. This specification does not provide a way for homeservers to send update requests to other servers. However, homeservers MUST handle GET requests to resolve aliases on other servers; they should do this using the federation API if necessary.

Rooms do not store a list of all aliases present on a room, though members of the room with relevant permissions may publish preferred aliases through the m.room.canonical_alias state event. The aliases in the state event should point to the room ID they are published within, however room aliases can and do drift to other room IDs over time. Clients SHOULD NOT treat the aliases as accurate. They SHOULD be checked before they are used or shared with another user. If a room appears to have a room alias of #alias:example.com, this SHOULD be checked to make sure that the room’s ID matches the room_id returned from the request.

GET /_matrix/client/r0/directory/room/{roomAlias}


Requests that the server resolve a room alias to a room ID.

The server will use the federation API to resolve the alias if the domain part of the alias does not correspond to the server's own domain.

Rate-limited: No
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
roomAlias string Required: The room alias.

Responses

Status Description
200 The room ID and other information for this alias.
404 There is no mapped room ID for this room alias.

200 response body

Name Type Description
room_id string The room ID for this room alias.
servers [string] A list of servers that are aware of this room alias.

200 response body example

{
  "room_id": "!abnjk1jdasj98:capuchins.com",
  "servers": [
    "capuchins.com",
    "matrix.org",
    "another.com"
  ]
}

PUT /_matrix/client/r0/directory/room/{roomAlias}


Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomAlias string Required: The room alias to set.

Request body

Name Type Description
room_id string Required: The room ID to set.

Request body example

{
  "room_id": "!abnjk1jdasj98:capuchins.com"
}

Responses

Status Description
200 The mapping was created.
409 A room alias with that name already exists.

DELETE /_matrix/client/r0/directory/room/{roomAlias}


Remove a mapping of room alias to room ID.

Servers may choose to implement additional access control checks here, for instance that room aliases can only be deleted by their creator or a server administrator.

.. Note:: Servers may choose to update the alt_aliases for the m.room.canonical_alias state event in the room when an alias is removed. Servers which choose to update the canonical alias event are recommended to, in addition to their other relevant permission checks, delete the alias and return a successful response even if the user does not have permission to update the m.room.canonical_alias event.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomAlias string Required: The room alias to remove.

Responses

Status Description
200 The mapping was deleted.
404 There is no mapped room ID for this room alias.

GET /_matrix/client/r0/rooms/{roomId}/aliases


Get a list of aliases maintained by the local server for the given room.

This endpoint can be called by users who are in the room (external users receive an M_FORBIDDEN error response). If the room's m.room.history_visibility maps to world_readable, any user can call this endpoint.

Servers may choose to implement additional access control checks here, such as allowing server administrators to view aliases regardless of membership.

.. Note:: Clients are recommended not to display this list of aliases prominently as they are not curated, unlike those listed in the m.room.canonical_alias state event.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room ID to find local aliases of.

Responses

Status Description
200 The list of local aliases for the room.
403 The user is not permitted to retrieve the list of local aliases for the room.
429 This request was rate-limited.

200 response body

Name Type Description
aliases [string] Required: The server’s local aliases on the room. Can be empty.

200 response body example

{
  "aliases": [
    "#somewhere:example.com",
    "#another:example.com",
    "#hat_trick:example.com"
  ]
}

Permissions

Note

This section is a work in progress.

Permissions for rooms are done via the concept of power levels - to do any action in a room a user must have a suitable power level. Power levels are stored as state events in a given room. The power levels required for operations and the power levels for users are defined in m.room.power_levels, where both a default and specific users' power levels can be set. By default all users have a power level of 0, other than the room creator whose power level defaults to 100. Users can grant other users increased power levels up to their own power level. For example, user A with a power level of 50 could increase the power level of user B to a maximum of level 50. Power levels for users are tracked per-room even if the user is not present in the room. The keys contained in m.room.power_levels determine the levels required for certain operations such as kicking, banning and sending state events. See m.room.power_levels for more information.

Clients may wish to assign names to particular power levels. A suggested mapping is as follows: - 0 User - 50 Moderator - 100 Admin

Room membership

Users need to be a member of a room in order to send and receive events in that room. There are several states in which a user may be, in relation to a room:

  • Unrelated (the user cannot send or receive events in the room)
  • Invited (the user has been invited to participate in the room, but is not yet participating)
  • Joined (the user can send and receive events in the room)
  • Banned (the user is not allowed to join the room)

There is an exception to the requirement that a user join a room before sending events to it: users may send an m.room.member event to a room with content.membership set to leave to reject an invitation if they have currently been invited to a room but have not joined it.

Some rooms require that users be invited to it before they can join; others allow anyone to join. Whether a given room is an “invite-only” room is determined by the room config key m.room.join_rules. It can have one of the following values:

public
This room is free for anyone to join without an invite.

invite
This room can only be joined if you were invited.

The allowable state transitions of membership are:

/ban
+------------------------------------------------------+
|                                                      |
|  +----------------+  +----------------+              |
|  |    /leave      |  |                |              |
|  |                v  v                |              |
/invite    +--------+           +-------+             |              |
------------>| invite |<----------| leave |----+        |              |
+--------+  /invite  +-------+    |        |              |
|                   |    ^      |        |              |
|                   |    |      |        |              |
/join |   +---------------+    |      |        |              |
|   | /join if           |      |        |              |
|   | join_rules         |      | /ban   | /unban       |
|   | public      /leave |      |        |              |
v   v               or   |      |        |              |
+------+            /kick  |      |        |              |
------------>| join |-------------------+      |        |              |
/join       +------+                          v        |              |
if             |                           +-----+     |              |
join_rules     +-------------------------->| ban |-----+              |
public                   /ban              +-----+                    |
         ^ ^                      |
         | |                      |
----------------------------------------------+ +----------------------+
/ban

GET /_matrix/client/r0/joined_rooms


This API returns a list of the user's current rooms.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 A list of the rooms the user is in.

200 response body

Name Type Description
joined_rooms [string] Required: The ID of each room in which the user has joined membership.

200 response body example

{
  "joined_rooms": [
    "!foo:example.com"
  ]
}
Joining rooms

POST /_matrix/client/r0/rooms/{roomId}/invite


.. _invite-by-user-id-endpoint:

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 homeserver will append a m.room.member event to the room.

.. third party invites section: invite-by-third-party-id-endpoint

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) to which to invite the user.

Request body

Name Type Description
user_id string Required: The fully qualified user ID of the invitee.

Request body example

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

Responses

Status Description
200 The user has been invited to join the room.
400

The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:

  • The request body is malformed (errcode set to M_BAD_JSON or M_NOT_JSON).

  • One or more users being invited to the room are residents of a homeserver which does not support the requested room version. The errcode will be M_UNSUPPORTED_ROOM_VERSION in these cases.

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.
429 This request was rate-limited.

POST /_matrix/client/r0/join/{roomIdOrAlias}


*Note that this API takes either a room ID or alias, unlike* ``/room/{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|_ and |/sync|_ APIs.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomIdOrAlias string Required: The room identifier or alias to join.
query parameters
Name Type Description
server_name [] The servers to attempt to join the room through. One of the servers must be participating in the room.

Request body

Name Type Description
third_party_signed Third Party Signed If a third_party_signed was supplied, the homeserver must verify that it matches a pending m.room.third_party_invite event in the room, and perform key validity checking if required by the event.
Third Party Signed
Name Type Description
mxid string Required: The Matrix ID of the invitee.
sender string Required: The Matrix ID of the user who issued the invite.
signatures Signatures Required: A signatures object containing a signature of the entire signed object.
token string Required: The state key of the m.third_party_invite event.

Request body example

{
  "third_party_signed": {
    "mxid": "@bob:example.org",
    "sender": "@alice:example.org",
    "signatures": {
      "example.org": {
        "ed25519:0": "some9signature"
      }
    },
    "token": "random8nonce"
  }
}

Responses

Status Description
200

The room has been joined.

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

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.
429 This request was rate-limited.

200 response body

Name Type Description
room_id string Required: The joined room ID.

200 response body example

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

POST /_matrix/client/r0/rooms/{roomId}/join


*Note that this API requires a room ID, not alias.* ``/join/{roomIdOrAlias}`` *exists if you have a room alias.*

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|_ and |/sync|_ APIs.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) to join.

Request body

Name Type Description
third_party_signed Third Party Signed If supplied, the homeserver must verify that it matches a pending m.room.third_party_invite event in the room, and perform key validity checking if required by the event.
Third Party Signed
Name Type Description
mxid string Required: The Matrix ID of the invitee.
sender string Required: The Matrix ID of the user who issued the invite.
signatures Signatures Required: A signatures object containing a signature of the entire signed object.
token string Required: The state key of the m.third_party_invite event.

Request body example

{
  "third_party_signed": {
    "mxid": "@bob:example.org",
    "sender": "@alice:example.org",
    "signatures": {
      "example.org": {
        "ed25519:0": "some9signature"
      }
    },
    "token": "random8nonce"
  }
}

Responses

Status Description
200

The room has been joined.

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

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.
429 This request was rate-limited.

200 response body

Name Type Description
room_id string Required: The joined room ID.

200 response body example

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

A user can leave a room to stop receiving events for that room. A user must have been invited to or have joined the room before they are eligible to leave the room. Leaving a room to which the user has been invited rejects the invite. Once a user leaves a room, it will no longer appear in the response to the /sync_ API unless it is explicitly requested via a filter with the include_leave field set to true.

Whether or not they actually joined the room, if the room is an “invite-only” room the user will need to be re-invited before they can re-join the room.

A user can also forget a room which they have left. Rooms which have been forgotten will never appear the response to the /sync_ API, until the user re-joins or is re-invited.

A user may wish to force another user to leave a room. This can be done by ‘kicking’ the other user. To do so, the user performing the kick MUST have the required power level. Once a user has been kicked, the behaviour is the same as if they had left of their own accord. In particular, the user is free to re-join if the room is not “invite-only”.

POST /_matrix/client/r0/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 must leave the room before calling this API.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

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

Responses

Status Description
200 The room has been forgotten.
400 The user has not left the room
429 This request was rate-limited.

POST /_matrix/client/r0/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 authentication: Yes

Request

Request parameters

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

Responses

Status Description
200 The room has been left.
429 This request was rate-limited.

POST /_matrix/client/r0/rooms/{roomId}/kick


Kick a user from the room.

The caller must have the required power level in order to perform this operation.

Kicking a user adjusts the target member's membership state to be leave with an optional reason. Like with other membership changes, a user can directly adjust the target member's state by making a request to /rooms/&lt;room id&gt;/state/m.room.member/&lt;user id&gt;.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) from which the user should be kicked.

Request body

Name Type Description
reason string The reason the user has been kicked. This will be supplied as the reason on the target’s updated m.room.member_ event.
user_id string Required: The fully qualified user ID of the user being kicked.

Request body example

{
  "reason": "Telling unfunny jokes",
  "user_id": "@cheeky_monkey:matrix.org"
}

Responses

Status Description
200 The user has been kicked from the room.
403

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

  • The kicker is not currently in the room.
  • The kickee is not currently in the room.
  • The kicker’s power level is insufficient to kick users from the room.
Banning users in a room

A user may decide to ban another user in a room. ‘Banning’ forces the target user to leave the room and prevents them from re-joining the room. A banned user will not be treated as a joined user, and so will not be able to send or receive events in the room. In order to ban someone, the user performing the ban MUST have the required power level. To ban a user, a request should be made to /rooms/<room_id>/ban_ with:

{
  "user_id": "<user id to ban>"
  "reason": "string: <reason for the ban>"
}

Banning a user adjusts the banned member’s membership state to ban. Like with other membership changes, a user can directly adjust the target member’s state, by making a request to /rooms/<room id>/state/m.room.member/<user id>:

{
  "membership": "ban"
}

A user must be explicitly unbanned with a request to /rooms/<room_id>/unban_ before they can re-join the room or be re-invited.

POST /_matrix/client/r0/rooms/{roomId}/ban


Ban a user in the room. If the user is currently in the room, also kick them.

When a user is banned from a room, they may not join it or be invited to it until they are unbanned.

The caller must have the required power level in order to perform this operation.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) from which the user should be banned.

Request body

Name Type Description
reason string The reason the user has been banned. This will be supplied as the reason on the target’s updated m.room.member_ event.
user_id string Required: The fully qualified user ID of the user being banned.

Request body example

{
  "reason": "Telling unfunny jokes",
  "user_id": "@cheeky_monkey:matrix.org"
}

Responses

Status Description
200 The user has been kicked and banned from the room.
403

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

  • The banner is not currently in the room.
  • The banner’s power level is insufficient to ban users from the room.

POST /_matrix/client/r0/rooms/{roomId}/unban


Unban a user from the room. This allows them to be invited to the room, and join if they would otherwise be allowed to join according to its join rules.

The caller must have the required power level in order to perform this operation.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) from which the user should be unbanned.

Request body

Name Type Description
user_id string Required: The fully qualified user ID of the user being unbanned.

Request body example

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

Responses

Status Description
200 The user has been unbanned from the room.
403

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

  • The unbanner’s power level is insufficient to unban users from the room.

Listing rooms

GET /_matrix/client/r0/directory/list/room/{roomId}


Gets the visibility of a given room on the server's public room directory.

Rate-limited: No
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room ID.

Responses

Status Description
200 The visibility of the room in the directory
404 The room is not known to the server

200 response body

Name Type Description
visibility enum The visibility of the room in the directory.

One of: [private public].

200 response body example

{
  "visibility": "public"
}

PUT /_matrix/client/r0/directory/list/room/{roomId}


Sets the visibility of a given room in the server's public room directory.

Servers may choose to implement additional access control checks here, for instance that room visibility can only be changed by the room creator or a server administrator.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room ID.

Request body

Name Type Description
visibility enum The new visibility setting for the room. Defaults to ‘public’.

One of: [private public].

Request body example

{
  "visibility": "public"
}

Responses

Status Description
200 The visibility was updated, or no change was needed.
404 The room is not known to the server

GET /_matrix/client/r0/publicRooms


Lists the public rooms on the server.

This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first.

Rate-limited: No
Requires authentication: No

Request

Request parameters

query parameters
Name Type Description
limit integer Limit the number of results returned.
server string The server to fetch the public room lists from. Defaults to the local server.
since string A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag.

Responses

Status Description
200 A list of the rooms on the server.

200 response body

Name Type Description
chunk PublicRoomsChunks Required: A paginated chunk of public rooms.
next_batch string A pagination token for the response. The absence of this token means there are no more results to fetch and the client should stop paginating.
prev_batch string A pagination token that allows fetching previous results. The absence of this token means there are no results before this batch, i.e. this is the first batch.
total_room_count_estimate integer An estimate on the total number of public rooms, if the server has an estimate.
PublicRoomsChunk
Name Type Description
aliases [string] Aliases of the room. May be empty.
avatar_url string The URL for the room’s avatar, if one is set.
canonical_alias string The canonical alias of the room, if any.
guest_can_join boolean Required: 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.
num_joined_members integer Required: The number of members joined to the room.
room_id string Required: The ID of the room.
topic string The topic of the room, if any.
world_readable boolean Required: Whether the room may be viewed by guest users without joining.

200 response body example

{
  "chunk": [
    {
      "aliases": [
        "#murrays:cheese.bar"
      ],
      "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}

POST /_matrix/client/r0/publicRooms


Lists the public rooms on the server, with optional filter.

This API returns paginated responses. The rooms are ordered by the number of joined members, with the largest rooms first.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
server string The server to fetch the public room lists from. Defaults to the local server.

Request body

Name Type Description
filter Filter Filter to apply to the results.
include_all_networks boolean Whether or not to include all known networks/protocols from application services on the homeserver. Defaults to false.
limit integer Limit the number of results returned.
since string A pagination token from a previous request, allowing clients to get the next (or previous) batch of rooms. The direction of pagination is specified solely by which token is supplied, rather than via an explicit flag.
third_party_instance_id string The specific third party network/protocol to request from the homeserver. Can only be used if include_all_networks is false.
Filter
Name Type Description
generic_search_term string A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional).

Request body example

{
  "filter": {
    "generic_search_term": "foo"
  },
  "include_all_networks": false,
  "limit": 10,
  "third_party_instance_id": "irc"
}

Responses

Status Description
200 A list of the rooms on the server.

200 response body

Name Type Description
chunk PublicRoomsChunks Required: A paginated chunk of public rooms.
next_batch string A pagination token for the response. The absence of this token means there are no more results to fetch and the client should stop paginating.
prev_batch string A pagination token that allows fetching previous results. The absence of this token means there are no results before this batch, i.e. this is the first batch.
total_room_count_estimate integer An estimate on the total number of public rooms, if the server has an estimate.
PublicRoomsChunk
Name Type Description
aliases [string] Aliases of the room. May be empty.
avatar_url string The URL for the room’s avatar, if one is set.
canonical_alias string The canonical alias of the room, if any.
guest_can_join boolean Required: 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.
num_joined_members integer Required: The number of members joined to the room.
room_id string Required: The ID of the room.
topic string The topic of the room, if any.
world_readable boolean Required: Whether the room may be viewed by guest users without joining.

200 response body example

{
  "chunk": [
    {
      "aliases": [
        "#murrays:cheese.bar"
      ],
      "avatar_url": "mxc://bleeker.street/CHEDDARandBRIE",
      "guest_can_join": false,
      "name": "CHEESE",
      "num_joined_members": 37,
      "room_id": "!ol19s:bleecker.street",
      "topic": "Tasty tasty cheese",
      "world_readable": true
    }
  ],
  "next_batch": "p190q",
  "prev_batch": "p1902",
  "total_room_count_estimate": 115
}

User Data

User Directory

POST /_matrix/client/r0/user_directory/search


Performs a search for users. The homeserver may determine which subset of users are searched, however the homeserver MUST at a minimum consider the users the requesting user shares a room with and those who reside in public rooms (known to the homeserver). The search MUST consider local users to the homeserver, and SHOULD query remote users as part of the search.

The search is performed case-insensitively on user IDs and display names preferably using a collation determined based upon the Accept-Language header provided in the request, if present.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
limit integer The maximum number of results to return. Defaults to 10.
search_term string Required: The term to search for

Request body example

{
  "limit": 10,
  "search_term": "foo"
}

Responses

Status Description
200 The results of the search.
429 This request was rate-limited.

200 response body

Name Type Description
limited boolean Required: Indicates if the result list has been truncated by the limit.
results [User] Required: Ordered by rank and then whether or not profile info is available.
User
Name Type Description
avatar_url string The avatar url, as an MXC, if one exists.
display_name string The display name of the user, if one exists.
user_id string Required: The user’s matrix user ID.

200 response body example

{
  "limited": false,
  "results": [
    {
      "avatar_url": "mxc://bar.com/foo",
      "display_name": "Foo",
      "user_id": "@foo:bar.com"
    }
  ]
}

Profiles

GET /_matrix/client/r0/profile/{userId}


Get the combined profile information for this user. This API may be used to fetch the user's own profile information or other users; either locally or on remote homeservers. This API may return keys which are not limited to ``displayname`` or ``avatar_url``.

Rate-limited: No
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose profile information to get.

Responses

Status Description
200 The avatar URL for this user.
404 There is no profile information for this user or this user does not exist.

200 response body

Name Type Description
avatar_url string The user’s avatar URL if they have set one, otherwise not present.
displayname string The user’s display name if they have set one, otherwise not present.

200 response body example

{
  "avatar_url": "mxc://matrix.org/SDGdghriugerRg",
  "displayname": "Alice Margatroid"
}

GET /_matrix/client/r0/profile/{userId}/avatar_url


Get the user's avatar URL. This API may be used to fetch the user's own avatar URL or to query the URL of other users; either locally or on remote homeservers.

Rate-limited: No
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose avatar URL to get.

Responses

Status Description
200 The avatar URL for this user.
404 There is no avatar URL for this user or this user does not exist.

200 response body

Name Type Description
avatar_url string The user’s avatar URL if they have set one, otherwise not present.

200 response body example

{
  "avatar_url": "mxc://matrix.org/SDGdghriugerRg"
}

PUT /_matrix/client/r0/profile/{userId}/avatar_url


This API sets the given user's avatar URL. You must have permission to set this user's avatar URL, e.g. you need to have their ``access_token``.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose avatar URL to set.

Request body

Name Type Description
avatar_url string The new avatar URL for this user.

Request body example

{
  "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34"
}

Responses

Status Description
200 The avatar URL was set.
429 This request was rate-limited.

GET /_matrix/client/r0/profile/{userId}/displayname


Get the user's display name. This API may be used to fetch the user's own displayname or to query the name of other users; either locally or on remote homeservers.

Rate-limited: No
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose display name to get.

Responses

Status Description
200 The display name for this user.
404 There is no display name for this user or this user does not exist.

200 response body

Name Type Description
displayname string The user’s display name if they have set one, otherwise not present.

200 response body example

{
  "displayname": "Alice Margatroid"
}

PUT /_matrix/client/r0/profile/{userId}/displayname


This API sets the given user's display name. You must have permission to set this user's display name, e.g. you need to have their ``access_token``.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose display name to set.

Request body

Name Type Description
displayname string The new display name for this user.

Request body example

{
  "displayname": "Alice Margatroid"
}

Responses

Status Description
200 The display name was set.
429 This request was rate-limited.
Events on Change of Profile Information

Because the profile display name and avatar information are likely to be used in many places of a client’s display, changes to these fields cause an automatic propagation event to occur, informing likely-interested parties of the new values. This change is conveyed using two separate mechanisms:

  • a m.room.member event (with a join membership) is sent to every room the user is a member of, to update the displayname and avatar_url.
  • a m.presence presence status update is sent, again containing the new values of the displayname and avatar_url keys, in addition to the required presence key containing the current presence state of the user.

Both of these should be done automatically by the homeserver when a user successfully changes their display name or avatar URL fields.

Additionally, when homeservers emit room membership events for their own users, they should include the display name and avatar URL fields in these events so that clients already have these details to hand, and do not have to perform extra round trips to query it.

Security

Rate limiting

Homeservers SHOULD implement rate limiting to reduce the risk of being overloaded. If a request is refused due to rate limiting, it should return a standard error response of the form:

{
  "errcode": "M_LIMIT_EXCEEDED",
  "error": "string",
  "retry_after_ms": integer (optional)
}

The retry_after_ms key SHOULD be included to tell the client how long they have to wait in milliseconds before they can try again.

Modules

Instant Messaging

This module adds support for sending human-readable messages to a room. It also adds support for associating human-readable information with the room itself such as a room name and topic.

Events

{{m_room_message_event}}

{{m_room_message_feedback_event}}

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.

{{m_room_name_event}}

{{m_room_topic_event}}

{{m_room_avatar_event}}

{{m_room_pinned_events_event}}

m.room.message msgtypes

Each m.room.message MUST have a msgtype key which identifies the type of message being sent. Each type has their own required and optional keys, as outlined below. If a client cannot display the given msgtype then it SHOULD display the fallback plain text body key instead.

Some message types support HTML in the event content that clients should prefer to display if available. Currently m.text, m.emote, and m.notice support an additional format parameter of org.matrix.custom.html. When this field is present, a formatted_body with the HTML must be provided. The plain text version of the HTML should be provided in the body.

Clients should limit the HTML they render to avoid Cross-Site Scripting, HTML injection, and similar attacks. The strongly suggested set of HTML tags to permit, denying the use and rendering of anything else, is: font, del, h1, h2, h3, h4, h5, h6, blockquote, p, a, ul, ol, sup, sub, li, b, i, u, strong, em, strike, code, hr, br, div, table, thead, tbody, tr, th, td, caption, pre, span, img.

Not all attributes on those tags should be permitted as they may be avenues for other disruption attempts, such as adding onclick handlers or excessively large text. Clients should only permit the attributes listed for the tags below. Where data-mx-bg-color and data-mx-color are listed, clients should translate the value (a 6-character hex color code) to the appropriate CSS/attributes for the tag.

font
data-mx-bg-color, data-mx-color

span
data-mx-bg-color, data-mx-color

a
name, target, href (provided the value is not relative and has a scheme matching one of: https, http, ftp, mailto, magnet)

img
width, height, alt, title, src (provided it is a Matrix Content (MXC) URI)

ol
start

code
class (only classes which start with language- for syntax highlighting)

Additionally, web clients should ensure that all a tags get a rel="noopener" to prevent the target page from referencing the client’s tab/window.

Tags must not be nested more than 100 levels deep. Clients should only support the subset of tags they can render, falling back to other representations of the tags where possible. For example, a client may not be able to render tables correctly and instead could fall back to rendering tab-delimited text.

In addition to not rendering unsafe HTML, clients should not emit unsafe HTML in events. Likewise, clients should not generate HTML that is not needed, such as extra paragraph tags surrounding text due to Rich Text Editors. HTML included in events should otherwise be valid, such as having appropriate closing tags, appropriate attributes (considering the custom ones defined in this specification), and generally valid structure.

A special tag, mx-reply, may appear on rich replies (described below) and should be allowed if, and only if, the tag appears as the very first tag in the formatted_body. The tag cannot be nested and cannot be located after another tag in the tree. Because the tag contains HTML, an mx-reply is expected to have a partner closing tag and should be treated similar to a div. Clients that support rich replies will end up stripping the tag and its contents and therefore may wish to exclude the tag entirely.

Note

A future iteration of the specification will support more powerful and extensible message formatting options, such as the proposal MSC1225.

{{msgtype_events}}

Client behaviour

Clients SHOULD verify the structure of incoming events to ensure that the expected keys exist and that they are of the right type. Clients can discard malformed events or display a placeholder message to the user. Redacted m.room.message events MUST be removed from the client. This can either be replaced with placeholder text (e.g. “[REDACTED]") or the redacted message can be removed entirely from the messages view.

Events which have attachments (e.g. m.image, m.file) SHOULD be uploaded using the content repository module where available. The resulting mxc:// URI can then be used in the url key.

Clients MAY include a client generated thumbnail image for an attachment under a info.thumbnail_url key. The thumbnail SHOULD also be a mxc:// URI. Clients displaying events with attachments can either use the client generated thumbnail or ask its homeserver to generate a thumbnail from the original attachment using the content repository module.

Recommendations when sending messages

In the event of send failure, clients SHOULD retry requests using an exponential-backoff algorithm for a certain amount of time T. It is recommended that T is no longer than 5 minutes. After this time, the client should stop retrying and mark the message as “unsent”. Users should be able to manually resend unsent messages.

Users may type several messages at once and send them all in quick succession. Clients SHOULD preserve the order in which they were sent by the user. This means that clients should wait for the response to the previous request before sending the next request. This can lead to head-of-line blocking. In order to reduce the impact of head-of-line blocking, clients should use a queue per room rather than a global queue, as ordering is only relevant within a single room rather than between rooms.

Local echo

Messages SHOULD appear immediately in the message view when a user presses the “send” button. This should occur even if the message is still sending. This is referred to as “local echo”. Clients SHOULD implement “local echo” of messages. Clients MAY display messages in a different format to indicate that the server has not processed the message. This format should be removed when the server responds.

Clients need to be able to match the message they are sending with the same message which they receive from the event stream. The echo of the same message from the event stream is referred to as “remote echo”. Both echoes need to be identified as the same message in order to prevent duplicate messages being displayed. Ideally this pairing would occur transparently to the user: the UI would not flicker as it transitions from local to remote. Flickering can be reduced through clients making use of the transaction ID they used to send a particular event. The transaction ID used will be included in the event’s unsigned data as transaction_id when it arrives through the event stream.

Clients unable to make use of the transaction ID are likely to experience flickering when the remote echo arrives on the event stream before the request to send the message completes. In that case the event arrives before the client has obtained an event ID, making it impossible to identify it as a remote echo. This results in the client displaying the message twice for some time (depending on the server responsiveness) before the original request to send the message completes. Once it completes, the client can take remedial actions to remove the duplicate event by looking for duplicate event IDs.

Calculating the display name for a user

Clients may wish to show the human-readable display name of a room member as part of a membership list, or when they send a message. However, different members may have conflicting display names. Display names MUST be disambiguated before showing them to the user, in order to prevent spoofing of other users.

To ensure this is done consistently across clients, clients SHOULD use the following algorithm to calculate a disambiguated display name for a given user:

  1. Inspect the m.room.member state event for the relevant user id.
  2. If the m.room.member state event has no displayname field, or if that field has a null value, use the raw user id as the display name. Otherwise:
  3. If the m.room.member event has a displayname which is unique among members of the room with membership: join or membership: invite, use the given displayname as the user-visible display name. Otherwise:
  4. The m.room.member event has a non-unique displayname. This should be disambiguated using the user id, for example “display name (@id:homeserver.org)”.

Developers should take note of the following when implementing the above algorithm:

  • The user-visible display name of one member can be affected by changes in the state of another member. For example, if @user1:matrix.org is present in a room, with displayname: Alice, then when @user2:example.com joins the room, also with displayname: Alice, both users must be given disambiguated display names. Similarly, when one of the users then changes their display name, there is no longer a clash, and both users can be given their chosen display name. Clients should be alert to this possibility and ensure that all affected users are correctly renamed.
  • The display name of a room may also be affected by changes in the membership list. This is due to the room name sometimes being based on user display names (see Calculating the display name for a room).
  • If the entire membership list is searched for clashing display names, this leads to an O(N^2) implementation for building the list of room members. This will be very inefficient for rooms with large numbers of members. It is recommended that client implementations maintain a hash table mapping from displayname to a list of room members using that name. Such a table can then be used for efficient calculation of whether disambiguation is needed.
Displaying membership information with messages

Clients may wish to show the display name and avatar URL of the room member who sent a message. This can be achieved by inspecting the m.room.member state event for that user ID (see Calculating the display name for a user).

When a user paginates the message history, clients may wish to show the historical display name and avatar URL for a room member. This is possible because older m.room.member events are returned when paginating. This can be implemented efficiently by keeping two sets of room state: old and current. As new events arrive and/or the user paginates back in time, these two sets of state diverge from each other. New events update the current state and paginated events update the old state. When paginated events are processed sequentially, the old state represents the state of the room at the time the event was sent. This can then be used to set the historical display name and avatar URL.

Calculating the display name for a room

Clients may wish to show a human-readable name for a room. There are a number of possibilities for choosing a useful name. To ensure that rooms are named consistently across clients, clients SHOULD use the following algorithm to choose a name:

  1. If the room has an m.room.name state event with a non-empty name field, use the name given by that field.
  2. If the room has an m.room.canonical_alias state event with a valid alias field, use the alias given by that field as the name. Note that clients should avoid using alt_aliases when calculating the room name.
  3. If none of the above conditions are met, a name should be composed based on the members of the room. Clients should consider m.room.member events for users other than the logged-in user, as defined below.
    1. If the number of m.heroes for the room are greater or equal to m.joined_member_count + m.invited_member_count - 1, then use the membership events for the heroes to calculate display names for the users (disambiguating them if required) and concatenating them. For example, the client may choose to show “Alice, Bob, and Charlie (@charlie:example.org)” as the room name. The client may optionally limit the number of users it uses to generate a room name.
    2. If there are fewer heroes than m.joined_member_count + m.invited_member_count - 1, and m.joined_member_count + m.invited_member_count is greater than 1, the client should use the heroes to calculate display names for the users (disambiguating them if required) and concatenating them alongside a count of the remaining users. For example, “Alice, Bob, and 1234 others”.
    3. If m.joined_member_count + m.invited_member_count is less than or equal to 1 (indicating the member is alone), the client should use the rules above to indicate that the room was empty. For example, “Empty Room (was Alice)”, “Empty Room (was Alice and 1234 others)”, or “Empty Room” if there are no heroes.

Clients SHOULD internationalise the room name to the user’s language when using the m.heroes to calculate the name. Clients SHOULD use minimum 5 heroes to calculate room names where possible, but may use more or less to fit better with their user experience.

Forming relationships between events

In some cases, events may wish to reference other events. This could be to form a thread of messages for the user to follow along with, or to provide more context as to what a particular event is describing. Currently, the only kind of relation defined is a “rich reply” where a user may reference another message to create a thread-like conversation.

Relationships are defined under an m.relates_to key in the event’s content. If the event is of the type m.room.encrypted, the m.relates_to key MUST NOT be covered by the encryption and instead be put alongside the encryption information held in the content.

Rich replies

Users may wish to reference another message when forming their own message, and clients may wish to better embed the referenced message for the user to have a better context for the conversation being had. This sort of embedding another message in a message is known as a “rich reply”, or occasionally just a “reply”.

A rich reply is formed through use of an m.relates_to relation for m.in_reply_to where a single key, event_id, is used to reference the event being replied to. The referenced event ID SHOULD belong to the same room where the reply is being sent. Clients should be cautious of the event ID belonging to another room, or being invalid entirely. Rich replies can only be constructed in the form of m.room.message events with a msgtype of m.text or m.notice. Due to the fallback requirements, rich replies cannot be constructed for types of m.emote, m.file, etc. Rich replies may reference any other m.room.message event, however. Rich replies may reference another event which also has a rich reply, infinitely.

An m.in_reply_to relationship looks like the following:

{
  ...
  "type": "m.room.message",
  "content": {
    "msgtype": "m.text",
    "body": "<body including fallback>",
    "format": "org.matrix.custom.html",
    "formatted_body": "<HTML including fallback>",
    "m.relates_to": {
      "m.in_reply_to": {
        "event_id": "$another:event.com"
      }
    }
  }
}

####### Fallbacks and event representation

Some clients may not have support for rich replies and therefore need a fallback to use instead. Clients that do not support rich replies should render the event as if rich replies were not special.

Clients that do support rich replies MUST provide the fallback format on replies, and MUST strip the fallback before rendering the reply. Rich replies MUST have a format of org.matrix.custom.html and therefore a formatted_body alongside the body and appropriate msgtype. The specific fallback text is different for each msgtype, however the general format for the body is:

> <@alice:example.org> This is the original body

This is where the reply goes

The formatted_body should use the following template:

<mx-reply>
  <blockquote>
    <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
    <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
    <br />
    <!-- This is where the related event's HTML would be. -->
  </blockquote>
</mx-reply>
This is where the reply goes.

If the related event does not have a formatted_body, the event’s body should be considered after encoding any HTML special characters. Note that the href in both of the anchors use a matrix.to URI.

######## Stripping the fallback

Clients which support rich replies MUST strip the fallback from the event before rendering the event. This is because the text provided in the fallback cannot be trusted to be an accurate representation of the event. After removing the fallback, clients are recommended to represent the event referenced by m.in_reply_to similar to the fallback’s representation, although clients do have creative freedom for their user interface. Clients should prefer the formatted_body over the body, just like with other m.room.message events.

To strip the fallback on the body, the client should iterate over each line of the string, removing any lines that start with the fallback prefix ("> “, including the space, without quotes) and stopping when a line is encountered without the prefix. This prefix is known as the “fallback prefix sequence”.

To strip the fallback on the formatted_body, the client should remove the entirety of the mx-reply tag.

######## Fallback for m.text, m.notice, and unrecognised message types

Using the prefix sequence, the first line of the related event’s body should be prefixed with the user’s ID, followed by each line being prefixed with the fallback prefix sequence. For example:

> <@alice:example.org> This is the first line
> This is the second line

This is the reply

The formatted_body uses the template defined earlier in this section.

######## Fallback for m.emote

Similar to the fallback for m.text, each line gets prefixed with the fallback prefix sequence. However an asterisk should be inserted before the user’s ID, like so:

> * <@alice:example.org> feels like today is going to be a great day

This is the reply

The formatted_body has a subtle difference for the template where the asterisk is also inserted ahead of the user’s ID:

<mx-reply>
  <blockquote>
    <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a>
    * <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a>
    <br />
    <!-- This is where the related event's HTML would be. -->
  </blockquote>
</mx-reply>
This is where the reply goes.

######## Fallback for m.image, m.video, m.audio, and m.file

The related event’s body would be a file name, which may not be very descriptive. The related event should additionally not have a format or formatted_body in the content - if the event does have a format and/or formatted_body, those fields should be ignored. Because the filename alone may not be descriptive, the related event’s body should be considered to be "sent a file." such that the output looks similar to the following:

> <@alice:example.org> sent a file.

This is the reply

<mx-reply> <blockquote> <a href="https://matrix.to/#/!somewhere:example.org/$event:example.org">In reply to</a> <a href="https://matrix.to/#/@alice:example.org">@alice:example.org</a> <br /> sent a file. </blockquote> </mx-reply> This is where the reply goes.

For m.image, the text should be "sent an image.". For m.video, the text should be "sent a video.". For m.audio, the text should be "sent an audio file".

Server behaviour

Homeservers SHOULD reject m.room.message events which don’t have a msgtype key, or which don’t have a textual body key, with an HTTP status code of 400.

Security considerations

Messages sent using this module are not encrypted, although end to end encryption is in development (see E2E module).

Clients should sanitise all displayed keys for unsafe HTML to prevent Cross-Site Scripting (XSS) attacks. This includes room names and topics.

Voice over IP

This module outlines how two users in a room can set up a Voice over IP (VoIP) call to each other. Voice and video calls are built upon the WebRTC 1.0 standard. Call signalling is achieved by sending message events to the room. In this version of the spec, only two-party communication is supported (e.g. between two peers, or between a peer and a multi-point conferencing unit). This means that clients MUST only send call events to rooms with exactly two participants.

Events

{{voip_events}}

Client behaviour

A call is set up with message events exchanged as follows:

Caller                    Callee
[Place Call]
m.call.invite ----------->
m.call.candidate -------->
[..candidates..] -------->
                        [Answers call]
       <--------------- m.call.answer
 [Call is active and ongoing]
       <--------------- m.call.hangup

Or a rejected call:

Caller                      Callee
m.call.invite ------------>
m.call.candidate --------->
[..candidates..] --------->
                         [Rejects call]
         <-------------- m.call.hangup

Calls are negotiated according to the WebRTC specification.

Glare

“Glare” is a problem which occurs when two users call each other at roughly the same time. This results in the call failing to set up as there already is an incoming/outgoing call. A glare resolution algorithm can be used to determine which call to hangup and which call to answer. If both clients implement the same algorithm then they will both select the same call and the call will be successfully connected.

As calls are “placed” to rooms rather than users, the glare resolution algorithm outlined below is only considered for calls which are to the same room. The algorithm is as follows:

  • If an m.call.invite to a room is received whilst the client is preparing to send an m.call.invite to the same room:
    • the client should cancel its outgoing call and instead automatically accept the incoming call on behalf of the user.
  • If an m.call.invite to a room is received after the client has sent an m.call.invite to the same room and is waiting for a response:
    • the client should perform a lexicographical comparison of the call IDs of the two calls and use the lesser of the two calls, aborting the greater. If the incoming call is the lesser, the client should accept this call on behalf of the user.

The call setup should appear seamless to the user as if they had simply placed a call and the other party had accepted. This means any media stream that had been setup for use on a call should be transferred and used for the call that replaces it.

Server behaviour

The homeserver MAY provide a TURN server which clients can use to contact the remote party. The following HTTP API endpoints will be used by clients in order to get information about the TURN server.

GET /_matrix/client/r0/voip/turnServer


This API provides credentials for the client to use when initiating calls.

Rate-limited: Yes
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The TURN server credentials.
429 This request was rate-limited.

200 response body

Name Type Description
password string Required: The password to use.
ttl integer Required: The time-to-live in seconds
uris [string] Required: A list of TURN URIs
username string Required: The username to use.

200 response body example

{
  "password": "JlKfBy1QwLrO20385QyAtEyIv0=",
  "ttl": 86400,
  "uris": [
    "turn:turn.example.com:3478?transport=udp",
    "turn:10.20.30.40:3478?transport=tcp",
    "turns:10.20.30.40:443?transport=tcp"
  ],
  "username": "1443779631:@user:example.com"
}

Security considerations

Calls should only be placed to rooms with one other user in them. If they are placed to group chat rooms it is possible that another user will intercept and answer the call.

Typing Notifications

Users may wish to be informed when another user is typing in a room. This can be achieved using typing notifications. These are ephemeral events scoped to a room_id. This means they do not form part of the Event Graph but still have a room_id key.

Events

{{m_typing_event}}

Client behaviour

When a client receives an m.typing event, it MUST use the user ID list to REPLACE its knowledge of every user who is currently typing. The reason for this is that the server does not remember users who are not currently typing as that list gets big quickly. The client should mark as not typing any user ID who is not in that list.

It is recommended that clients store a boolean indicating whether the user is typing or not. Whilst this value is true a timer should fire periodically every N seconds to send a typing HTTP request. The value of N is recommended to be no more than 20-30 seconds. This request should be re-sent by the client to continue informing the server the user is still typing. As subsequent requests will replace older requests, a safety margin of 5 seconds before the expected timeout runs out is recommended. When the user stops typing, the state change of the boolean to false should trigger another HTTP request to inform the server that the user has stopped typing.

PUT /_matrix/client/r0/rooms/{roomId}/typing/{userId}


This tells the server that the user is typing for the next N milliseconds where N is the value specified in the ``timeout`` key. Alternatively, if ``typing`` is ``false``, it tells the server that the user has stopped typing.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room in which the user is typing.
userId string Required: The user who has started to type.

Request body

Name Type Description
timeout integer The length of time in milliseconds to mark this user as typing.
typing boolean Required: Whether the user is typing or not. If false, the timeout key can be omitted.

Request body example

{
  "timeout": 30000,
  "typing": true
}

Responses

Status Description
200 The new typing state was set.
429 This request was rate-limited.

Security considerations

Clients may not wish to inform everyone in a room that they are typing and instead only specific users in the room.

Receipts

This module adds in support for receipts. These receipts are a form of acknowledgement of an event. This module defines a single acknowledgement: m.read which indicates that the user has read up to a given event.

Sending a receipt for each event can result in sending large amounts of traffic to a homeserver. To prevent this from becoming a problem, receipts are implemented using “up to” markers. This marker indicates that the acknowledgement applies to all events “up to and including” the event specified. For example, marking an event as “read” would indicate that the user had read all events up to the referenced event. See the Receiving notifications section for more information on how read receipts affect notification counts.

Events

Each user_id, receipt_type pair must be associated with only a single event_id.

{{m_receipt_event}}

Client behaviour

In /sync, receipts are listed under the ephemeral array of events for a given room. New receipts that come down the event streams are deltas which update existing mappings. Clients should replace older receipt acknowledgements based on user_id and receipt_type pairs. For example:

Client receives m.receipt:
  user = @alice:example.com
  receipt_type = m.read
  event_id = $aaa:example.com

Client receives another m.receipt: user = @alice:example.com receipt_type = m.read event_id = $bbb:example.com

The client should replace the older acknowledgement for $aaa:example.com with this one for $bbb:example.com

Clients should send read receipts when there is some certainty that the event in question has been displayed to the user. Simply receiving an event does not provide enough certainty that the user has seen the event. The user SHOULD need to take some action such as viewing the room that the event was sent to or dismissing a notification in order for the event to count as “read”. Clients SHOULD NOT send read receipts for events sent by their own user.

A client can update the markers for its user by interacting with the following HTTP APIs.

POST /_matrix/client/r0/rooms/{roomId}/receipt/{receiptType}/{eventId}


This API updates the marker for the given receipt type to the event ID specified.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventId string Required: The event ID to acknowledge up to.
receiptType enum Required: The type of receipt to send.

One of: [m.read].

roomId string Required: The room in which to send the event.

Request body

Request body example

{}

Responses

Status Description
200 The receipt was sent.
429 This request was rate-limited.

Server behaviour

For efficiency, receipts SHOULD be batched into one event per room before delivering them to clients.

Receipts are sent across federation as EDUs with type m.receipt. The format of the EDUs are:

{
    <room_id>: {
        <receipt_type>: {
            <user_id>: { <content> }
        },
        ...
    },
    ...
}

These are always sent as deltas to previously sent receipts. Currently only a single <receipt_type> should be used: m.read.

Security considerations

As receipts are sent outside the context of the event graph, there are no integrity checks performed on the contents of m.receipt events.

Fully read markers

The history for a given room may be split into three sections: messages the user has read (or indicated they aren’t interested in them), messages the user might have read some but not others, and messages the user hasn’t seen yet. The “fully read marker” (also known as a “read marker”) marks the last event of the first section, whereas the user’s read receipt marks the last event of the second section.

Events

The user’s fully read marker is kept as an event in the room’s account data. The event may be read to determine the user’s current fully read marker location in the room, and just like other account data events the event will be pushed down the event stream when updated.

The fully read marker is kept under an m.fully_read event. If the event does not exist on the user’s account data, the fully read marker should be considered to be the user’s read receipt location.

{{m_fully_read_event}}

Client behaviour

The client cannot update fully read markers by directly modifying the m.fully_read account data event. Instead, the client must make use of the read markers API to change the values.

The read markers API can additionally update the user’s read receipt (m.read) location in the same operation as setting the fully read marker location. This is because read receipts and read markers are commonly updated at the same time, and therefore the client might wish to save an extra HTTP call. Providing an m.read location performs the same task as a request to /receipt/m.read/$event:example.org.

POST /_matrix/client/r0/rooms/{roomId}/read_markers


Sets the position of the read marker for a given room, and optionally the read receipt's location.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room ID to set the read marker in for the user.

Request body

Name Type Description
m.fully_read string Required: The event ID the read marker should be located at. The event MUST belong to the room.
m.read string The event ID to set the read receipt location at. This is equivalent to calling /receipt/m.read/$elsewhere:example.org and is provided here to save that extra call.

Request body example

{
  "m.fully_read": "$somewhere:example.org",
  "m.read": "$elsewhere:example.org"
}

Responses

Status Description
200 The read marker, and read receipt if provided, have been updated.
429 This request was rate-limited.

Server behaviour

The server MUST prevent clients from setting m.fully_read directly in room account data. The server must additionally ensure that it treats the presence of m.read in the /read_markers request the same as how it would for a request to /receipt/m.read/$event:example.org.

Upon updating the m.fully_read event due to a request to /read_markers, the server MUST send the updated account data event through to the client via the event stream (eg: /sync), provided any applicable filters are also satisfied.

Presence

Each user has the concept of presence information. This encodes:

  • Whether the user is currently online
  • How recently the user was last active (as seen by the server)
  • Whether a given client considers the user to be currently idle
  • Arbitrary information about the user’s current status (e.g. “in a meeting”).

This information is collated from both per-device (online, idle, last_active) and per-user (status) data, aggregated by the user’s homeserver and transmitted as an m.presence event. Presence events are sent to interested parties where users share a room membership.

User’s presence state is represented by the presence key, which is an enum of one of the following:

  • online : The default state when the user is connected to an event stream.
  • unavailable : The user is not reachable at this time e.g. they are idle.
  • offline : The user is not connected to an event stream or is explicitly suppressing their profile information from being sent.

Events

{{presence_events}}

Client behaviour

Clients can manually set/get their presence using the HTTP APIs listed below.

GET /_matrix/client/r0/presence/{userId}/status


Get the given user's presence state.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose presence state to get.

Responses

Status Description
200 The presence state for this user.
403 You are not allowed to see this user’s presence status.
404 There is no presence state for this user. This user may not exist or isn’t exposing presence information to you.

200 response body

Name Type Description
currently_active boolean Whether the user is currently active
last_active_ago integer The length of time in milliseconds since an action was performed by this user.
presence enum Required: This user’s presence.

One of: [online offline unavailable].

status_msg [string null] The state message for this user if one was set.

200 response body example

{
  "last_active_ago": 420845,
  "presence": "unavailable"
}

PUT /_matrix/client/r0/presence/{userId}/status


This API sets the given user's presence state. When setting the status, the activity time is updated to reflect that activity; the client does not need to specify the ``last_active_ago`` field. You cannot set the presence state of another user.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
userId string Required: The user whose presence state to update.

Request body

Name Type Description
presence enum Required: The new presence state.

One of: [online offline unavailable].

status_msg string The status message to attach to this state.

Request body example

{
  "presence": "online",
  "status_msg": "I am here."
}

Responses

Status Description
200 The new presence state was set.
429 This request was rate-limited.
Last active ago

The server maintains a timestamp of the last time it saw a pro-active event from the user. A pro-active event may be sending a message to a room or changing presence state to online. This timestamp is presented via a key called last_active_ago which gives the relative number of milliseconds since the pro-active event.

To reduce the number of presence updates sent to clients the server may include a currently_active boolean field when the presence state is online. When true, the server will not send further updates to the last active time until an update is sent to the client with either a) currently_active set to false or b) a presence state other than online. During this period clients must consider the user to be currently active, irrespective of the last active time.

The last active time must be up to date whenever the server gives a presence event to the client. The currently_active mechanism should purely be used by servers to stop sending continuous presence updates, as opposed to disabling last active tracking entirely. Thus clients can fetch up to date last active times by explicitly requesting the presence for a given user.

Idle timeout

The server will automatically set a user’s presence to unavailable if their last active time was over a threshold value (e.g. 5 minutes). Clients can manually set a user’s presence to unavailable. Any activity that bumps the last active time on any of the user’s clients will cause the server to automatically set their presence to online.

Security considerations

Presence information is shared with all users who share a room with the target user. In large public rooms this could be undesirable.

Content repository

The content repository (or “media repository”) allows users to upload files to their homeserver for later use. For example, files which the user wants to send to a room would be uploaded here, as would an avatar the user wants to use.

Uploads are POSTed to a resource on the user’s local homeserver which returns a MXC URI which can later be used to GET the download. Content is downloaded from the recipient’s local homeserver, which must first transfer the content from the origin homeserver using the same API (unless the origin and destination homeservers are the same).

When serving content, the server SHOULD provide a Content-Security-Policy header. The recommended policy is sandbox; default-src 'none'; script-src 'none'; plugin-types application/pdf; style-src 'unsafe-inline'; object-src 'self';.

Matrix Content (MXC) URIs

Content locations are represented as Matrix Content (MXC) URIs. They look like:

mxc://<server-name>/<media-id>

<server-name> : The name of the homeserver where this content originated, e.g. matrix.org <media-id> : An opaque ID which identifies the content.

Client behaviour

Clients can upload and download content using the following HTTP APIs.

GET /_matrix/media/r0/config


This endpoint allows clients to retrieve the configuration of the content repository, such as upload limitations. Clients SHOULD use this as a guide when using content repository endpoints. All values are intentionally left optional. Clients SHOULD follow the advice given in the field description when the field is not available.

NOTE: Both clients and server administrators should be aware that proxies between the client and the server may affect the apparent behaviour of content repository APIs, for example, proxies may enforce a lower upload size limit than is advertised by the server on this endpoint.

Rate-limited: Yes
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The public content repository configuration for the matrix server.
429 This request was rate-limited.

200 response body

Name Type Description
m.upload.size integer The maximum size an upload can be in bytes. Clients SHOULD use this as a guide when uploading content. If not listed or null, the size limit should be treated as unknown.

200 response body example

{
  "m.upload.size": 50000000
}

GET /_matrix/media/r0/download/{serverName}/{mediaId}


Rate-limited: Yes
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
mediaId string Required: The media ID from the mxc:// URI (the path component)
serverName string Required: The server name from the mxc:// URI (the authoritory component)
query parameters
Name Type Description
allow_remote boolean Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.

Responses

Status Description
200 The content that was previously uploaded.
429 This request was rate-limited.
502 The content is too large for the server to serve.

GET /_matrix/media/r0/download/{serverName}/{mediaId}/{fileName}


This will download content from the content repository (same as the previous endpoint) but replace the target file name with the one provided by the caller.

Rate-limited: Yes
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
fileName string Required: A filename to give in the Content-Disposition header.
mediaId string Required: The media ID from the mxc:// URI (the path component)
serverName string Required: The server name from the mxc:// URI (the authoritory component)
query parameters
Name Type Description
allow_remote boolean Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.

Responses

Status Description
200 The content that was previously uploaded.
429 This request was rate-limited.
502 The content is too large for the server to serve.

GET /_matrix/media/r0/preview_url


Get information about a URL for the client. Typically this is called when a client sees a URL in a message and wants to render a preview for the user.

.. Note:: Clients should consider avoiding this endpoint for URLs posted in encrypted rooms. Encrypted rooms often contain more sensitive information the users do not want to share with the homeserver, and this can mean that the URLs being shared should also not be shared with the homeserver.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
ts integer The preferred point in time to return a preview for. The server may return a newer version if it does not have the requested version available.
url string Required: The URL to get a preview of.

Responses

Status Description
200 The OpenGraph data for the URL, which may be empty. Some values are replaced with matrix equivalents if they are provided in the response. The differences from the OpenGraph protocol are described here.
429 This request was rate-limited.

200 response body

Name Type Description
matrix:image:size integer The byte-size of the image. Omitted if there is no image attached.
og:image string An MXC URI_ to the image. Omitted if there is no image.

200 response body example

{
  "matrix:image:size": 102400,
  "og:description": "This is a really cool blog post from matrix.org",
  "og:image": "mxc://example.com/ascERGshawAWawugaAcauga",
  "og:image:height": 48,
  "og:image:type": "image/png",
  "og:image:width": 48,
  "og:title": "Matrix Blog Post"
}

GET /_matrix/media/r0/thumbnail/{serverName}/{mediaId}


Download a thumbnail of content from the content repository. See the `thumbnailing <#thumbnails>`_ section for more information.

Rate-limited: Yes
Requires authentication: No

Request

Request parameters

path parameters
Name Type Description
mediaId string Required: The media ID from the mxc:// URI (the path component)
serverName string Required: The server name from the mxc:// URI (the authoritory component)
query parameters
Name Type Description
allow_remote boolean Indicates to the server that it should not attempt to fetch the media if it is deemed remote. This is to prevent routing loops where the server contacts itself. Defaults to true if not provided.
height integer Required: The desired height of the thumbnail. The actual thumbnail may be larger than the size specified.
method enum The desired resizing method. See the thumbnailing <#thumbnails>_ section for more information.

One of: [crop scale].

width integer Required: The desired width of the thumbnail. The actual thumbnail may be larger than the size specified.

Responses

Status Description
200 A thumbnail of the requested content.
400 The request does not make sense to the server, or the server cannot thumbnail the content. For example, the client requested non-integer dimensions or asked for negatively-sized images.
413 The local content is too large for the server to thumbnail.
429 This request was rate-limited.
502 The remote content is too large for the server to thumbnail.

POST /_matrix/media/r0/upload


Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

header parameters
Name Type Description
Content-Type string The content type of the file being uploaded
query parameters
Name Type Description
filename string The name of the file being uploaded

Request body

Request body example

"\u003cbytes\u003e"

Responses

Status Description
200 The MXC URI_ for the uploaded content.
403

The user does not have permission to upload the content. Some reasons for this error include:

  • The server does not permit the file type.
  • The user has reached a quota for uploaded content.
413 The uploaded content is too large for the server.
429 This request was rate-limited.

200 response body

Name Type Description
content_uri string Required: The MXC URI_ to the uploaded content.

200 response body example

{
  "content_uri": "mxc://example.com/AQwafuaFswefuhsfAFAgsw"
}
Thumbnails

The homeserver SHOULD be able to supply thumbnails for uploaded images and videos. The exact file types which can be thumbnailed are not currently specified - see Issue #1938 for more information.

The thumbnail methods are “crop” and “scale”. “scale” tries to return an image where either the width or the height is smaller than the requested size. The client should then scale and letterbox the image if it needs to fit within a given rectangle. “crop” tries to return an image where the width and height are close to the requested size and the aspect matches the requested size. The client should scale the image if it needs to fit within a given rectangle.

The dimensions given to the thumbnail API are the minimum size the client would prefer. Servers must never return thumbnails smaller than the client’s requested dimensions, unless the content being thumbnailed is smaller than the dimensions. When the content is smaller than the requested dimensions, servers should return the original content rather than thumbnail it.

Servers SHOULD produce thumbnails with the following dimensions and methods:

  • 32x32, crop
  • 96x96, crop
  • 320x240, scale
  • 640x480, scale
  • 800x600, scale

In summary:

  • “scale” maintains the original aspect ratio of the image
  • “crop” provides an image in the aspect ratio of the sizes given in the request
  • The server will return an image larger than or equal to the dimensions requested where possible.

Servers MUST NOT upscale thumbnails under any circumstance. Servers MUST NOT return a smaller thumbnail than requested, unless the original content makes that impossible.

Security considerations

The HTTP GET endpoint does not require any authentication. Knowing the URL of the content is sufficient to retrieve the content, even if the entity isn’t in the room.

MXC URIs are vulnerable to directory traversal attacks such as mxc://127.0.0.1/../../../some_service/etc/passwd. This would cause the target homeserver to try to access and return this file. As such, homeservers MUST sanitise MXC URIs by allowing only alphanumeric (A-Za-z0-9), _ and - characters in the server-name and media-id values. This set of whitelisted characters allows URL-safe base64 encodings specified in RFC 4648. Applying this character whitelist is preferable to blacklisting . and / as there are techniques around blacklisted characters (percent-encoded characters, UTF-8 encoded traversals, etc).

Homeservers have additional content-specific concerns:

  • Clients may try to upload very large files. Homeservers should not store files that are too large and should not serve them to clients, returning a HTTP 413 error with the M_TOO_LARGE code.
  • Clients may try to upload very large images. Homeservers should not attempt to generate thumbnails for images that are too large, returning a HTTP 413 error with the M_TOO_LARGE code.
  • Remote homeservers may host very large files or images. Homeservers should not proxy or thumbnail large files or images from remote homeservers, returning a HTTP 502 error with the M_TOO_LARGE code.
  • Clients may try to upload a large number of files. Homeservers should limit the number and total size of media that can be uploaded by clients, returning a HTTP 403 error with the M_FORBIDDEN code.
  • Clients may try to access a large number of remote files through a homeserver. Homeservers should restrict the number and size of remote files that it caches.
  • Clients or remote homeservers may try to upload malicious files targeting vulnerabilities in either the homeserver thumbnailing or the client decoders.

Send-to-Device messaging

This module provides a means by which clients can exchange signalling messages without them being stored permanently as part of a shared communication history. A message is delivered exactly once to each client device.

The primary motivation for this API is exchanging data that is meaningless or undesirable to persist in the room DAG - for example, one-time authentication tokens or key data. It is not intended for conversational data, which should be sent using the normal _ API for consistency throughout Matrix.

Client behaviour

To send a message to other devices, a client should call /sendToDevice_. Only one message can be sent to each device per transaction, and they must all have the same event type. The device ID in the request body can be set to * to request that the message be sent to all known devices.

If there are send-to-device messages waiting for a client, they will be returned by _, as detailed in Extensions to /sync_. Clients should inspect the type of each returned event, and ignore any they do not understand.

Server behaviour

Servers should store pending messages for local users until they are successfully delivered to the destination device. When a client calls _ with an access token which corresponds to a device with pending messages, the server should list the pending messages, in order of arrival, in the response body.

When the client calls /sync again with the next_batch token from the first response, the server should infer that any send-to-device messages in that response have been delivered successfully, and delete them from the store.

If there is a large queue of send-to-device messages, the server should limit the number sent in each /sync response. 100 messages is recommended as a reasonable limit.

If the client sends messages to users on remote domains, those messages should be sent on to the remote servers via federation.

Protocol definitions

PUT /_matrix/client/r0/sendToDevice/{eventType}/{txnId}


This endpoint is used to send send-to-device events to a set of client devices.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
eventType string Required: The type of event to send.
txnId string Required: The transaction ID for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests.

Request body

body
Name Type Description
messages object The messages to send. A map from user ID, to a map from device ID to message body. The device ID may also be *, meaning all known devices for the user.

Request body example

{
  "messages": {
    "@alice:example.com": {
      "TLLBEANAAG": {
        "example_content_key": "value"
      }
    }
  }
}

Responses

Status Description
200 The message was successfully sent.
Extensions to /sync

This module adds the following properties to the _ response:

Parameter Type Description

to_device

ToDevice

Optional. Information on the send-to-device messages for the client device.

ToDevice

Parameter Type Description
events [Event] List of send-to-device messages.

Event

Parameter Type Description

content

EventContent

The content of this event. The fields in this object will vary depending on the type of event.

sender

string

The Matrix user ID of the user who sent this event.

type string The type of event.

Example response:

{
  "next_batch": "s72595_4483_1934",
  "rooms": {"leave": {}, "join": {}, "invite": {}},
  "to_device": {
    "events": [
      {
        "sender": "@alice:example.com",
        "type": "m.new_device",
        "content": {
          "device_id": "XYZABCDE",
          "rooms": ["!726s6s6q:example.com"]
        }
      }
    ]
  }
}

Device Management

This module provides a means for a user to manage their devices.

Client behaviour

Clients that implement this module should offer the user a list of registered devices, as well as the means to update their display names. Clients should also allow users to delete disused devices.

POST /_matrix/client/r0/delete_devices


This API endpoint uses the `User-Interactive Authentication API`_.

Deletes the given devices, and invalidates any access token associated with them.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API.
devices [string] Required: The list of device IDs to delete.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  },
  "devices": [
    "QBUAZIFURK",
    "AUIECTSRND"
  ]
}

Responses

Status Description
200 The devices were successfully removed, or had been removed previously.
401 The homeserver requires additional authentication information.

GET /_matrix/client/r0/devices


Gets information about all devices for the current user.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 Device information

200 response body

Name Type Description
devices [object] A list of all registered devices for this user.
Device
Name Type Description
device_id string Required: Identifier of this device.
display_name string Display name set by the user for this device. Absent if no name has been set.
last_seen_ip string The IP address where this device was last seen. (May be a few minutes out of date, for efficiency reasons).
last_seen_ts integer The timestamp (in milliseconds since the unix epoch) when this devices was last seen. (May be a few minutes out of date, for efficiency reasons).

200 response body example

{
  "devices": [
    {
      "device_id": "QBUAZIFURK",
      "display_name": "android",
      "last_seen_ip": "1.2.3.4",
      "last_seen_ts": 1474491775024
    }
  ]
}

GET /_matrix/client/r0/devices/{deviceId}


Gets information on a single device, by device id.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
deviceId string Required: The device to retrieve.

Responses

Status Description
200 Device information
404 The current user has no device with the given ID.

200 response body

Device
Name Type Description
device_id string Required: Identifier of this device.
display_name string Display name set by the user for this device. Absent if no name has been set.
last_seen_ip string The IP address where this device was last seen. (May be a few minutes out of date, for efficiency reasons).
last_seen_ts integer The timestamp (in milliseconds since the unix epoch) when this devices was last seen. (May be a few minutes out of date, for efficiency reasons).

200 response body example

{
  "device_id": "QBUAZIFURK",
  "display_name": "android",
  "last_seen_ip": "1.2.3.4",
  "last_seen_ts": 1474491775024
}

PUT /_matrix/client/r0/devices/{deviceId}


Updates the metadata on the given device.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
deviceId string Required: The device to update.

Request body

Name Type Description
display_name string The new display name for this device. If not given, the display name is unchanged.

Request body example

{
  "display_name": "My other phone"
}

Responses

Status Description
200 The device was successfully updated.
404 The current user has no device with the given ID.

DELETE /_matrix/client/r0/devices/{deviceId}


This API endpoint uses the `User-Interactive Authentication API`_.

Deletes the given device, and invalidates any access token associated with it.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
deviceId string Required: The device to delete.

Request body

Name Type Description
auth Authentication Data Additional authentication information for the user-interactive authentication API.
Authentication Data
Name Type Description
session string The value of the session key given by the homeserver.
type string Required: The login type that the client is attempting to complete.

Request body example

{
  "auth": {
    "example_credential": "verypoorsharedsecret",
    "session": "xxxxx",
    "type": "example.type.foo"
  }
}

Responses

Status Description
200 The device was successfully removed, or had been removed previously.
401 The homeserver requires additional authentication information.

Security considerations

Deleting devices has security implications: it invalidates the access_token assigned to the device, so an attacker could use it to log out the real user (and do it repeatedly every time the real user tries to log in to block the attacker). Servers should require additional authentication beyond the access token when deleting devices (for example, requiring that the user resubmit their password).

The display names of devices are publicly visible. Clients should consider advising the user of this.

End-to-End Encryption

Matrix optionally supports end-to-end encryption, allowing rooms to be created whose conversation contents are not decryptable or interceptable on any of the participating homeservers.

Key Distribution

Encryption and Authentication in Matrix is based around public-key cryptography. The Matrix protocol provides a basic mechanism for exchange of public keys, though an out-of-band channel is required to exchange fingerprints between users to build a web of trust.

Overview
1) Bob publishes the public keys and supported algorithms for his
   device. This may include long-term identity keys, and/or one-time
   keys.
                                  +----------+  +--------------+
                                  | Bob's HS |  | Bob's Device |
                                  +----------+  +--------------+
                                        |              |
                                        |&lt;=============|
                                          /keys/upload
  1. Alice requests Bob’s public identity keys and supported algorithms.

+—————-+ +————+ +———-+ | Alice’s Device | | Alice’s HS | | Bob’s HS | +—————-+ +————+ +———-+ | | | |=================>|==============>| /keys/query <federation>

  1. Alice selects an algorithm and claims any one-time keys needed.

+—————-+ +————+ +———-+ | Alice’s Device | | Alice’s HS | | Bob’s HS | +—————-+ +————+ +———-+ | | | |=================>|==============>| /keys/claim <federation>

Key algorithms

The name ed25519 corresponds to the Ed25519 signature algorithm. The key is a 32-byte Ed25519 public key, encoded using unpadded Base64. Example:

"SogYyrkTldLz0BXP+GYWs0qaYacUI0RleEqNT8J3riQ"

The name curve25519 corresponds to the Curve25519 ECDH algorithm. The key is a 32-byte Curve25519 public key, encoded using unpadded Base64. Example:

"JGLn/yafz74HB2AbPLYJWIVGnKAtqECOBf11yyXac2Y"

The name signed_curve25519 also corresponds to the Curve25519 algorithm, but a key using this algorithm is represented by an object with a the following properties:

KeyObject

Parameter Type Description

key

string

Required. The unpadded Base64-encoded 32-byte Curve25519 public key.

signatures

Signatures

Required. Signatures of the key object.

The signature is calculated using the process described at Signing JSON.

Example:

{
  "key":"06UzBknVHFMwgi7AVloY7ylC+xhOhEX4PkNge14Grl8",
  "signatures": {
    "@user:example.com": {
      "ed25519:EGURVBUNJP": "YbJva03ihSj5mPk+CHMJKUKlCXCPFXjXOK6VqBnN9nA2evksQcTGn6hwQfrgRHIDDXO2le49x7jnWJHMJrJoBQ"
    }
  }
}
Device keys

Each device should have one Ed25519 signing key. This key should be generated on the device from a cryptographically secure source, and the private part of the key should never be exported from the device. This key is used as the fingerprint for a device by other clients.

A device will generally need to generate a number of additional keys. Details of these will vary depending on the messaging algorithm in use.

Algorithms generally require device identity keys as well as signing keys. Some algorithms also require one-time keys to improve their secrecy and deniability. These keys are used once during session establishment, and are then thrown away.

For Olm version 1, each device requires a single Curve25519 identity key, and a number of signed Curve25519 one-time keys.

Uploading keys

A device uploads the public parts of identity keys to their homeserver as a signed JSON object, using the /keys/upload_ API. The JSON object must include the public part of the device’s Ed25519 key, and must be signed by that key, as described in Signing JSON.

One-time keys are also uploaded to the homeserver using the /keys/upload_ API.

Devices must store the private part of each key they upload. They can discard the private part of a one-time key when they receive a message using that key. However it’s possible that a one-time key given out by a homeserver will never be used, so the device that generates the key will never know that it can discard the key. Therefore a device could end up trying to store too many private keys. A device that is trying to store too many private keys may discard keys starting with the oldest.

Tracking the device list for a user

Before Alice can send an encrypted message to Bob, she needs a list of each of his devices and the associated identity keys, so that she can establish an encryption session with each device. This list can be obtained by calling /keys/query_, passing Bob’s user ID in the device_keys parameter.

From time to time, Bob may add new devices, and Alice will need to know this so that she can include his new devices for later encrypted messages. A naive solution to this would be to call /keys/query_ before sending each message -however, the number of users and devices may be large and this would be inefficient.

It is therefore expected that each client will maintain a list of devices for a number of users (in practice, typically each user with whom we share an encrypted room). Furthermore, it is likely that this list will need to be persisted between invocations of the client application (to preserve device verification data and to alert Alice if Bob suddenly gets a new device).

Alice’s client can maintain a list of Bob’s devices via the following process:

  1. It first sets a flag to record that it is now tracking Bob’s device list, and a separate flag to indicate that its list of Bob’s devices is outdated. Both flags should be in storage which persists over client restarts.
  2. It then makes a request to /keys/query_, passing Bob’s user ID in the device_keys parameter. When the request completes, it stores the resulting list of devices in persistent storage, and clears the ‘outdated’ flag.
  3. During its normal processing of responses to _, Alice’s client inspects the changed property of the device_lists_ field. If it is tracking the device lists of any of the listed users, then it marks the device lists for those users outdated, and initiates another request to /keys/query_ for them.
  4. Periodically, Alice’s client stores the next_batch field of the result from _ in persistent storage. If Alice later restarts her client, it can obtain a list of the users who have updated their device list while it was offline by calling /keys/changes_, passing the recorded next_batch field as the from parameter. If the client is tracking the device list of any of the users listed in the response, it marks them as outdated. It combines this list with those already flagged as outdated, and initiates a /keys/query_ request for all of them.

Warning

Bob may update one of his devices while Alice has a request to /keys/query in flight. Alice’s client may therefore see Bob’s user ID in the device_lists field of the /sync response while the first request is in flight, and initiate a second request to /keys/query. This may lead to either of two related problems.

The first problem is that, when the first request completes, the client will clear the ‘outdated’ flag for Bob’s devices. If the second request fails, or the client is shut down before it completes, this could lead to Alice using an outdated list of Bob’s devices.

The second possibility is that, under certain conditions, the second request may complete before the first one. When the first request completes, the client could overwrite the later results from the second request with those from the first request.

Clients MUST guard against these situations. For example, a client could ensure that only one request to /keys/query is in flight at a time for each user, by queuing additional requests until the first completes. Alternatively, the client could make a new request immediately, but ensure that the first request’s results are ignored (possibly by cancelling the request).

Note

When Bob and Alice share a room, with Bob tracking Alice’s devices, she may leave the room and then add a new device. Bob will not be notified of this change, as he doesn’t share a room anymore with Alice. When they start sharing a room again, Bob has an out-of-date list of Alice’s devices. In order to address this issue, Bob’s homeserver will add Alice’s user ID to the changed property of the device_lists field, thus Bob will update his list of Alice’s devices as part of his normal processing. Note that Bob can also be notified when he stops sharing any room with Alice by inspecting the left property of the device_lists field, and as a result should remove her from its list of tracked users.

Sending encrypted attachments

When encryption is enabled in a room, files should be uploaded encrypted on the homeserver.

In order to achieve this, a client should generate a single-use 256-bit AES key, and encrypt the file using AES-CTR. The counter should be 64-bit long, starting at 0 and prefixed by a random 64-bit Initialization Vector (IV), which together form a 128-bit unique counter block.

Warning

An IV must never be used multiple times with the same key. This implies that if there are multiple files to encrypt in the same message, typically an image and its thumbnail, the files must not share both the same key and IV.

Then, the encrypted file can be uploaded to the homeserver. The key and the IV must be included in the room event along with the resulting mxc:// in order to allow recipients to decrypt the file. As the event containing those will be Megolm encrypted, the server will never have access to the decrypted file.

A hash of the ciphertext must also be included, in order to prevent the homeserver from changing the file content.

A client should send the data as an encrypted m.room.message event, using either m.file as the msgtype, or the appropriate msgtype for the file type. The key is sent using the JSON Web Key format, with a W3C extension.

Extensions to m.room.message msgtypes <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<

This module adds file and thumbnail_file properties, of type EncryptedFile, to m.room.message msgtypes that reference files, such as m.file and m.image, replacing the url and thumbnail_url properties.

EncryptedFile

Parameter Type Description
url string Required. The URL to the file.
key JWK Required. A JSON Web Key object.

iv

string

Required. The 128-bit unique counter block used by AES-CTR, encoded as unpadded base64.

hashes

{string: string}

Required. A map from an algorithm name to a hash of the ciphertext, encoded as unpadded base64. Clients should support the SHA-256 hash, which uses the key sha256.

v

string

Required. Version of the encrypted attachments protocol. Must be v2.

JWK

Parameter Type Description
kty string Required. Key type. Must be oct.

key_ops

[string]

Required. Key operations. Must at least contain encrypt and decrypt.

alg string Required. Algorithm. Must be A256CTR.
k string Required. The key, encoded as urlsafe unpadded base64.

ext

boolean

Required. Extractable. Must be true. This is a W3C extension.

Example:

Claiming one-time keys

A client wanting to set up a session with another device can claim a one-time key for that device. This is done by making a request to the /keys/claim_ API.

A homeserver should rate-limit the number of one-time keys that a given user or remote server can claim. A homeserver should discard the public part of a one time key once it has given that key to another user.

Device verification

Before Alice sends Bob encrypted data, or trusts data received from him, she may want to verify that she is actually communicating with him, rather than a man-in-the-middle. This verification process requires an out-of-band channel: there is no way to do it within Matrix without trusting the administrators of the homeservers.

In Matrix, verification works by Alice meeting Bob in person, or contacting him via some other trusted medium, and use [SAS Verification](#SAS Verification) to interactively verify Bob’s devices. Alice and Bob may also read aloud their unpadded base64 encoded Ed25519 public key, as returned by /keys/query.

Device verification may reach one of several conclusions. For example:

  • Alice may “accept” the device. This means that she is satisfied that the device belongs to Bob. She can then encrypt sensitive material for that device, and knows that messages received were sent from that device.
  • Alice may “reject” the device. She will do this if she knows or suspects that Bob does not control that device (or equivalently, does not trust Bob). She will not send sensitive material to that device, and cannot trust messages apparently received from it.
  • Alice may choose to skip the device verification process. She is not able to verify that the device actually belongs to Bob, but has no reason to suspect otherwise. The encryption protocol continues to protect against passive eavesdroppers.

Note

Once the signing key has been verified, it is then up to the encryption protocol to verify that a given message was sent from a device holding that Ed25519 private key, or to encrypt a message so that it may only be decrypted by such a device. For the Olm protocol, this is documented at https://matrix.org/docs/olm_signing.html.

Key verification framework

Verifying keys manually by reading out the Ed25519 key is not very user friendly, and can lead to errors. In order to help mitigate errors, and to make the process easier for users, some verification methods are supported by the specification. The methods all use a common framework for negotiating the key verification.

To use this framework, Alice’s client would send m.key.verification.request events to Bob’s devices. All of the to_device messages sent to Bob MUST have the same transaction_id to indicate they are part of the same request. This allows Bob to reject the request on one device, and have it apply to all of his devices. Similarly, it allows Bob to process the verification on one device without having to involve all of his devices.

When Bob’s device receives a m.key.verification.request, it should prompt Bob to verify keys with Alice using one of the supported methods in the request. If Bob’s device does not understand any of the methods, it should not cancel the request as one of his other devices may support the request. Instead, Bob’s device should tell Bob that an unsupported method was used for starting key verification. The prompt for Bob to accept/reject Alice’s request (or the unsupported method prompt) should be automatically dismissed 10 minutes after the timestamp field or 2 minutes after Bob’s client receives the message, whichever comes first, if Bob does not interact with the prompt. The prompt should additionally be hidden if an appropriate m.key.verification.cancel message is received.

If Bob rejects the request, Bob’s client must send a m.key.verification.cancel message to Alice’s device. Upon receipt, Alice’s device should tell her that Bob does not want to verify her device and send m.key.verification.cancel messages to all of Bob’s devices to notify them that the request was rejected.

If Bob accepts the request, Bob’s device starts the key verification process by sending a m.key.verification.start message to Alice’s device. Upon receipt of this message, Alice’s device should send a m.key.verification.cancel message to all of Bob’s other devices to indicate the process has been started. The start message must use the same transaction_id from the original key verification request if it is in response to the request. The start message can be sent indepdently of any request.

Individual verification methods may add additional steps, events, and properties to the verification messages. Event types for methods defined in this specification must be under the m.key.verification namespace and any other event types must be namespaced according to the Java package naming convention.

Any of Alice’s or Bob’s devices can cancel the key verification request or process at any time with a m.key.verification.cancel message to all applicable devices.

This framework yields the following handshake, assuming both Alice and Bob each have 2 devices, Bob’s first device accepts the key verification request, and Alice’s second device initiates the request. Note how Alice’s first device is not involved in the request or verification process.

+---------------+ +---------------+                    +-------------+ +-------------+
| AliceDevice1  | | AliceDevice2  |                    | BobDevice1  | | BobDevice2  |
+---------------+ +---------------+                    +-------------+ +-------------+
        |                 |                                   |               |
        |                 | m.key.verification.request        |               |
        |                 |---------------------------------->|               |
        |                 |                                   |               |
        |                 | m.key.verification.request        |               |
        |                 |-------------------------------------------------->|
        |                 |                                   |               |
        |                 |          m.key.verification.start |               |
        |                 |<----------------------------------|               |
        |                 |                                   |               |
        |                 | m.key.verification.cancel         |               |
        |                 |-------------------------------------------------->|
        |                 |                                   |               |

After the handshake, the verification process begins.

{{m_key_verification_request_event}}

{{m_key_verification_start_event}}

{{m_key_verification_cancel_event}}

Short Authentication String (SAS) verification

SAS verification is a user-friendly key verification process built off the common framework outlined above. SAS verification is intended to be a highly interactive process for users, and as such exposes verfiication methods which are easier for users to use.

The verification process is heavily inspired by Phil Zimmermann’s ZRTP key agreement handshake. A key part of key agreement in ZRTP is the hash commitment: the party that begins the Diffie-Hellman key sharing sends a hash of their part of the Diffie-Hellman exchange, and does not send their part of the Diffie-Hellman exchange until they have received the other party’s part. Thus an attacker essentially only has one attempt to attack the Diffie-Hellman exchange, and hence we can verify fewer bits while still achieving a high degree of security: if we verify n bits, then an attacker has a 1 in 2n chance of success. For example, if we verify 40 bits, then an attacker has a 1 in 1,099,511,627,776 chance (or less than 1 in 1012 chance) of success. A failed attack would result in a mismatched Short Authentication String, alerting users to the attack.

The verification process takes place over to-device messages in two phases:

  1. Key agreement phase (based on ZRTP key agreement).
  2. Key verification phase (based on HMAC).

The process between Alice and Bob verifying each other would be:

  1. Alice and Bob establish a secure out-of-band connection, such as meeting in-person or a video call. “Secure” here means that either party cannot be impersonated, not explicit secrecy.
  2. Alice and Bob communicate which devices they’d like to verify with each other.
  3. Alice selects Bob’s device from the device list and begins verification.
  4. Alice’s client ensures it has a copy of Bob’s device key.
  5. Alice’s device sends Bob’s device a m.key.verification.start message.
  6. Bob’s device receives the message and selects a key agreement protocol, hash algorithm, message authentication code, and SAS method supported by Alice’s device.
  7. Bob’s device ensures it has a copy of Alice’s device key.
  8. Bob’s device creates an ephemeral Curve25519 key pair (KBprivate, KBpubli**c), and calculates the hash (using the chosen algorithm) of the public key KBpubli**c.
  9. Bob’s device replies to Alice’s device with a m.key.verification.accept message.
  10. Alice’s device receives Bob’s message and stores the commitment hash for later use.
  11. Alice’s device creates an ephemeral Curve25519 key pair (KAprivate, KApubli**c) and replies to Bob’s device with a m.key.verification.key, sending only the public key KApubli**c.
  12. Bob’s device receives Alice’s message and replies with its own m.key.verification.key message containing its public key KBpubli**c.
  13. Alice’s device receives Bob’s message and verifies the commitment hash from earlier matches the hash of the key Bob’s device just sent and the content of Alice’s m.key.verification.start message.
  14. Both Alice and Bob’s devices perform an Elliptic-curve Diffie-Hellman (ECD**H(KAprivate, KBpubli**c)), using the result as the shared secret.
  15. Both Alice and Bob’s devices display a SAS to their users, which is derived from the shared key using one of the methods in this section. If multiple SAS methods are available, clients should allow the users to select a method.
  16. Alice and Bob compare the strings shown by their devices, and tell their devices if they match or not.
  17. Assuming they match, Alice and Bob’s devices calculate the HMAC of their own device keys and a comma-separated sorted list of of the key IDs that they wish the other user to verify, using SHA-256 as the hash function. HMAC is defined in RFC 2104. The key for the HMAC is different for each item and is calculated by generating 32 bytes (256 bits) using the key verification HKDF.
  18. Alice’s device sends Bob’s device a m.key.verification.mac message containing the MAC of Alice’s device keys and the MAC of her key IDs to be verified. Bob’s device does the same for Bob’s device keys and key IDs concurrently with Alice.
  19. When the other device receives the m.key.verification.mac message, the device calculates the HMAC of its copies of the other device’s keys given in the message, as well as the HMAC of the comma-separated, sorted, list of key IDs in the message. The device compares these with the HMAC values given in the message, and if everything matches then the device keys are verified.

The wire protocol looks like the following between Alice and Bob’s devices:

+-------------+                    +-----------+
| AliceDevice |                    | BobDevice |
+-------------+                    +-----------+
      |                                 |
      | m.key.verification.start        |
      |-------------------------------->|
      |                                 |
      |       m.key.verification.accept |
      |<--------------------------------|
      |                                 |
      | m.key.verification.key          |
      |-------------------------------->|
      |                                 |
      |          m.key.verification.key |
      |<--------------------------------|
      |                                 |
      | m.key.verification.mac          |
      |-------------------------------->|
      |                                 |
      |          m.key.verification.mac |
      |<--------------------------------|
      |                                 |
Error and exception handling

At any point the interactive verfication can go wrong. The following describes what to do when an error happens:

  • Alice or Bob can cancel the verification at any time. A m.key.verification.cancel message must be sent to signify the cancellation.
  • The verification can time out. Clients should time out a verification that does not complete within 10 minutes. Additionally, clients should expire a transaction_id which goes unused for 10 minutes after having last sent/received it. The client should inform the user that the verification timed out, and send an appropriate m.key.verification.cancel message to the other device.
  • When the same device attempts to intiate multiple verification attempts, the receipient should cancel all attempts with that device.
  • When a device receives an unknown transaction_id, it should send an appropriate m.key.verfication.cancel message to the other device indicating as such. This does not apply for inbound m.key.verification.start or m.key.verification.cancel messages.
  • If the two devices do not share a common key share, hash, HMAC, or SAS method then the device should notify the other device with an appropriate m.key.verification.cancel message.
  • If the user claims the Short Authentication Strings do not match, the device should send an appropriate m.key.verification.cancel message to the other device.
  • If the device receives a message out of sequence or that it was not expecting, it should notify the other device with an appropriate m.key.verification.cancel message.
Verification messages specific to SAS

Building off the common framework, the following events are involved in SAS verification.

The m.key.verification.cancel event is unchanged, however the following error codes are used in addition to those already specified:

  • m.unknown_method: The devices are unable to agree on the key agreement, hash, MAC, or SAS method.
  • m.mismatched_commitment: The hash commitment did not match.
  • m.mismatched_sas: The SAS did not match.

{{m_key_verification_start_m_sas_v1_event}}

{{m_key_verification_accept_event}}

{{m_key_verification_key_event}}

{{m_key_verification_mac_event}}

HKDF calculation

In all of the SAS methods, HKDF is as defined in RFC 5869 and uses the previously agreed-upon hash function for the hash function. The shared secret is supplied as the input keying material. No salt is used. When the key_agreement_protocol is curve25519-hkdf-sha256, the info parameter is the concatenation of:

  • The string MATRIX_KEY_VERIFICATION_SAS|.
  • The Matrix ID of the user who sent the m.key.verification.start message, followed by |.
  • The Device ID of the device which sent the m.key.verification.start message, followed by |.
  • The public key from the m.key.verification.key message sent by the device which sent the m.key.verification.start message, followed by |.
  • The Matrix ID of the user who sent the m.key.verification.accept message, followed by |.
  • The Device ID of the device which sent the m.key.verification.accept message, followed by |.
  • The public key from the m.key.verification.key message sent by the device which sent the m.key.verification.accept message, followed by |.
  • The transaction_id being used.

When the key_agreement_protocol is the deprecated method curve25519, the info parameter is the concatenation of:

  • The string MATRIX_KEY_VERIFICATION_SAS.
  • The Matrix ID of the user who sent the m.key.verification.start message.
  • The Device ID of the device which sent the m.key.verification.start message.
  • The Matrix ID of the user who sent the m.key.verification.accept message.
  • The Device ID of the device which sent the m.key.verification.accept message.
  • The transaction_id being used.

New implementations are discouraged from implementing the curve25519 method.

Rationale

HKDF is used over the plain shared secret as it results in a harder attack as well as more uniform data to work with.

For verification of each party’s device keys, HKDF is as defined in RFC 5869 and uses SHA-256 as the hash function. The shared secret is supplied as the input keying material. No salt is used, and in the info parameter is the concatenation of:

  • The string MATRIX_KEY_VERIFICATION_MAC.
  • The Matrix ID of the user whose key is being MAC-ed.
  • The Device ID of the device sending the MAC.
  • The Matrix ID of the other user.
  • The Device ID of the device receiving the MAC.
  • The transaction_id being used.
  • The Key ID of the key being MAC-ed, or the string KEY_IDS if the item being MAC-ed is the list of key IDs.
SAS method: decimal

Generate 5 bytes using HKDF then take sequences of 13 bits to convert to decimal numbers (resulting in 3 numbers between 0 and 8191 inclusive each). Add 1000 to each calculated number.

The bitwise operations to get the numbers given the 5 bytes B0, B1, B2, B3, B4 would be:

  • First: (B0 ≪ 5|B1 ≫ 3) + 1000
  • Second: ((B1&0x7) ≪ 10|B2 ≪ 2|B3 ≫ 6) + 1000
  • Third: ((B3&0x3F) ≪ 7|B4 ≫ 1) + 1000

The digits are displayed to the user either with an appropriate separator, such as dashes, or with the numbers on individual lines.

SAS method: emoji

Generate 6 bytes using HKDF then split the first 42 bits into 7 groups of 6 bits, similar to how one would base64 encode something. Convert each group of 6 bits to a number and use the following table to get the corresponding emoji:

{{sas_emoji_table}}

Note

This table is available as JSON at https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/sas-emoji.json

Rationale

The emoji above were chosen to:

  • Be recognisable without colour.
  • Be recognisable at a small size.
  • Be recognisable by most cultures.
  • Be distinguishable from each other.
  • Easily described by a few words.
  • Avoid symbols with negative connotations.
  • Be likely similar across multiple platforms.

Clients SHOULD show the emoji with the descriptions from the table, or appropriate translation of those descriptions. Client authors SHOULD collaborate to create a common set of translations for all languages.

Note

Known translations for the emoji are available from https://github.com/matrix-org/matrix-doc/blob/master/data-definitions/ and can be translated online: https://translate.riot.im/projects/matrix-doc/sas-emoji-v1

Sharing keys between devices

If Bob has an encrypted conversation with Alice on his computer, and then logs in through his phone for the first time, he may want to have access to the previously exchanged messages. To address this issue, several methods are provided to allow users to transfer keys from one device to another.

Key requests

When a device is missing keys to decrypt messages, it can request the keys by sending m.room_key_request to-device messages to other devices with action set to request.

If a device wishes to share the keys with that device, it can forward the keys to the first device by sending an encrypted m.forwarded_room_key to-device message. The first device should then send an m.room_key_request to-device message with action set to request_cancellation to the other devices that it had originally sent the key request to; a device that receives a request_cancellation should disregard any previously-received request message with the same request_id and requesting_device_id.

If a device does not wish to share keys with that device, it can indicate this by sending an m.room_key.withheld to-device message, as described in Reporting that decryption keys are withheld.

Note

Key sharing can be a big attack vector, thus it must be done very carefully. A reasonable strategy is for a user’s client to only send keys requested by the verified devices of the same user.

Server-side key backups

Devices may upload encrypted copies of keys to the server. When a device tries to read a message that it does not have keys for, it may request the key from the server and decrypt it. Backups are per-user, and users may replace backups with new backups.

In contrast with Key requests, Server-side key backups do not require another device to be online from which to request keys. However, as the session keys are stored on the server encrypted, it requires users to enter a decryption key to decrypt the session keys.

To create a backup, a client will call POST /_matrix/client/r0/room_keys/version and define how the keys are to be encrypted through the backup’s auth_data; other clients can discover the backup by calling GET /_matrix/client/r0/room_keys/version. Keys are encrypted according to the backup’s auth_data and added to the backup by calling PUT /_matrix/client/r0/room_keys/keys or one of its variants, and can be retrieved by calling GET /_matrix/client/r0/room_keys/keys or one of its variants. Keys can only be written to the most recently created version of the backup. Backups can also be deleted using DELETE /_matrix/client/r0/room_keys/version/{version}, or individual keys can be deleted using DELETE /_matrix/client/r0/room_keys/keys or one of its variants.

Clients must only store keys in backups after they have ensured that the auth_data is trusted, either by checking the signatures on it, or by deriving the public key from a private key that it obtained from a trusted source.

When a client uploads a key for a session that the server already has a key for, the server will choose to either keep the existing key or replace it with the new key based on the key metadata as follows:

  • if the keys have different values for is_verified, then it will keep the key that has is_verified set to true;
  • if they have the same values for is_verified, then it will keep the key with a lower first_message_index;
  • and finally, is is_verified and first_message_index are equal, then it will keep the key with a lower forwarded_count.
Recovery key

If the recovery key (the private half of the backup encryption key) is presented to the user to save, it is presented as a string constructed as follows:

  1. The 256-bit curve25519 private key is prepended by the bytes 0x8B and 0x01
  2. All the bytes in the string above, including the two header bytes, are XORed together to form a parity byte. This parity byte is appended to the byte string.
  3. The byte string is encoded using base58, using the same mapping as is used for Bitcoin addresses, that is, using the alphabet 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz.
  4. A space should be added after every 4th character.

When reading in a recovery key, clients must disregard whitespace, and perform the reverse of steps 1 through 3.

Backup algorithm: m.megolm_backup.v1.curve25519-aes-sha2

When a backup is created with the algorithm set to m.megolm_backup.v1.curve25519-aes-sha2, the auth_data should have the following format:

AuthData

Parameter Type Description

public_key

string

Required. The curve25519 public key used to encrypt the backups, encoded in unpadded base64.

signatures

Signatures

Optional. Signatures of the auth_data, as Signed JSON

The session_data field in the backups is constructed as follows:

  1. Encode the session key to be backed up as a JSON object with the properties:

    Parameter Type Description

    algorithm

    string

    Required. The end-to-end message encryption algorithm that the key is for. Must be m.megolm.v1.aes-sha2.

    forwarding_curve25519_key_chain

    [string]

    Required. Chain of Curve25519 keys through which this session was forwarded, via m.forwarded_room_key events.

    sender_key

    string

    Required. Unpadded base64-encoded device curve25519 key.

    sender_claimed_keys

    {string: string}

    Required. A map from algorithm name (ed25519) to the identity key for the sending device.

    session_key

    string

    Required. Unpadded base64-encoded session key in session-sharing format.

  2. Generate an ephemeral curve25519 key, and perform an ECDH with the ephemeral key and the backup’s public key to generate a shared secret. The public half of the ephemeral key, encoded using unpadded base64, becomes the ephemeral property of the session_data.

  3. Using the shared secret, generate 80 bytes by performing an HKDF using SHA-256 as the hash, with a salt of 32 bytes of 0, and with the empty string as the info. The first 32 bytes are used as the AES key, the next 32 bytes are used as the MAC key, and the last 16 bytes are used as the AES initialization vector.

  4. Stringify the JSON object, and encrypt it using AES-CBC-256 with PKCS#7 padding. This encrypted data, encoded using unpadded base64, becomes the ciphertext property of the session_data.

  5. Pass the raw encrypted data (prior to base64 encoding) through HMAC-SHA-256 using the MAC key generated above. The first 8 bytes of the resulting MAC are base64-encoded, and become the mac property of the session_data.

GET /_matrix/client/r0/room_keys/keys


Retrieve the keys from the backup for a given room

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
version string Required: The backup from which to retrieve the keys.

Responses

Status Description
200 The key data. If no keys are found, then an object with an empty rooms property will be returned ({"rooms": {}}).
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
rooms object A map of room IDs to room key backup data.

200 response body example

{
  "rooms": {
    "!room:example.org": {
      "sessions": {
        "sessionid1": {
          "first_message_index": 1,
          "forwarded_count": 0,
          "is_verified": true,
          "session_data": {
            "ciphertext": "base64+ciphertext+of+JSON+data",
            "ephemeral": "base64+ephemeral+key",
            "mac": "base64+mac+of+ciphertext"
          }
        }
      }
    }
  }
}

PUT /_matrix/client/r0/room_keys/keys


Store several keys in the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
version string Required: The backup in which to store the keys. Must be the current backup.

Request body

Name Type Description
rooms object Required: A map of room IDs to room key backup data.

Request body example

{
  "rooms": {
    "!room:example.org": {
      "sessions": {
        "sessionid1": {
          "first_message_index": 1,
          "forwarded_count": 0,
          "is_verified": true,
          "session_data": {
            "ciphertext": "base64+ciphertext+of+JSON+data",
            "ephemeral": "base64+ephemeral+key",
            "mac": "base64+mac+of+ciphertext"
          }
        }
      }
    }
  }
}

Responses

Status Description
200 The update succeeded
403 The version specified does not match the current backup version. The current version will be included in the current_version field.
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

DELETE /_matrix/client/r0/room_keys/keys


Delete a key from the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
version string Required: The backup from which to delete the key

Responses

Status Description
200 The update succeeded
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

GET /_matrix/client/r0/room_keys/keys/{roomId}


Retrieve the keys from the backup for a given room

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the requested key is for.
query parameters
Name Type Description
version string Required: The backup from which to retrieve the key.

Responses

Status Description
200 The key data. If no keys are found, then an object with an empty sessions property will be returned ({"sessions": {}}).
404 The backup was not found.
429 This request was rate-limited.

200 response body

RoomKeyBackup
Name Type Description
sessions object Required: A map of session IDs to key data.

200 response body example

{
  "sessions": {
    "sessionid1": {
      "first_message_index": 1,
      "forwarded_count": 0,
      "is_verified": true,
      "session_data": {
        "ciphertext": "base64+ciphertext+of+JSON+data",
        "ephemeral": "base64+ephemeral+key",
        "mac": "base64+mac+of+ciphertext"
      }
    }
  }
}

PUT /_matrix/client/r0/room_keys/keys/{roomId}


Store a key in the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the keys are for.
query parameters
Name Type Description
version string Required: The backup in which to store the keys. Must be the current backup.

Request body

RoomKeyBackup
Name Type Description
sessions object Required: A map of session IDs to key data.

Request body example

{
  "sessions": {
    "sessionid1": {
      "first_message_index": 1,
      "forwarded_count": 0,
      "is_verified": true,
      "session_data": {
        "ciphertext": "base64+ciphertext+of+JSON+data",
        "ephemeral": "base64+ephemeral+key",
        "mac": "base64+mac+of+ciphertext"
      }
    }
  }
}

Responses

Status Description
200 The update succeeded
403 The version specified does not match the current backup version. The current version will be included in the current_version field.
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

DELETE /_matrix/client/r0/room_keys/keys/{roomId}


Delete a key from the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the specified key is for.
query parameters
Name Type Description
version string Required: The backup from which to delete the key.

Responses

Status Description
200 The update succeeded
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

GET /_matrix/client/r0/room_keys/keys/{roomId}/{sessionId}


Retrieve a key from the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the requested key is for.
sessionId string Required: The ID of the megolm session whose key is requested.
query parameters
Name Type Description
version string Required: The backup from which to retrieve the key.

Responses

Status Description
200 The key data
404 The key or backup was not found.
429 This request was rate-limited.

200 response body

KeyBackupData
Name Type Description
first_message_index integer Required: The index of the first message in the session that the key can decrypt.
forwarded_count integer Required: The number of times this key has been forwarded via key-sharing between devices.
is_verified boolean Required: Whether the device backing up the key verified the device that the key is from.
session_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.

200 response body example

{
  "first_message_index": 1,
  "session_data": {
    "ciphertext": "base64+ciphertext+of+JSON+data",
    "ephemeral": "base64+ephemeral+key",
    "mac": "base64+mac+of+ciphertext"
  }
}

PUT /_matrix/client/r0/room_keys/keys/{roomId}/{sessionId}


Store a key in the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the key is for.
sessionId string Required: The ID of the megolm session that the key is for.
query parameters
Name Type Description
version string Required: The backup in which to store the key. Must be the current backup.

Request body

KeyBackupData
Name Type Description
first_message_index integer Required: The index of the first message in the session that the key can decrypt.
forwarded_count integer Required: The number of times this key has been forwarded via key-sharing between devices.
is_verified boolean Required: Whether the device backing up the key verified the device that the key is from.
session_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.

Request body example

{
  "first_message_index": 1,
  "session_data": {
    "ciphertext": "base64+ciphertext+of+JSON+data",
    "ephemeral": "base64+ephemeral+key",
    "mac": "base64+mac+of+ciphertext"
  }
}

Responses

Status Description
200 The update succeeded.
403 The version specified does not match the current backup version. The current version will be included in the current_version field.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

DELETE /_matrix/client/r0/room_keys/keys/{roomId}/{sessionId}


Delete a key from the backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The ID of the room that the specified key is for.
sessionId string Required: The ID of the megolm session whose key is to be deleted.
query parameters
Name Type Description
version string Required: The backup from which to delete the key

Responses

Status Description
200 The update succeeded
404 The backup was not found.
429 This request was rate-limited.

200 response body

Name Type Description
count integer Required: The number of keys stored in the backup
etag string Required: The new etag value representing stored keys in the backup. See GET /room_keys/version/{version} for more details.

200 response body example

{
  "count": 10,
  "etag": "abcdefg"
}

GET /_matrix/client/r0/room_keys/version


Get information about the latest backup version.

Rate-limited: Yes
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The information about the backup.
404 No backup exists.
429 This request was rate-limited.

200 response body

Name Type Description
algorithm enum Required: The algorithm used for storing backups.

One of: [m.megolm_backup.v1.curve25519-aes-sha2].

auth_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.
count integer Required: The number of keys stored in the backup.
etag string Required: An opaque string representing stored keys in the backup. Clients can compare it with the etag value they received in the request of their last key storage request. If not equal, another client has modified the backup.
version string Required: The backup version.

200 response body example

{
  "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
  "auth_data": {
    "public_key": "abcdefg",
    "signatures": {
      "@alice:example.org": {
        "ed25519:deviceid": "signature"
      }
    }
  },
  "count": 42,
  "etag": "anopaquestring",
  "version": "1"
}

POST /_matrix/client/r0/room_keys/version


Creates a new backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
algorithm enum Required: The algorithm used for storing backups.

One of: [m.megolm_backup.v1.curve25519-aes-sha2].

auth_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.

Request body example

{
  "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
  "auth_data": {
    "public_key": "abcdefg",
    "signatures": {
      "@alice:example.org": {
        "ed25519:deviceid": "signature"
      }
    }
  }
}

Responses

Status Description
200 The version id of the new backup.
429 This request was rate-limited.

200 response body

Name Type Description
version string Required: The backup version. This is an opaque string.

200 response body example

{
  "version": "1"
}

GET /_matrix/client/r0/room_keys/version/{version}


Get information about an existing backup.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
version string Required: The backup version to get, as returned in the version parameter of the response in POST /_matrix/client/r0/room_keys/version_ or this endpoint.

Responses

Status Description
200 The information about the requested backup.
404 The backup specified does not exist.
429 This request was rate-limited.

200 response body

Name Type Description
algorithm enum Required: The algorithm used for storing backups.

One of: [m.megolm_backup.v1.curve25519-aes-sha2].

auth_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.
count integer Required: The number of keys stored in the backup.
etag string Required: An opaque string representing stored keys in the backup. Clients can compare it with the etag value they received in the request of their last key storage request. If not equal, another client has modified the backup.
version string Required: The backup version.

200 response body example

{
  "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
  "auth_data": {
    "public_key": "abcdefg",
    "signatures": {
      "@alice:example.org": {
        "ed25519:deviceid": "signature"
      }
    }
  },
  "count": 42,
  "etag": "anopaquestring",
  "version": "1"
}

PUT /_matrix/client/r0/room_keys/version/{version}


Update information about an existing backup. Only ``auth_data`` can be modified.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
version string Required: The backup version to update, as returned in the version parameter in the response of POST /_matrix/client/r0/room_keys/version_ or GET /_matrix/client/r0/room_keys/version/{version}_.

Request body

Name Type Description
algorithm enum Required: The algorithm used for storing backups. Must be the same as the algorithm currently used by the backup.

One of: [m.megolm_backup.v1.curve25519-aes-sha2].

auth_data object Required: Algorithm-dependent data. See the documentation for the backup algorithms in Server-side key backups_ for more information on the expected format of the data.
version string The backup version. If present, must be the same as the version in the path parameter.

Request body example

{
  "algorithm": "m.megolm_backup.v1.curve25519-aes-sha2",
  "auth_data": {
    "public_key": "abcdefg",
    "signatures": {
      "@alice:example.org": {
        "ed25519:deviceid": "signature"
      }
    }
  },
  "version": "1"
}

Responses

Status Description
200 The update succeeded.
400 A parameter was incorrect. For example, the algorithm does not match the current backup algorithm, or the version in the body does not match the version in the path.
404 The backup specified does not exist.
429 This request was rate-limited.

DELETE /_matrix/client/r0/room_keys/version/{version}


Delete an existing key backup. Both the information about the backup, as well as all key data related to the backup will be deleted.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
version string Required: The backup version to delete, as returned in the version parameter in the response of POST /_matrix/client/r0/room_keys/version_ or GET /_matrix/client/r0/room_keys/version/{version}_.

Responses

Status Description
200 The delete succeeded, or the specified backup was previously deleted.
404 The backup specified does not exist. If the backup was previously deleted, the call should succeed rather than returning an error.
429 This request was rate-limited.
Key exports

Keys can be manually exported from one device to an encrypted file, copied to another device, and imported. The file is encrypted using a user-supplied passphrase, and is created as follows:

  1. Encode the sessions as a JSON object, formatted as described in Key export format.

  2. Generate a 512-bit key from the user-entered passphrase by computing PBKDF2(HMAC-SHA-512, passphrase, S, N, 512), where S is a 128-bit cryptographically-random salt and N is the number of rounds. N should be at least 100,000. The keys K and K' are set to the first and last 256 bits of this generated key, respectively. K is used as an AES-256 key, and K' is used as an HMAC-SHA-256 key.

  3. Serialize the JSON object as a UTF-8 string, and encrypt it using AES-CTR-256 with the key K generated above, and with a 128-bit cryptographically-random initialization vector, IV, that has bit 63 set to zero. (Setting bit 63 to zero in IV is needed to work around differences in implementations of AES-CTR.)

  4. Concatenate the following data:

    Size (bytes) Description
    1 Export format version, which must be 0x01.
    16 The salt S.
    16 The initialization vector IV.
    4 The number of rounds N, as a big-endian unsigned 32-bit integer.
    variable The encrypted JSON object.

    32

    The HMAC-SHA-256 of all the above string concatenated together, using K' as the key.

  5. Base64-encode the string above. Newlines may be added to avoid overly long lines.

  6. Prepend the resulting string with -----BEGIN MEGOLM SESSION DATA-----, with a trailing newline, and append -----END MEGOLM SESSION DATA-----, with a leading and trailing newline.

Key export format

The exported sessions are formatted as a JSON array of SessionData objects described as follows:

SessionData

Parameter Type Description

algorithm

string

Required. The encryption algorithm that the session uses. Must be m.megolm.v1.aes-sha2.

forwarding_curve25519_key_chain

[string]

Required. Chain of Curve25519 keys through which this session was forwarded, via m.forwarded_room_key events.

room_id

string

Required. The room where the session is used.

sender_key

string

Required. The Curve25519 key of the device which initiated the session originally.

sender_claimed_keys

{string: string}

Required. The Ed25519 key of the device which initiated the session originally.

session_id string Required. The ID of the session.
session_key string Required. The key for the session.

This is similar to the format before encryption used for the session keys in Server-side key backups but adds the room_id and session_id fields.

Example:

[
    {
        "algorithm": "m.megolm.v1.aes-sha2",
        "forwarding_curve25519_key_chain": [
            "hPQNcabIABgGnx3/ACv/jmMmiQHoeFfuLB17tzWp6Hw"
        ],
        "room_id": "!Cuyf34gef24t:localhost",
        "sender_key": "RF3s+E7RkTQTGF2d8Deol0FkQvgII2aJDf3/Jp5mxVU",
        "sender_claimed_keys": {
            "ed25519": "<device ed25519 identity key>",
        },
        "session_id": "X3lUlvLELLYxeTx4yOVu6UDpasGEVO0Jbu+QFnm0cKQ",
        "session_key": "AgAAAADxKHa9uFxcXzwYoNueL5Xqi69IkD4sni8Llf..."
    },
    ...
]

Messaging Algorithms

Messaging Algorithm Names

Messaging algorithm names use the extensible naming scheme used throughout this specification. Algorithm names that start with m. are reserved for algorithms defined by this specification. Implementations wanting to experiment with new algorithms must be uniquely globally namespaced following Java’s package naming conventions.

Algorithm names should be short and meaningful, and should list the primitives used by the algorithm so that it is easier to see if the algorithm is using a broken primitive.

A name of m.olm.v1 is too short: it gives no information about the primitives in use, and is difficult to extend for different primitives. However a name of m.olm.v1.ecdh-curve25519-hdkfsha256.hmacsha256.hkdfsha256-aes256-cbc-hmac64sha256 is too long despite giving a more precise description of the algorithm: it adds to the data transfer overhead and sacrifices clarity for human readers without adding any useful extra information.

m.olm.v1.curve25519-aes-sha2

The name m.olm.v1.curve25519-aes-sha2 corresponds to version 1 of the Olm ratchet, as defined by the Olm specification. This uses:

  • Curve25519 for the initial key agreement.
  • HKDF-SHA-256 for ratchet key derivation.
  • Curve25519 for the root key ratchet.
  • HMAC-SHA-256 for the chain key ratchet.
  • HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption.

Devices that support Olm must include “m.olm.v1.curve25519-aes-sha2” in their list of supported messaging algorithms, must list a Curve25519 device key, and must publish Curve25519 one-time keys.

An event encrypted using Olm has the following format:

{
  "type": "m.room.encrypted",
  "content": {
    "algorithm": "m.olm.v1.curve25519-aes-sha2",
    "sender_key": "<sender_curve25519_key>",
    "ciphertext": {
      "<device_curve25519_key>": {
        "type": 0,
        "body": "<encrypted_payload_base_64>"
      }
    }
  }
}

ciphertext is a mapping from device Curve25519 key to an encrypted payload for that device. body is a Base64-encoded Olm message body. type is an integer indicating the type of the message body: 0 for the initial pre-key message, 1 for ordinary messages.

Olm sessions will generate messages with a type of 0 until they receive a message. Once a session has decrypted a message it will produce messages with a type of 1.

When a client receives a message with a type of 0 it must first check if it already has a matching session. If it does then it will use that session to try to decrypt the message. If there is no existing session then the client must create a new session and use the new session to decrypt the message. A client must not persist a session or remove one-time keys used by a session until it has successfully decrypted a message using that session.

Messages with type 1 can only be decrypted with an existing session. If there is no matching session, the client must treat this as an invalid message.

The plaintext payload is of the form:

{
  "type": "<type of the plaintext event>",
  "content": "<content for the plaintext event>",
  "sender": "<sender_user_id>",
  "recipient": "<recipient_user_id>",
  "recipient_keys": {
    "ed25519": "<our_ed25519_key>"
  },
  "keys": {
    "ed25519": "<sender_ed25519_key>"
  }
}

The type and content of the plaintext message event are given in the payload.

Other properties are included in order to prevent an attacker from publishing someone else’s curve25519 keys as their own and subsequently claiming to have sent messages which they didn’t. sender must correspond to the user who sent the event, recipient to the local user, and recipient_keys to the local ed25519 key.

Clients must confirm that the sender_key and the ed25519 field value under the keys property match the keys returned by /keys/query_ for the given user, and must also verify the signature of the payload. Without this check, a client cannot be sure that the sender device owns the private part of the ed25519 key it claims to have in the Olm payload. This is crucial when the ed25519 key corresponds to a verified device.

If a client has multiple sessions established with another device, it should use the session from which it last received and successfully decrypted a message. For these purposes, a session that has not received any messages should use its creation time as the time that it last received a message. A client may expire old sessions by defining a maximum number of olm sessions that it will maintain for each device, and expiring sessions on a Least Recently Used basis. The maximum number of olm sessions maintained per device should be at least 4.

Recovering from undecryptable messages

Occasionally messages may be undecryptable by clients due to a variety of reasons. When this happens to an Olm-encrypted message, the client should assume that the Olm session has become corrupted and create a new one to replace it.

Note

Megolm-encrypted messages generally do not have the same problem. Usually the key for an undecryptable Megolm-encrypted message will come later, allowing the client to decrypt it successfully. Olm does not have a way to recover from the failure, making this session replacement process required.

To establish a new session, the client sends a m.dummy to-device event to the other party to notify them of the new session details.

Clients should rate-limit the number of sessions it creates per device that it receives a message from. Clients should not create a new session with another device if it has already created one for that given device in the past 1 hour.

Clients should attempt to mitigate loss of the undecryptable messages. For example, Megolm sessions that were sent using the old session would have been lost. The client can attempt to retrieve the lost sessions through m.room_key_request messages.

m.megolm.v1.aes-sha2

The name m.megolm.v1.aes-sha2 corresponds to version 1 of the Megolm ratchet, as defined by the Megolm specification. This uses:

  • HMAC-SHA-256 for the hash ratchet.
  • HKDF-SHA-256, AES-256 in CBC mode, and 8 byte truncated HMAC-SHA-256 for authenticated encryption.
  • Ed25519 for message authenticity.

Devices that support Megolm must support Olm, and include “m.megolm.v1.aes-sha2” in their list of supported messaging algorithms.

An event encrypted using Megolm has the following format:

{
  "type": "m.room.encrypted",
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "sender_key": "<sender_curve25519_key>",
    "device_id": "<sender_device_id>",
    "session_id": "<outbound_group_session_id>",
    "ciphertext": "<encrypted_payload_base_64>"
  }
}

The encrypted payload can contain any message event. The plaintext is of the form:

{
  "type": "<event_type>",
  "content": "<event_content>",
  "room_id": "<the room_id>"
}

We include the room ID in the payload, because otherwise the homeserver would be able to change the room a message was sent in.

Clients must guard against replay attacks by keeping track of the ratchet indices of Megolm sessions. They should reject messages with a ratchet index that they have already decrypted. Care should be taken in order to avoid false positives, as a client may decrypt the same event twice as part of its normal processing.

As with Olm events, clients must confirm that the sender_key belongs to the user who sent the message. The same reasoning applies, but the sender ed25519 key has to be inferred from the keys.ed25519 property of the event which established the Megolm session.

In order to enable end-to-end encryption in a room, clients can send a m.room.encryption state event specifying m.megolm.v1.aes-sha2 as its algorithm property.

When creating a Megolm session in a room, clients must share the corresponding session key using Olm with the intended recipients, so that they can decrypt future messages encrypted using this session. A m.room_key event is used to do this. Clients must also handle m.room_key events sent by other devices in order to decrypt their messages.

Protocol definitions

Events

{{m_room_encryption_event}}

{{m_room_encrypted_event}}

{{m_room_key_event}}

{{m_room_key_request_event}}

{{m_forwarded_room_key_event}}

{{m_dummy_event}}

Key management API

GET /_matrix/client/r0/keys/changes


Gets a list of users who have updated their device identity keys since a previous sync token.

The server should include in the results any users who:

  • currently share a room with the calling user (ie, both users have membership state join); and
  • added new device identity keys or removed an existing device with identity keys, between from and to.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
from string Required: The desired start point of the list. Should be the next_batch field from a response to an earlier call to |/sync|. Users who have not uploaded new device identity keys since this point, nor deleted existing devices with identity keys since then, will be excluded from the results.
to string Required: The desired end point of the list. Should be the next_batch field from a recent call to |/sync| - typically the most recent such call. This may be used by the server as a hint to check its caches are up to date.

Responses

Status Description
200 The list of users who updated their devices.

200 response body

Name Type Description
changed [string] The Matrix User IDs of all users who updated their device identity keys.
left [string] The Matrix User IDs of all users who may have left all the end-to-end encrypted rooms they previously shared with the user.

200 response body example

{
  "changed": [
    "@alice:example.com",
    "@bob:example.org"
  ],
  "left": [
    "@clara:example.com",
    "@doug:example.org"
  ]
}

POST /_matrix/client/r0/keys/claim


Claims one-time keys for use in pre-key messages.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
one_time_keys object Required: The keys to be claimed. A map from user ID, to a map from device ID to algorithm name.
timeout integer The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default.

Request body example

{
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": "signed_curve25519"
    }
  },
  "timeout": 10000
}

Responses

Status Description
200 The claimed keys.

200 response body

Name Type Description
failures object

If any remote homeservers could not be reached, they are recorded here. The names of the properties are the names of the unreachable servers.

If the homeserver could be reached, but the user or device was unknown, no failure is recorded. Instead, the corresponding user or device is missing from the one_time_keys result.

one_time_keys object Required:

One-time keys for the queried devices. A map from user ID, to a map from devices to a map from <algorithm>:<key_id> to the key object.

See the key algorithms <#key-algorithms>_ section for information on the Key Object format.

200 response body example

{
  "one_time_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "signed_curve25519:AAAAHg": {
          "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
          "signatures": {
            "@alice:example.com": {
              "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
            }
          }
        }
      }
    }
  }
}

POST /_matrix/client/r0/keys/query


Returns the current devices and identity keys for the given users.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
device_keys object Required: The keys to be downloaded. A map from user ID, to a list of device IDs, or to an empty list to indicate all devices for the corresponding user.
timeout integer The time (in milliseconds) to wait when downloading keys from remote servers. 10 seconds is the recommended default.
token string If the client is fetching keys as a result of a device update received in a sync request, this should be the ‘since’ token of that sync request, or any later sync token. This allows the server to ensure its response contains the keys advertised by the notification in that sync.

Request body example

{
  "device_keys": {
    "@alice:example.com": []
  },
  "timeout": 10000
}

Responses

Status Description
200 The device information

200 response body

Name Type Description
device_keys object Information on the queried devices. A map from user ID, to a map from device ID to device information. For each device, the information returned will be the same as uploaded via /keys/upload, with the addition of an unsigned property.
failures object

If any remote homeservers could not be reached, they are recorded here. The names of the properties are the names of the unreachable servers.

If the homeserver could be reached, but the user or device was unknown, no failure is recorded. Instead, the corresponding user or device is missing from the device_keys result.

200 response body example

{
  "device_keys": {
    "@alice:example.com": {
      "JLAFKJWSCS": {
        "algorithms": [
          "m.olm.v1.curve25519-aes-sha2",
          "m.megolm.v1.aes-sha2"
        ],
        "device_id": "JLAFKJWSCS",
        "keys": {
          "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
          "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
        },
        "signatures": {
          "@alice:example.com": {
            "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
          }
        },
        "unsigned": {
          "device_display_name": "Alice's mobile phone"
        },
        "user_id": "@alice:example.com"
      }
    }
  }
}

POST /_matrix/client/r0/keys/upload


Publishes end-to-end encryption keys for the device.

Rate-limited: No
Requires authentication: Yes

Request

Request body

Name Type Description
device_keys DeviceKeys Identity keys for the device. May be absent if no new identity keys are required.
one_time_keys object

One-time public keys for “pre-key” messages. The names of the properties should be in the format <algorithm>:<key_id>. The format of the key is determined by the key algorithm <#key-algorithms>_.

May be absent if no new one-time keys are required.

DeviceKeys
Name Type Description
algorithms [string] Required: The encryption algorithms supported by this device.
device_id string Required: The ID of the device these keys belong to. Must match the device ID used when logging in.
keys object Required: Public identity keys. The names of the properties should be in the format <algorithm>:<device_id>. The keys themselves should be encoded as specified by the key algorithm.
signatures Signatures Required:

Signatures for the device key object. A map from user ID, to a map from <algorithm>:<device_id> to the signature.

The signature is calculated using the process described at Signing JSON_.

user_id string Required: The ID of the user the device belongs to. Must match the user ID used when logging in.

Request body example

{
  "device_keys": {
    "algorithms": [
      "m.olm.v1.curve25519-aes-sha2",
      "m.megolm.v1.aes-sha2"
    ],
    "device_id": "JLAFKJWSCS",
    "keys": {
      "curve25519:JLAFKJWSCS": "3C5BFWi2Y8MaVvjM8M22DBmh24PmgR0nPvJOIArzgyI",
      "ed25519:JLAFKJWSCS": "lEuiRJBit0IG6nUf5pUzWTUEsRVVe/HJkoKuEww9ULI"
    },
    "signatures": {
      "@alice:example.com": {
        "ed25519:JLAFKJWSCS": "dSO80A01XiigH3uBiDVx/EjzaoycHcjq9lfQX0uWsqxl2giMIiSPR8a4d291W1ihKJL/a+myXS367WT6NAIcBA"
      }
    },
    "user_id": "@alice:example.com"
  },
  "one_time_keys": {
    "curve25519:AAAAAQ": "/qyvZvwjiTxGdGU0RCguDCLeR+nmsb3FfNG3/Ve4vU8",
    "signed_curve25519:AAAAHQ": {
      "key": "j3fR3HemM16M7CWhoI4Sk5ZsdmdfQHsKL1xuSft6MSw",
      "signatures": {
        "@alice:example.com": {
          "ed25519:JLAFKJWSCS": "IQeCEPb9HFk217cU9kw9EOiusC6kMIkoIRnbnfOh5Oc63S1ghgyjShBGpu34blQomoalCyXWyhaaT3MrLZYQAA"
        }
      }
    },
    "signed_curve25519:AAAAHg": {
      "key": "zKbLg+NrIjpnagy+pIY6uPL4ZwEG2v+8F9lmgsnlZzs",
      "signatures": {
        "@alice:example.com": {
          "ed25519:JLAFKJWSCS": "FLWxXqGbwrb8SM3Y795eB6OA8bwBcoMZFXBqnTn58AYWZSqiD45tlBVcDa2L7RwdKXebW/VzDlnfVJ+9jok1Bw"
        }
      }
    }
  }
}

Responses

Status Description
200 The provided keys were successfully uploaded.

200 response body

Name Type Description
one_time_key_counts object Required: For each key algorithm, the number of unclaimed one-time keys of that type currently held on the server for this device.

200 response body example

{
  "one_time_key_counts": {
    "curve25519": 10,
    "signed_curve25519": 20
  }
}
Extensions to /sync

This module adds an optional device_lists property to the _ response, as specified below. The server need only populate this property for an incremental /sync (ie, one where the since parameter was specified). The client is expected to use /keys/query_ or /keys/changes_ for the equivalent functionality after an initial sync, as documented in Tracking the device list for a user.

It also adds a one_time_keys_count property. Note the spelling difference with the one_time_key_counts property in the /keys/upload_ response.

Parameter Type Description

device_lists

DeviceLists

Optional. Information on e2e device updates. Note: only present on an incremental sync.

device_one_time_keys_count

{string: integer}

Optional. For each key algorithm, the number of unclaimed one-time keys currently held on the server for this device.

DeviceLists

Parameter Type Description

changed

[string]

List of users who have updated their device identity keys, or who now share an encrypted room with the client since the previous sync response.

left

[string]

List of users with whom we do not share any encrypted rooms anymore since the previous sync response.

Note

For optimal performance, Alice should be added to changed in Bob’s sync only when she adds a new device, or when Alice and Bob now share a room but didn’t share any room previously. However, for the sake of simpler logic, a server may add Alice to changed when Alice and Bob share a new room, even if they previously already shared a room.

Example response:

{
  "next_batch": "s72595_4483_1934",
  "rooms": {"leave": {}, "join": {}, "invite": {}},
  "device_lists": {
    "changed": [
       "@alice:example.com",
    ],
    "left": [
       "@bob:example.com",
    ],
  },
  "device_one_time_keys_count": {
    "curve25519": 10,
    "signed_curve25519": 20
  }
}

Reporting that decryption keys are withheld

When sending an encrypted event to a room, a client can optionally signal to other devices in that room that it is not sending them the keys needed to decrypt the event. In this way, the receiving client can indicate to the user why it cannot decrypt the event, rather than just showing a generic error message.

In the same way, when one device requests keys from another using Key requests, the device from which the key is being requested may want to tell the requester that it is purposely not sharing the key.

If Alice withholds a megolm session from Bob for some messages in a room, and then later on decides to allow Bob to decrypt later messages, she can send Bob the megolm session, ratcheted up to the point at which she allows Bob to decrypt the messages. If Bob logs into a new device and uses key sharing to obtain the decryption keys, the new device will be sent the megolm sessions that have been ratcheted up. Bob’s old device can include the reason that the session was initially not shared by including a withheld property in the m.forwarded_room_key message that is an object with the code and reason properties from the m.room_key.withheld message.

{{m_room_key_withheld_event}}

Secrets

Clients may have secret information that they wish to be made available to other authorised clients, but that the server should not be able to see, so the information must be encrypted as it passes through the server. This can be done either asynchronously, by storing encrypted data on the server for later retrieval, or synchronously, by sending messages to each other.

Each secret has an identifier that is used by clients to refer to the secret when storing, fetching, requesting, or sharing the secret. Secrets are plain strings; structured data can be stored by encoding it as a string.

Storage

When secrets are stored on the server, they are stored in the user’s account-data, using an event type equal to the secret’s identifier. The keys that secrets are encrypted with are described by data that is also stored in the user’s account-data. Users can have multiple keys, allowing them to control what sets of secrets clients can access, depending on what keys are given to them.

Key storage

Each key has an ID, and the description of the key is stored in the user’s account_data using the event type m.secret_storage.key.[key ID]. The contents of the account data for the key will include an algorithm property, which indicates the encryption algorithm used, as well as a name property, which is a human-readable name. Key descriptions may also have a passphrase property for generating the key from a user-entered passphrase, as described in deriving keys from passphrases.

KeyDescription

Parameter Type Description
name string Required. The name of the key.

algorithm

string

Required. The encryption algorithm to be used for this key. Currently, only m.secret_storage.v1.aes-hmac-sha2 is supported.

passphrase

string

See deriving keys from passphrases section for a description of this property.

Other properties depend on the encryption algorithm, and are described below.

A key can be marked as the “default” key by setting the user’s account_data with event type m.secret_storage.default_key to an object that has the ID of the key as its key property. The default key will be used to encrypt all secrets that the user would expect to be available on all their clients. Unless the user specifies otherwise, clients will try to use the default key to decrypt secrets.

Secret storage

Encrypted data is stored in the user’s account_data using the event type defined by the feature that uses the data. The account_data will have an encrypted property that is a map from key ID to an object. The algorithm from the m.secret_storage.key.[key ID] data for the given key defines how the other properties are interpreted, though it’s expected that most encryption schemes would have ciphertext and mac properties, where the ciphertext property is the unpadded base64-encoded ciphertext, and the mac is used to ensure the integrity of the data.

Secret

Parameter Type Description

encrypted

{string: object}

Required. Map from key ID the encrypted data. The exact format for the encrypted data is dependent on the key algorithm. See the definition of AesHmacSha2EncryptedData in the m.secret_storage.v1.aes-hmac-sha2 section.

Example:

Some secret is encrypted using keys with ID key_id_1 and key_id_2:

org.example.some.secret:

{
  "encrypted": {
    "key_id_1": {
      "ciphertext": "base64+encoded+encrypted+data",
      "mac": "base64+encoded+mac",
      // ... other properties according to algorithm property in
      // m.secret_storage.key.key_id_1
    },
    "key_id_2": {
      // ...
    }
  }
}

and the key descriptions for the keys would be:

m.secret_storage.key.key_id_1:

{
  "name": "Some key",
  "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
  // ... other properties according to algorithm
}

m.secret_storage.key.key_id_2:

{
  "name": "Some other key",
  "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
  // ... other properties according to algorithm
}
m.secret_storage.v1.aes-hmac-sha2

Secrets encrypted using the m.secret_storage.v1.aes-hmac-sha2 algorithm are encrypted using AES-CTR-256, and authenticated using HMAC-SHA-256. The secret is encrypted as follows:

  1. Given the secret storage key, generate 64 bytes by performing an HKDF with SHA-256 as the hash, a salt of 32 bytes of 0, and with the secret name as the info. The first 32 bytes are used as the AES key, and the next 32 bytes are used as the MAC key
  2. Generate 16 random bytes, set bit 63 to 0 (in order to work around differences in AES-CTR implementations), and use this as the AES initialization vector. This becomes the iv property, encoded using base64.
  3. Encrypt the data using AES-CTR-256 using the AES key generated above. This encrypted data, encoded using base64, becomes the ciphertext property.
  4. Pass the raw encrypted data (prior to base64 encoding) through HMAC-SHA-256 using the MAC key generated above. The resulting MAC is base64-encoded and becomes the mac property.

AesHmacSha2EncryptedData

Parameter Type Description

iv

string

Required. The 16-byte initialization vector, encoded as base64.

ciphertext

string

Required. The AES-CTR-encrypted data, encoded as base64.

mac string Required. The MAC, encoded as base64.

For the purposes of allowing clients to check whether a user has correctly entered the key, clients should:

  1. encrypt and MAC a message consisting of 32 bytes of 0 as described above, using the empty string as the info parameter to the HKDF in step 1.
  2. store the iv and mac in the m.secret_storage.key.[key ID] account-data.

AesHmacSha2KeyDescription

Parameter Type Description
name string Required. The name of the key.

algorithm

string

Required. The encryption algorithm to be used for this key. Currently, only m.secret_storage.v1.aes-hmac-sha2 is supported.

passphrase

object

See deriving keys from passphrases section for a description of this property.

iv string The 16-byte initialization vector, encoded as base64.

mac

string

The MAC of the result of encrypting 32 bytes of 0, encoded as base64.

For example, the m.secret_storage.key.key_id for a key using this algorithm could look like:

{
  "name": "m.default",
  "algorithm": "m.secret_storage.v1.aes-hmac-sha2",
  "iv": "random+data",
  "mac": "mac+of+encrypted+zeros"
}

and data encrypted using this algorithm could look like this:

{
  "encrypted": {
      "key_id": {
        "iv": "16+bytes+base64",
        "ciphertext": "base64+encoded+encrypted+data",
        "mac": "base64+encoded+mac"
      }
  }
}
Key representation

When a user is given a raw key for m.secret_storage.v1.aes-hmac-sha2, it will be presented as a string constructed as follows:

  1. The key is prepended by the two bytes 0x8b and 0x01
  2. All the bytes in the string above, including the two header bytes, are XORed together to form a parity byte. This parity byte is appended to the byte string.
  3. The byte string is encoded using base58, using the same mapping as is used for Bitcoin addresses, that is, using the alphabet 123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz.
  4. The string is formatted into groups of four characters separated by spaces.

When decoding a raw key, the process should be reversed, with the exception that whitespace is insignificant in the user’s input.

Deriving keys from passphrases

A user may wish to use a chosen passphrase rather than a randomly generated key. In this case, information on how to generate the key from a passphrase will be stored in the passphrase property of the m.secret_storage.key.[key ID] account-data. The passphrase property has an algorithm property that indicates how to generate the key from the passphrase. Other properties of the passphrase property are defined by the algorithm specified.

####### m.pbkdf2

For the m.pbkdf2 algorithm, the passphrase property has the following properties:

Parameter Type Description
algorithm string Required. Must be m.pbkdf2
salt string Required. The salt used in PBKDF2.
iterations integer Required. The number of iterations to use in PBKDF2.

bits

integer

Optional. The number of bits to generate for the key. Defaults to 256.

The key is generated using PBKDF2 with SHA-512 as the hash, using the salt given in the salt parameter, and the number of iterations given in the iterations parameter.

Example:

{
    "passphrase": {
        "algorithm": "m.pbkdf2",
        "salt": "MmMsAlty",
        "iterations": 100000,
        "bits": 256
    },
    ...
}

Sharing

To request a secret from other devices, a client sends an m.secret.requests device event with action set to request and name set to the identifier of the secret. A device that wishes to share the secret will reply with an m.secret.send event, encrypted using olm. When the original client obtains the secret, it sends an m.secret.request event with action set to request_cancellation to all devices other than the one that it received the secret from. Clients should ignore m.secret.send events received from devices that it did not send an m.secret.request event to.

Clients must ensure that they only share secrets with other devices that are allowed to see them. For example, clients should only share secrets with the user’s own devices that are verified and may prompt the user to confirm sharing the secret.

Event definitions
m.secret.request

Sent by a client to request a secret from another device or to cancel a previous request. It is sent as an unencrypted to-device event.

Parameter Type Description

name

string

Required if action is request. The name of the secret that is being requested.

action enum Required. One of ["request", "request_cancellation"].
requesting_device_id string Required. The ID of the device requesting the secret.

request_id

string

Required. A random string uniquely identifying (with respect to the requester and the target) the target for a secret. If the secret is requested from multiple devices at the same time, the same ID may be used for every target. The same ID is also used in order to cancel a previous request.

Example:

{
  "name": "org.example.some.secret",
  "action": "request",
  "requesting_device_id": "ABCDEFG",
  "request_id": "randomly_generated_id_9573"
}
m.secret.send

Sent by a client to share a secret with another device, in response to an m.secret.request event. It must be encrypted as an m.room.encrypted event, then sent as a to-device event.

Parameter Type Description
request_id string Required. The ID of the request that this a response to.
secret string Required. The contents of the secret.

Example:

{
  "request_id": "randomly_generated_id_9573",
  "secret": "ThisIsASecretDon'tTellAnyone"
}

Room History Visibility

This module adds support for controlling the visibility of previous events in a room.

In all cases except world_readable, a user needs to join a room to view events in that room. Once they have joined a room, they will gain access to a subset of events in the room. How this subset is chosen is controlled by the m.room.history_visibility event outlined below. After a user has left a room, they may see any events which they were allowed to see before they left the room, but no events received after they left.

The four options for the m.room.history_visibility event are:

  • world_readable - All events while this is the m.room.history_visibility value may be shared by any participating homeserver with anyone, regardless of whether they have ever joined the room.
  • shared - Previous events are always accessible to newly joined members. All events in the room are accessible, even those sent when the member was not a part of the room.
  • invited - Events are accessible to newly joined members from the point they were invited onwards. Events stop being accessible when the member’s state changes to something other than invite or join.
  • joined - Events are accessible to newly joined members from the point they joined the room onwards. Events stop being accessible when the member’s state changes to something other than join.

Warning

These options are applied at the point an event is sent. Checks are performed with the state of the m.room.history_visibility event when the event in question is added to the DAG. This means clients cannot retrospectively choose to show or hide history to new users if the setting at that time was more restrictive.

Events

{{m_room_history_visibility_event}}

Client behaviour

Clients that implement this module MUST present to the user the possible options for setting history visibility when creating a room.

Clients may want to display a notice that their events may be read by non-joined people if the value is set to world_readable.

Server behaviour

By default if no history_visibility is set, or if the value is not understood, the visibility is assumed to be shared. The rules governing whether a user is allowed to see an event depend on the state of the room at that event.

  1. If the history_visibility was set to world_readable, allow.
  2. If the user’s membership was join, allow.
  3. If history_visibility was set to shared, and the user joined the room at any point after the event was sent, allow.
  4. If the user’s membership was invite, and the history_visibility was set to invited, allow.
  5. Otherwise, deny.

For m.room.history_visibility events themselves, the user should be allowed to see the event if the history_visibility before or after the event would allow them to see it. (For example, a user should be able to see m.room.history_visibility events which change the history_visibility from world_readable to joined or from joined to world_readable, even if that user was not a member of the room.)

Likewise, for the user’s own m.room.member events, the user should be allowed to see the event if their membership before or after the event would allow them to see it. (For example, a user can always see m.room.member events which set their membership to join, or which change their membership from join to any other value, even if history_visibility is joined.)

Security considerations

The default value for history_visibility is shared for backwards-compatibility reasons. Clients need to be aware that by not setting this event they are exposing all of their room history to anyone in the room.

Push Notifications

+--------------------+  +-------------------+
Matrix HTTP      |                    |  |                   |
Notification Protocol |   App Developer    |  |   Device Vendor   |
|                    |  |                   |
+-------------------+   | +----------------+ |  | +---------------+ |
|                   |   | |                | |  | |               | |
| Matrix homeserver +----->  Push Gateway  +------> Push Provider | |
|                   |   | |                | |  | |               | |
+-^-----------------+   | +----------------+ |  | +----+----------+ |
|                     |                    |  |      |            |
Matrix   |                     |                    |  |      |            |
Client/Server API  +              |                    |  |      |            |
|      |              +--------------------+  +-------------------+
|   +--+-+                                           |
|   |    <-------------------------------------------+
+---+    |
|    |          Provider Push Protocol
+----+

Mobile Device or Client

This module adds support for push notifications. Homeservers send notifications of events to user-configured HTTP endpoints. Users may also configure a number of rules that determine which events generate notifications. These are all stored and managed by the user’s homeserver. This allows user-specific push settings to be reused between client applications.

The above diagram shows the flow of push notifications being sent to a handset where push notifications are submitted via the handset vendor, such as Apple’s APNS or Google’s GCM. This happens as follows:

  1. The client app signs in to a homeserver.
  2. The client app registers with its vendor’s Push Provider and obtains a routing token of some kind.
  3. The mobile app uses the Client/Server API to add a ‘pusher’, providing the URL of a specific Push Gateway which is configured for that application. It also provides the routing token it has acquired from the Push Provider.
  4. The homeserver starts sending HTTP requests to the Push Gateway using the supplied URL. The Push Gateway relays this notification to the Push Provider, passing the routing token along with any necessary private credentials the provider requires to send push notifications.
  5. The Push Provider sends the notification to the device.

Definitions for terms used in this section are below:

Push Provider
A push provider is a service managed by the device vendor which can send notifications directly to the device. Google Cloud Messaging (GCM) and Apple Push Notification Service (APNS) are two examples of push providers.

Push Gateway
A push gateway is a server that receives HTTP event notifications from homeservers and passes them on to a different protocol such as APNS for iOS devices or GCM for Android devices. Clients inform the homeserver which Push Gateway to send notifications to when it sets up a Pusher.

Pusher
A pusher is a worker on the homeserver that manages the sending of HTTP notifications for a user. A user can have multiple pushers: one per device.

Push Rule
A push rule is a single rule that states under what conditions an event should be passed onto a push gateway and how the notification should be presented. These rules are stored on the user’s homeserver. They are manually configured by the user, who can create and view them via the Client/Server API.

Push Ruleset
A push ruleset scopes a set of rules according to some criteria. For example, some rules may only be applied for messages from a particular sender, a particular room, or by default. The push ruleset contains the entire set of scopes and rules.

Client behaviour

Clients MUST configure a Pusher before they will receive push notifications. There is a single API endpoint for this, as described below.

GET /_matrix/client/r0/pushers


Gets all currently active pushers for the authenticated user.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 The pushers for this user.

200 response body

Name Type Description
pushers Pushers An array containing the current pushers for the user
Pusher
Name Type Description
app_display_name string Required: A string that will allow the user to identify what application owns this pusher.
app_id string Required: This is a reverse-DNS style identifier for the application. Max length, 64 chars.
data PusherData Required: A dictionary of information for the pusher implementation itself.
device_display_name string Required: A string that will allow the user to identify what device owns this pusher.
kind string Required: The kind of pusher. "http" is a pusher that sends HTTP pokes.
lang string Required: The preferred language for receiving notifications (e.g. ‘en’ or ‘en-US’)
profile_tag string This string determines which set of device specific rules this pusher executes.
pushkey string Required: This is a unique identifier for this pusher. See /set for more detail. Max length, 512 bytes.
PusherData
Name Type Description
format string The format to use when sending notifications to the Push Gateway.
url string Required if kind is http. The URL to use to send notifications to.

200 response body example

{
  "pushers": [
    {
      "app_display_name": "Appy McAppface",
      "app_id": "face.mcapp.appy.prod",
      "data": {
        "url": "https://example.com/_matrix/push/v1/notify"
      },
      "device_display_name": "Alice's Phone",
      "kind": "http",
      "lang": "en-US",
      "profile_tag": "xyz",
      "pushkey": "Xp/MzCt8/9DcSNE9cuiaoT5Ac55job3TdLSSmtmYl4A="
    }
  ]
}

POST /_matrix/client/r0/pushers/set


This endpoint allows the creation, modification and deletion of `pushers`_ for this user ID. The behaviour of this endpoint varies depending on the values in the JSON body.

Rate-limited: Yes
Requires authentication: Yes

Request

Request body

Name Type Description
app_display_name string Required: A string that will allow the user to identify what application owns this pusher.
app_id string Required:

This is a reverse-DNS style identifier for the application. It is recommended that this end with the platform, such that different platform versions get different app identifiers. Max length, 64 chars.

If the kind is "email", this is "m.email".

append boolean If true, the homeserver should add another pusher with the given pushkey and App ID in addition to any others with different user IDs. Otherwise, the homeserver must remove any other pushers with the same App ID and pushkey for different users. The default is false.
data PusherData Required: A dictionary of information for the pusher implementation itself. If kind is http, this should contain url which is the URL to use to send notifications to.
device_display_name string Required: A string that will allow the user to identify what device owns this pusher.
kind string Required: The kind of pusher to configure. "http" makes a pusher that sends HTTP pokes. "email" makes a pusher that emails the user with unread notifications. null deletes the pusher.
lang string Required: The preferred language for receiving notifications (e.g. ‘en’ or ‘en-US’).
profile_tag string This string determines which set of device specific rules this pusher executes.
pushkey string Required:

This is a unique identifier for this pusher. The value you should use for this is the routing or destination address information for the notification, for example, the APNS token for APNS or the Registration ID for GCM. If your notification client has no such concept, use any unique identifier. Max length, 512 bytes.

If the kind is "email", this is the email address to send notifications to.

PusherData
Name Type Description
format string The format to send notifications in to Push Gateways if the kind is http. The details about what fields the homeserver should send to the push gateway are defined in the Push Gateway Specification_. Currently the only format available is ‘event_id_only’.
url string Required if kind is http. The URL to use to send notifications to. MUST be an HTTPS URL with a path of /_matrix/push/v1/notify.

Request body example

{
  "app_display_name": "Mat Rix",
  "app_id": "com.example.app.ios",
  "append": false,
  "data": {
    "format": "event_id_only",
    "url": "https://push-gateway.location.here/_matrix/push/v1/notify"
  },
  "device_display_name": "iPhone 9",
  "kind": "http",
  "lang": "en",
  "profile_tag": "xxyyzz",
  "pushkey": "APA91bHPRgkF3JUikC4ENAHEeMrd41Zxv3hVZjC9KtT8OvPVGJ-hQMRKRrZuJAEcl7B338qju59zJMjw2DELjzEvxwYv7hH5Ynpc1ODQ0aT4U4OFEeco8ohsN5PjL1iC2dNtk2BAokeMCg2ZXKqpc8FXKmhX94kIxQ"
}

Responses

Status Description
200 The pusher was set.
400 One or more of the pusher values were invalid.
429 This request was rate-limited.
Listing Notifications

A client can retrieve a list of events that it has been notified about. This may be useful so that users can see a summary of what important messages they have received.

GET /_matrix/client/r0/notifications


This API is used to paginate through the list of events that the user has been, or would have been notified about.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

query parameters
Name Type Description
from string Pagination token given to retrieve the next set of events.
limit integer Limit on the number of events to return in this request.
only string Allows basic filtering of events returned. Supply highlight to return only events where the notification had the highlight tweak set.

Responses

Status Description
200 A batch of events is being returned

200 response body

Name Type Description
next_token string The token to supply in the from param of the next /notifications request in order to request more events. If this is absent, there are no more results.
notifications [Notification] Required: The list of events that triggered notifications.
Notification
Name Type Description
actions [] Required: The action(s) to perform when the conditions for this rule are met. See Push Rules: API_.
event Event Required: The Event object for the event that triggered the notification.
profile_tag string The profile tag of the rule that matched this event.
read boolean Required: Indicates whether the user has sent a read receipt indicating that they have read this message.
room_id string Required: The ID of the room in which the event was posted.
ts integer Required: The unix timestamp at which the event notification was sent, in milliseconds.
Event
Name Type Description
content EventContent The content of this event. The fields in this object will vary depending on the type of event.
event_id string The ID of this event, if applicable.
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 UnsignedData Information about this event which was not sent by the originating homeserver
UnsignedData
Name 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.
redacted_because Event Optional. The event that redacted this event, if any.
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.

200 response body example

{
  "next_token": "abcdef",
  "notifications": [
    {
      "actions": [
        "notify"
      ],
      "event": {
        "content": {
          "body": "This is an example text message",
          "format": "org.matrix.custom.html",
          "formatted_body": "\u003cb\u003eThis is an example text message\u003c/b\u003e",
          "key": "value",
          "msgtype": "m.text"
        },
        "event_id": "$143273582443PhrSn:example.org",
        "origin_server_ts": 1432735824653,
        "room_id": "!jEsUZKDJdhlrceRyVU:example.org",
        "sender": "@example:example.org",
        "type": "m.room.message",
        "unsigned": {
          "age": 1234
        }
      },
      "profile_tag": "hcbvkzxhcvb",
      "read": true,
      "room_id": "!abcdefg:example.com",
      "ts": 1475508881945
    }
  ]
}
Receiving notifications

Servers MUST include the number of unread notifications in a client’s /sync stream, and MUST update it as it changes. Notifications are determined by the push rules which apply to an event.

When the user updates their read receipt (either by using the API or by sending an event), notifications prior to and including that event MUST be marked as read.

Push Rules

A push rule is a single rule that states under what conditions an event should be passed onto a push gateway and how the notification should be presented. There are different “kinds” of push rules and each rule has an associated priority. Every push rule MUST have a kind and rule_id. The rule_id is a unique string within the kind of rule and its' scope: rule_ids do not need to be unique between rules of the same kind on different devices. Rules may have extra keys depending on the value of kind.

The different kinds of rule, in the order that they are checked, are:

Override Rules override
The highest priority rules are user-configured overrides.

Content-specific Rules content
These configure behaviour for (unencrypted) messages that match certain patterns. Content rules take one parameter: pattern, that gives the glob pattern to match against. This is treated in the same way as pattern for event_match.

Room-specific Rules room
These rules change the behaviour of all messages for a given room. The rule_id of a room rule is always the ID of the room that it affects.

Sender-specific rules sender
These rules configure notification behaviour for messages from a specific Matrix user ID. The rule_id of Sender rules is always the Matrix user ID of the user whose messages they’d apply to.

Underride rules underride
These are identical to override rules, but have a lower priority than content, room and sender rules.

Rules with the same kind can specify an ordering priority. This determines which rule is selected in the event of multiple matches. For example, a rule matching “tea” and a separate rule matching “time” would both match the sentence “It’s time for tea”. The ordering of the rules would then resolve the tiebreak to determine which rule is executed. Only actions for highest priority rule will be sent to the Push Gateway.

Each rule can be enabled or disabled. Disabled rules never match. If no rules match an event, the homeserver MUST NOT notify the Push Gateway for that event. Homeservers MUST NOT notify the Push Gateway for events that the user has sent themselves.

Actions

All rules have an associated list of actions. An action affects if and how a notification is delivered for a matching event. The following actions are defined:

notify
This causes each matching event to generate a notification.

dont_notify
This prevents each matching event from generating a notification

coalesce
This enables notifications for matching events but activates homeserver specific behaviour to intelligently coalesce multiple events into a single notification. Not all homeservers may support this. Those that do not support it should treat it as the notify action.

set_tweak
Sets an entry in the tweaks dictionary key that is sent in the notification request to the Push Gateway. This takes the form of a dictionary with a set_tweak key whose value is the name of the tweak to set. It may also have a value key which is the value to which it should be set.

Actions that have no parameters are represented as a string. Otherwise, they are represented as a dictionary with a key equal to their name and other keys as their parameters, e.g. { "set_tweak": "sound", "value": "default" }

####### Tweaks

The set_tweak action is used to add an entry to the ‘tweaks’ dictionary that is sent in the notification request to the Push Gateway. The following tweaks are defined:

sound
A string representing the sound to be played when this notification arrives. A value of default means to play a default sound. A device may choose to alert the user by some other means if appropriate, eg. vibration.

highlight
A boolean representing whether or not this message should be highlighted in the UI. This will normally take the form of presenting the message in a different colour and/or style. The UI might also be adjusted to draw particular attention to the room in which the event occurred. If a highlight tweak is given with no value, its value is defined to be true. If no highlight tweak is given at all then the value of highlight is defined to be false.

Tweaks are passed transparently through the homeserver so client applications and Push Gateways may agree on additional tweaks. For example, a tweak may be added to specify how to flash the notification light on a mobile device.

Conditions

override and underride rules MAY have a list of ‘conditions’. All conditions must hold true for an event in order for the rule to match. A rule with no conditions always matches. The following conditions are defined:

event_match
This is a glob pattern match on a field of the event. Parameters:

  • key: The dot-separated field of the event to match, e.g. content.body
  • pattern: The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition.

contains_display_name
This matches unencrypted messages where content.body contains the owner’s display name in that room. This is a separate rule because display names may change and as such it would be hard to maintain a rule that matched the user’s display name. This condition has no parameters.

room_member_count
This matches the current number of members in the room. Parameters:

  • is: A decimal integer optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches rooms where the member count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ==.

sender_notification_permission
This takes into account the current power levels in the room, ensuring the sender of the event has high enough power to trigger the notification.

Parameters:

  • key: A string that determines the power level the sender must have to trigger notifications of a given type, such as room. Refer to the m.room.power_levels event schema for information about what the defaults are and how to interpret the event. The key is used to look up the power level required to send a notification type from the notifications object in the power level event content.

Unrecognised conditions MUST NOT match any events, effectively making the push rule disabled.

room, sender and content rules do not have conditions in the same way, but instead have predefined conditions. In the cases of room and sender rules, the rule_id of the rule determines its behaviour.

Predefined Rules

Homeservers can specify “server-default rules” which operate at a lower priority than “user-defined rules”. The rule_id for all server-default rules MUST start with a dot (".") to identify them as “server-default”. The following server-default rules are specified:

####### Default Override Rules

######## .m.rule.master

Matches all events. This can be enabled to turn off all push notifications other than those generated by override rules set by the user. By default this rule is disabled.

Definition

{
    "rule_id": ".m.rule.master",
    "default": true,
    "enabled": false,
    "conditions": [],
    "actions": [
        "dont_notify"
    ]
}

######## .m.rule.suppress_notices

Matches messages with a msgtype of notice.

Definition:

{
    "rule_id": ".m.rule.suppress_notices",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "content.msgtype",
            "pattern": "m.notice",
        }
    ],
    "actions": [
        "dont_notify",
    ]
}

######## .m.rule.invite_for_me

Matches any invites to a new room for this user.

Definition:

{
    "rule_id": ".m.rule.invite_for_me",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
        },
        {
            "key": "content.membership",
            "kind": "event_match",
            "pattern": "invite"
        },
        {
            "key": "state_key",
            "kind": "event_match",
            "pattern": "[the user's Matrix ID]"
        }
    ],
    "actions": [
       "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}

######## .m.rule.member_event

Matches any m.room.member_event.

Definition:

{
    "rule_id": ".m.rule.member_event",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
        }
    ],
    "actions": [
        "dont_notify"
    ]
}

######## .m.rule.contains_display_name

Matches any message whose content is unencrypted and contains the user’s current display name in the room in which it was sent.

Definition:

{
    "rule_id": ".m.rule.contains_display_name",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "contains_display_name"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        },
        {
            "set_tweak": "highlight"
        }
    ]
}

######## .m.rule.tombstone

Matches any state event whose type is m.room.tombstone. This is intended to notify users of a room when it is upgraded, similar to what an @room notification would accomplish.

Definition:

{
    "rule_id": ".m.rule.tombstone",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.tombstone"
        },
        {
            "kind": "event_match",
            "key": "state_key",
            "pattern": ""
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "highlight"
        }
    ]
}

######## .m.rule.roomnotif

Matches any message whose content is unencrypted and contains the text @room, signifying the whole room should be notified of the event.

Definition:

{
    "rule_id": ".m.rule.roomnotif",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "event_match",
            "key": "content.body",
            "pattern": "@room"
        },
        {
            "kind": "sender_notification_permission",
            "key": "room"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "highlight"
        }
    ]
}

####### Default Content Rules

######## .m.rule.contains_user_name

Matches any message whose content is unencrypted and contains the local part of the user’s Matrix ID, separated by word boundaries.

Definition (as a content rule):

{
    "rule_id": ".m.rule.contains_user_name",
    "default": true,
    "enabled": true,
    "pattern": "[the local part of the user's Matrix ID]",
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        },
        {
            "set_tweak": "highlight"
        }
    ]
}

####### Default Underride Rules

######## .m.rule.call

Matches any incoming VOIP call.

Definition:

{
    "rule_id": ".m.rule.call",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.call.invite"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "ring"
        }
    ]
}

######## .m.rule.encrypted_room_one_to_one

Matches any encrypted event sent in a room with exactly two members. Unlike other push rules, this rule cannot be matched against the content of the event by nature of it being encrypted. This causes the rule to be an “all or nothing” match where it either matches all events that are encrypted (in 1:1 rooms) or none.

Definition:

{
    "rule_id": ".m.rule.encrypted_room_one_to_one",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "room_member_count",
            "is": "2"
        },
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.encrypted"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}

######## .m.rule.room_one_to_one

Matches any message sent in a room with exactly two members.

Definition:

{
    "rule_id": ".m.rule.room_one_to_one",
    "default": true,
    "enabled": true,
    "conditions": [
        {
            "kind": "room_member_count",
            "is": "2"
        },
        {
            "kind": "event_match",
            "key": "type",
            "pattern": "m.room.message"
        }
    ],
    "actions": [
        "notify",
        {
            "set_tweak": "sound",
            "value": "default"
        }
    ]
}

######## .m.rule.message

Matches all chat messages.

Definition:

{
     "rule_id": ".m.rule.message",
     "default": true,
     "enabled": true,
     "conditions": [
         {
             "kind": "event_match",
             "key": "type",
             "pattern": "m.room.message"
         }
     ],
     "actions": [
         "notify"
     ]
}

######## .m.rule.encrypted

Matches all encrypted events. Unlike other push rules, this rule cannot be matched against the content of the event by nature of it being encrypted. This causes the rule to be an “all or nothing” match where it either matches all events that are encrypted (in group rooms) or none.

Definition:

{
     "rule_id": ".m.rule.encrypted",
     "default": true,
     "enabled": true,
     "conditions": [
         {
             "kind": "event_match",
             "key": "type",
             "pattern": "m.room.encrypted"
         }
     ],
     "actions": [
         "notify"
     ]
}
Push Rules: API

Clients can retrieve, add, modify and remove push rules globally or per-device using the APIs below.

GET /_matrix/client/r0/pushrules/


Retrieve all push rulesets for this user. Clients can "drill-down" on the rulesets by suffixing a ``scope`` to this path e.g. ``/pushrules/global/``. This will return a subset of this data under the specified key e.g. the ``global`` key.

Rate-limited: No
Requires authentication: Yes

Request

No request parameters or request body.

Responses

Status Description
200 All the push rulesets for this user.

200 response body

Name Type Description
global Ruleset Required: The global ruleset.
Ruleset
Name Type Description
content [PushRule]
override [PushRule]
room [PushRule]
sender [PushRule]
underride [PushRule]
PushRule
Name Type Description
actions [] Required: The actions to perform when this rule is matched.
conditions [] The conditions that must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Only applicable to underride and override rules.
default boolean Required: Whether this is a default rule, or has been set explicitly.
enabled boolean Required: Whether the push rule is enabled or not.
pattern string The glob-style pattern to match against. Only applicable to content rules.
rule_id string Required: The ID of this rule.
PushCondition
Name Type Description
is string Required for room_member_count conditions. A decimal integer optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches rooms where the member count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ==.
key string

Required for event_match conditions. The dot-separated field of the event to match.

Required for sender_notification_permission conditions. The field in the power level event the user needs a minimum power level for. Fields must be specified under the notifications property in the power level event’s content.

kind string Required: The kind of condition to apply. See conditions <#conditions>_ for more information on the allowed kinds and how they work.
pattern string Required for event_match conditions. The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition.

200 response body example

{
  "global": {
    "content": [
      {
        "actions": [
          "notify",
          {
            "set_tweak": "sound",
            "value": "default"
          },
          {
            "set_tweak": "highlight"
          }
        ],
        "default": true,
        "enabled": true,
        "pattern": "alice",
        "rule_id": ".m.rule.contains_user_name"
      }
    ],
    "override": [
      {
        "actions": [
          "dont_notify"
        ],
        "conditions": [],
        "default": true,
        "enabled": false,
        "rule_id": ".m.rule.master"
      },
      {
        "actions": [
          "dont_notify"
        ],
        "conditions": [
          {
            "key": "content.msgtype",
            "kind": "event_match",
            "pattern": "m.notice"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.suppress_notices"
      }
    ],
    "room": [],
    "sender": [],
    "underride": [
      {
        "actions": [
          "notify",
          {
            "set_tweak": "sound",
            "value": "ring"
          },
          {
            "set_tweak": "highlight",
            "value": false
          }
        ],
        "conditions": [
          {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.call.invite"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.call"
      },
      {
        "actions": [
          "notify",
          {
            "set_tweak": "sound",
            "value": "default"
          },
          {
            "set_tweak": "highlight"
          }
        ],
        "conditions": [
          {
            "kind": "contains_display_name"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.contains_display_name"
      },
      {
        "actions": [
          "notify",
          {
            "set_tweak": "sound",
            "value": "default"
          },
          {
            "set_tweak": "highlight",
            "value": false
          }
        ],
        "conditions": [
          {
            "is": "2",
            "kind": "room_member_count"
          },
          {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.message"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.room_one_to_one"
      },
      {
        "actions": [
          "notify",
          {
            "set_tweak": "sound",
            "value": "default"
          },
          {
            "set_tweak": "highlight",
            "value": false
          }
        ],
        "conditions": [
          {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
          },
          {
            "key": "content.membership",
            "kind": "event_match",
            "pattern": "invite"
          },
          {
            "key": "state_key",
            "kind": "event_match",
            "pattern": "@alice:example.com"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.invite_for_me"
      },
      {
        "actions": [
          "notify",
          {
            "set_tweak": "highlight",
            "value": false
          }
        ],
        "conditions": [
          {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.member"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.member_event"
      },
      {
        "actions": [
          "notify",
          {
            "set_tweak": "highlight",
            "value": false
          }
        ],
        "conditions": [
          {
            "key": "type",
            "kind": "event_match",
            "pattern": "m.room.message"
          }
        ],
        "default": true,
        "enabled": true,
        "rule_id": ".m.rule.message"
      }
    ]
  }
}

GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}


Retrieve a single specified push rule.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: global to specify global rules.

Responses

Status Description
200 The specific push rule. This will also include keys specific to the rule itself such as the rule’s actions and conditions if set.

200 response body

PushRule
Name Type Description
actions [] Required: The actions to perform when this rule is matched.
conditions [] The conditions that must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Only applicable to underride and override rules.
default boolean Required: Whether this is a default rule, or has been set explicitly.
enabled boolean Required: Whether the push rule is enabled or not.
pattern string The glob-style pattern to match against. Only applicable to content rules.
rule_id string Required: The ID of this rule.
PushCondition
Name Type Description
is string Required for room_member_count conditions. A decimal integer optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches rooms where the member count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ==.
key string

Required for event_match conditions. The dot-separated field of the event to match.

Required for sender_notification_permission conditions. The field in the power level event the user needs a minimum power level for. Fields must be specified under the notifications property in the power level event’s content.

kind string Required: The kind of condition to apply. See conditions <#conditions>_ for more information on the allowed kinds and how they work.
pattern string Required for event_match conditions. The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition.

200 response body example

{
  "actions": [
    "dont_notify"
  ],
  "default": false,
  "enabled": true,
  "pattern": "cake*lie",
  "rule_id": "nocake"
}

PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}


This endpoint allows the creation, modification and deletion of pushers for this user ID. The behaviour of this endpoint varies depending on the values in the JSON body.

When creating push rules, they MUST be enabled by default.

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: global to specify global rules.
query parameters
Name Type Description
after string This makes the new rule the next-less important rule relative to the given user defined rule. It is not possible to add a rule relative to a predefined server rule.
before string Use ‘before’ with a rule_id as its value to make the new rule the next-most important rule with respect to the given user defined rule. It is not possible to add a rule relative to a predefined server rule.

Request body

Name Type Description
actions [] Required: The action(s) to perform when the conditions for this rule are met.
conditions [object] The conditions that must hold true for an event in order for a rule to be applied to an event. A rule with no conditions always matches. Only applicable to underride and override rules.
pattern string Only applicable to content rules. The glob-style pattern to match against.
PushCondition
Name Type Description
is string Required for room_member_count conditions. A decimal integer optionally prefixed by one of, ==, <, >, >= or <=. A prefix of < matches rooms where the member count is strictly less than the given number and so forth. If no prefix is present, this parameter defaults to ==.
key string

Required for event_match conditions. The dot-separated field of the event to match.

Required for sender_notification_permission conditions. The field in the power level event the user needs a minimum power level for. Fields must be specified under the notifications property in the power level event’s content.

kind string Required: The kind of condition to apply. See conditions <#conditions>_ for more information on the allowed kinds and how they work.
pattern string Required for event_match conditions. The glob-style pattern to match against. Patterns with no special glob characters should be treated as having asterisks prepended and appended when testing the condition.

Request body example

{
  "actions": [
    "notify"
  ],
  "pattern": "cake*lie"
}

Responses

Status Description
200 The push rule was created/updated.
400 There was a problem configuring this push rule.
429 This request was rate-limited.

DELETE /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}


This endpoint removes the push rule defined in the path.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: global to specify global rules.

Responses

Status Description
200 The push rule was deleted.

GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions


This endpoint get the actions for the specified push rule.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: Either global or device/<profile_tag> to specify global rules or device rules for the given profile_tag.

Responses

Status Description
200 The actions for this push rule.

200 response body

Name Type Description
actions [] Required: The action(s) to perform for this rule.

200 response body example

{
  "actions": [
    "notify",
    {
      "set_tweak": "sound",
      "value": "bing"
    }
  ]
}

PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/actions


This endpoint allows clients to change the actions of a push rule. This can be used to change the actions of builtin rules.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: global to specify global rules.

Request body

Name Type Description
actions [] Required: The action(s) to perform for this rule.

Request body example

{
  "actions": [
    "notify",
    {
      "set_tweak": "highlight"
    }
  ]
}

Responses

Status Description
200 The actions for the push rule were set.

GET /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/enabled


This endpoint gets whether the specified push rule is enabled.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: Either global or device/<profile_tag> to specify global rules or device rules for the given profile_tag.

Responses

Status Description
200 Whether the push rule is enabled.

200 response body

Name Type Description
enabled boolean Required: Whether the push rule is enabled or not.

200 response body example

{
  "enabled": true
}

PUT /_matrix/client/r0/pushrules/{scope}/{kind}/{ruleId}/enabled


This endpoint allows clients to enable or disable the specified push rule.

Rate-limited: No
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
kind enum Required: The kind of rule

One of: [override underride sender room content].

ruleId string Required: The identifier for the rule.
scope string Required: global to specify global rules.

Request body

Name Type Description
enabled boolean Required: Whether the push rule is enabled or not.

Request body example

{
  "enabled": true
}

Responses

Status Description
200 The push rule was enabled or disabled.
Push Rules: Events

When a user changes their push rules a m.push_rules event is sent to all clients in the account_data section of their next /sync request. The content of the event is the current push rules for the user.

{{m_push_rules_event}}

Examples

To create a rule that suppresses notifications for the room with ID !dj234r78wl45Gh4D:matrix.org:

curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/room/%21dj234r78wl45Gh4D%3Amatrix.org?access_token=123456" -d \
'{
   "actions" : ["dont_notify"]
 }'

To suppress notifications for the user @spambot:matrix.org:

curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/sender/%40spambot%3Amatrix.org?access_token=123456" -d \
'{
   "actions" : ["dont_notify"]
 }'

To always notify for messages that contain the work ‘cake’ and set a specific sound (with a rule_id of SSByZWFsbHkgbGlrZSBjYWtl):

curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/content/SSByZWFsbHkgbGlrZSBjYWtl?access_token=123456" -d \
'{
   "pattern": "cake",
   "actions" : ["notify", {"set_sound":"cakealarm.wav"}]
 }'

To add a rule suppressing notifications for messages starting with ‘cake’ but ending with ‘lie’, superseding the previous rule:

curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/content/U3BvbmdlIGNha2UgaXMgYmVzdA?access_token=123456&before=SSByZWFsbHkgbGlrZSBjYWtl" -d \
'{
   "pattern": "cake*lie",
   "actions" : ["notify"]
 }'

To add a custom sound for notifications messages containing the word ‘beer’ in any rooms with 10 members or fewer (with greater importance than the room, sender and content rules):

curl -X PUT -H "Content-Type: application/json" "https://example.com/_matrix/client/%CLIENT_MAJOR_VERSION%/pushrules/global/override/U2VlIHlvdSBpbiBUaGUgRHVrZQ?access_token=123456" -d \
'{
   "conditions": [
     {"kind": "event_match", "key": "content.body", "pattern": "beer" },
     {"kind": "room_member_count", "is": "<=10"}
   ],
   "actions" : [
     "notify",
     {"set_sound":"beeroclock.wav"}
   ]
 }'

Server behaviour

Push Gateway behaviour

Recommendations for APNS

The exact format for sending APNS notifications is flexible and up to the client app and its' push gateway to agree on. As APNS requires that the sender has a private key owned by the app developer, each app must have its own push gateway. It is recommended that:

  • The APNS token be base64 encoded and used as the pushkey.
  • A different app_id be used for apps on the production and sandbox APS environments.
  • APNS push gateways do not attempt to wait for errors from the APNS gateway before returning and instead to store failures and return ‘rejected’ responses next time that pushkey is used.

Security considerations

Clients specify the Push Gateway URL to use to send event notifications to. This URL should be over HTTPS and never over HTTP.

As push notifications will pass through a Push Provider, message content shouldn’t be sent in the push itself where possible. Instead, Push Gateways should send a “sync” command to instruct the client to get new events from the homeserver directly.

Third party invites

This module adds in support for inviting new members to a room where their Matrix user ID is not known, instead addressing them by a third party identifier such as an email address. There are two flows here; one if a Matrix user ID is known for the third party identifier, and one if not. Either way, the client calls /invite with the details of the third party identifier.

The homeserver asks the identity server whether a Matrix user ID is known for that identifier:

  • If it is, an invite is simply issued for that user.
  • If it is not, the homeserver asks the identity server to record the details of the invitation, and to notify the invitee’s homeserver of this pending invitation if it gets a binding for this identifier in the future. The identity server returns a token and public key to the inviting homeserver.

When the invitee’s homeserver receives the notification of the binding, it should insert an m.room.member event into the room’s graph for that user, with content.membership = invite, as well as a content.third_party_invite property which contains proof that the invitee does indeed own that third party identifier. See the m.room.member schema for more information.

Events

{{m_room_third_party_invite_event}}

Client behaviour

A client asks a server to invite a user by their third party identifier.

POST /_matrix/client/r0/rooms/{roomId}/invite


.. _invite-by-third-party-id-endpoint:

Note that there are two forms of this API, which are documented separately. This version of the API does not require that the inviter know the Matrix identifier of the invitee, and instead relies on third party identifiers. The homeserver uses an identity server to perform the mapping from third party identifier to a Matrix identifier. The other is documented in the joining rooms 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 identity server did know the Matrix user identifier for the third party identifier, the homeserver will append a m.room.member event to the room.

If the identity server does not know a Matrix user identifier for the passed third party identifier, the homeserver will issue an invitation which can be accepted upon providing proof of ownership of the third party identifier. This is achieved by the identity server generating a token, which it gives to the inviting homeserver. The homeserver will add an m.room.third_party_invite event into the graph for the room, containing that token.

When the invitee binds the invited third party identifier to a Matrix user ID, the identity server will give the user a list of pending invitations, each containing:

  • The room ID to which they were invited

  • The token given to the homeserver

  • A signature of the token, signed with the identity server's private key

  • The matrix user ID who invited them to the room

If a token is requested from the identity server, the homeserver will append a m.room.third_party_invite event to the room.

.. joining rooms section: invite-by-user-id-endpoint

Rate-limited: Yes
Requires authentication: Yes

Request

Request parameters

path parameters
Name Type Description
roomId string Required: The room identifier (not alias) to which to invite the user.

Request body

Name Type Description
address string Required: The invitee’s third party identifier.
id_access_token string Required: An access token previously registered with the identity server. Servers can treat this as optional to distinguish between r0.5-compatible clients and this specification version.
id_server string Required: The hostname+port of the identity server which should be used for third party identifier lookups.
medium string Required: The kind of address being passed in the address field, for example email.

Request body example

{
  "address": "cheeky@monkey.com",
  "id_access_token": "abc123_OpaqueString",
  "id_server": "matrix.org",
  "medium": "email"
}

Responses

Status Description
200 The user has been invited to join the room.
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.
429 This request was rate-limited.

Server behaviour

Upon receipt of an /invite, the server is expected to look up the third party identifier with the provided identity server. If the lookup yields a result for a Matrix User ID then the normal invite process can be initiated. This process ends up looking like this:

+---------+                         +-------------+                                    +-----------------+
| Client  |                         | Homeserver  |                                    | IdentityServer  |
+---------+                         +-------------+                                    +-----------------+
    |                                     |                                                    |
    | POST /invite                        |                                                    |
    |------------------------------------>|                                                    |
    |                                     |                                                    |
    |                                     | GET /lookup                                        |
    |                                     |--------------------------------------------------->|
    |                                     |                                                    |
    |                                     |                                     User ID result |
    |                                     |<---------------------------------------------------|
    |                                     |                                                    |
    |                                     | Invite process for the discovered User ID          |
    |                                     |------------------------------------------          |
    |                                     |                                         |          |
    |                                     |<-----------------------------------------          |
    |                                     |                                                    |
    |        Complete the /invite request |                                                    |
    |<------------------------------------|                                                    |
    |                                     |                                                    |

However, if the lookup does not yield a bound User ID, the homeserver must store the invite on the identity server and emit a valid m.room.third_party_invite event to the room. This process ends up looking like this:

+---------+                         +-------------+                                               +-----------------+
| Client  |                         | Homeserver  |                                               | IdentityServer  |
+---------+                         +-------------+                                               +-----------------+
    |                                     |                                                               |
    | POST /invite                        |                                                               |
    |------------------------------------>|                                                               |
    |                                     |                                                               |
    |                                     | GET /lookup                                                   |
    |                                     |-------------------------------------------------------------->|
    |                                     |                                                               |
    |                                     |                                             "no users" result |
    |                                     |<--------------------------------------------------------------|
    |                                     |                                                               |
    |                                     | POST /store-invite                                            |
    |                                     |-------------------------------------------------------------->|
    |                                     |                                                               |
    |                                     |          Information needed for the m.room.third_party_invite |
    |                                     |<--------------------------------------------------------------|
    |                                     |                                                               |
    |                                     | Emit m.room.third_party_invite to the room                    |
    |                                     |-------------------------------------------                    |
    |                                     |                                          |                    |
    |                                     |<------------------------------------------                    |
    |                                     |                                                               |
    |        Complete the /invite request |                                                               |
    |<------------------------------------|                                                               |
    |                                     |                                                               |

All homeservers MUST verify the signature in the event’s content.third_party_invite.signed object.

The third party user will then need to verify their identity, which results in a call from the identity server to the homeserver that bound the third party identifier to a user. The homeserver then exchanges the m.room.third_party_invite event in the room for a complete m.room.member event for membership: invite for the user that has bound the third party identifier.

If a homeserver is joining a room for the first time because of an m.room.third_party_invite, the server which is already participating in the room (which is chosen as per the standard server-server specification) MUST validate that the public key used for signing is still valid, by checking key_validity_url in the above described way.

No other homeservers may reject the joining of the room on the basis of key_validity_url, this is so that all homeservers have a consistent view of the room. They may, however, indicate to their clients that a member’s membership is questionable.

For example, given H1, H2, and H3 as homeservers, UserA as