Add syntax highlighting
This commit is contained in:
Will
parent
6c6bd57ebf
commit
ab64bda76d
11 changed files with 1100 additions and 905 deletions
|
|
@ -71,10 +71,12 @@ 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
|
@ -439,22 +441,24 @@ homeserver returns an HTTP 401 response, with a JSON body, as follows:
|
|||
HTTP/1.1 401 Unauthorized
|
||||
Content-Type: application/json
|
||||
|
||||
```json
|
||||
{
|
||||
"flows": [
|
||||
{
|
||||
"flows": [
|
||||
{
|
||||
"stages": [ "example.type.foo", "example.type.bar" ]
|
||||
},
|
||||
{
|
||||
"stages": [ "example.type.foo", "example.type.baz" ]
|
||||
}
|
||||
],
|
||||
"params": {
|
||||
"example.type.baz": {
|
||||
"example_key": "foobar"
|
||||
}
|
||||
},
|
||||
"session": "xxxxxx"
|
||||
"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:
|
||||
|
||||
|
|
@ -482,15 +486,17 @@ 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"
|
||||
}
|
||||
}
|
||||
```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
|
||||
|
|
@ -501,23 +507,25 @@ client has completed successfully:
|
|||
HTTP/1.1 401 Unauthorized
|
||||
Content-Type: application/json
|
||||
|
||||
```json
|
||||
{
|
||||
"completed": [ "example.type.foo" ],
|
||||
"flows": [
|
||||
{
|
||||
"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"
|
||||
"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
|
||||
|
|
@ -531,25 +539,27 @@ status 401 response as above, with the addition of the standard
|
|||
HTTP/1.1 401 Unauthorized
|
||||
Content-Type: application/json
|
||||
|
||||
```json
|
||||
{
|
||||
"errcode": "M_FORBIDDEN",
|
||||
"error": "Invalid password",
|
||||
"completed": [ "example.type.foo" ],
|
||||
"flows": [
|
||||
{
|
||||
"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"
|
||||
"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:
|
||||
|
|
@ -557,10 +567,12 @@ 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"
|
||||
}
|
||||
```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
|
||||
|
|
@ -641,14 +653,16 @@ 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>"
|
||||
}
|
||||
```
|
||||
{
|
||||
"type": "m.login.password",
|
||||
"identifier": {
|
||||
...
|
||||
},
|
||||
"password": "<password>",
|
||||
"session": "<session ID>"
|
||||
}
|
||||
```
|
||||
|
||||
where the `identifier` property is a user identifier object, as
|
||||
described in [Identifier types](#identifier-types).
|
||||
|
|
@ -656,30 +670,34 @@ described in [Identifier types](#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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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 than 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
|
@ -695,11 +713,13 @@ 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"type": "m.login.recaptcha",
|
||||
"response": "<captcha response>",
|
||||
"session": "<session ID>"
|
||||
}
|
||||
```
|
||||
|
||||
#### Single Sign-On
|
||||
|
||||
|
|
@ -730,18 +750,20 @@ information should be submitted to the homeserver.
|
|||
To use this authentication type, clients should submit an auth dict as
|
||||
follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "m.login.email.identity",
|
||||
"threepidCreds": [
|
||||
{
|
||||
"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>"
|
||||
"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.
|
||||
|
|
@ -762,18 +784,20 @@ information should be submitted to the homeserver.
|
|||
To use this authentication type, clients should submit an auth dict as
|
||||
follows:
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "m.login.msisdn",
|
||||
"threepidCreds": [
|
||||
{
|
||||
"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>"
|
||||
"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.
|
||||
|
|
@ -798,10 +822,12 @@ server can instead send flows `m.login.recaptcha, m.login.dummy` and
|
|||
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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"type": "m.login.dummy",
|
||||
"session": "<session ID>"
|
||||
}
|
||||
```
|
||||
|
||||
##### Fallback
|
||||
|
||||
|
|
@ -820,11 +846,13 @@ 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", "*");
|
||||
}
|
||||
```js
|
||||
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
|
||||
|
|
@ -836,64 +864,67 @@ Once a client receives the notification that the authentication stage
|
|||
has been completed, it should resubmit the request with an auth dict
|
||||
with just the session ID:
|
||||
|
||||
{
|
||||
"session": "<session ID>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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 (e.g. "https://matrix.org")
|
||||
*
|
||||
* apiEndpoint: the API endpoint being used (e.g.
|
||||
* "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
|
||||
*
|
||||
* loginType: the loginType being attempted (e.g. "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;
|
||||
```js
|
||||
/**
|
||||
* Arguments:
|
||||
* homeserverUrl: the base url of the homeserver (e.g. "https://matrix.org")
|
||||
*
|
||||
* apiEndpoint: the API endpoint being used (e.g.
|
||||
* "/_matrix/client/%CLIENT_MAJOR_VERSION%/account/password")
|
||||
*
|
||||
* loginType: the loginType being attempted (e.g. "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;
|
||||
}
|
||||
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);
|
||||
// close the popup
|
||||
popupWindow.close();
|
||||
window.removeEventListener("message", eventListener);
|
||||
|
||||
// repeat the request
|
||||
var requestBody = {
|
||||
auth: {
|
||||
session: sessionID,
|
||||
},
|
||||
};
|
||||
|
||||
request({
|
||||
method:'POST', url:apiEndpoint, json:requestBody,
|
||||
}, onComplete);
|
||||
// repeat the request
|
||||
var requestBody = {
|
||||
auth: {
|
||||
session: sessionID,
|
||||
},
|
||||
};
|
||||
|
||||
window.addEventListener("message", eventListener);
|
||||
request({
|
||||
method:'POST', url:apiEndpoint, json:requestBody,
|
||||
}, onComplete);
|
||||
};
|
||||
|
||||
var url = homeserverUrl +
|
||||
"/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
|
||||
encodeURIComponent(loginType) +
|
||||
"/fallback/web?session=" +
|
||||
encodeURIComponent(sessionID);
|
||||
window.addEventListener("message", eventListener);
|
||||
|
||||
var url = homeserverUrl +
|
||||
"/_matrix/client/%CLIENT_MAJOR_VERSION%/auth/" +
|
||||
encodeURIComponent(loginType) +
|
||||
"/fallback/web?session=" +
|
||||
encodeURIComponent(sessionID);
|
||||
|
||||
popupWindow = window.open(url);
|
||||
}
|
||||
popupWindow = window.open(url);
|
||||
}
|
||||
```
|
||||
|
||||
##### Identifier types
|
||||
|
||||
|
|
@ -920,10 +951,12 @@ 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>"
|
||||
}
|
||||
```json
|
||||
"identifier": {
|
||||
"type": "m.id.user",
|
||||
"user": "<user_id or user localpart>"
|
||||
}
|
||||
```
|
||||
|
||||
#### Third-party ID
|
||||
|
||||
|
|
@ -940,11 +973,13 @@ using the `/account/3pid`\_ API. See the [3PID
|
|||
Types](../appendices.html#pid-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>"
|
||||
}
|
||||
```json
|
||||
"identifier": {
|
||||
"type": "m.id.thirdparty",
|
||||
"medium": "<The medium of the third party identifier>",
|
||||
"address": "<The canonicalised third party address of the user>"
|
||||
}
|
||||
```
|
||||
|
||||
#### Phone number
|
||||
|
||||
|
|
@ -962,11 +997,13 @@ 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>"
|
||||
}
|
||||
```json
|
||||
"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
|
||||
|
|
@ -983,27 +1020,31 @@ API](#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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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 than 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`.
|
||||
|
|
@ -1011,10 +1052,12 @@ 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
|
@ -1166,13 +1209,15 @@ to change their password.
|
|||
|
||||
An example of the capability API's response for this capability is:
|
||||
|
||||
{
|
||||
"capabilities": {
|
||||
"m.change_password": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"capabilities": {
|
||||
"m.change_password": {
|
||||
"enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### `m.room_versions` capability
|
||||
|
||||
|
|
@ -1183,19 +1228,21 @@ 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"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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](../index.html#room-versions) to describe which versions are
|
||||
|
|
@ -1626,36 +1673,48 @@ There are several APIs provided to `GET` events for a room:
|
|||
|
||||
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" }
|
||||
```
|
||||
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" }
|
||||
```
|
||||
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" }
|
||||
```
|
||||
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" }
|
||||
```
|
||||
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 /rooms/!roomid:domain/state/m.room.bgd.color
|
||||
{ "color": "red", "hex": "#ff0000" }
|
||||
```
|
||||
|
||||
{{room\_send\_cs\_http\_api}}
|
||||
|
||||
|
|
@ -1872,19 +1931,23 @@ 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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
|
@ -1938,11 +2001,13 @@ 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)
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
|
|
|||
|
|
@ -99,14 +99,16 @@ with the following properties:
|
|||
|
||||
Example:
|
||||
|
||||
{
|
||||
"key":"06UzBknVHFMwgi7AVloY7ylC+xhOhEX4PkNge14Grl8",
|
||||
"signatures": {
|
||||
"@user:example.com": {
|
||||
"ed25519:EGURVBUNJP": "YbJva03ihSj5mPk+CHMJKUKlCXCPFXjXOK6VqBnN9nA2evksQcTGn6hwQfrgRHIDDXO2le49x7jnWJHMJrJoBQ"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"key":"06UzBknVHFMwgi7AVloY7ylC+xhOhEX4PkNge14Grl8",
|
||||
"signatures": {
|
||||
"@user:example.com": {
|
||||
"ed25519:EGURVBUNJP": "YbJva03ihSj5mPk+CHMJKUKlCXCPFXjXOK6VqBnN9nA2evksQcTGn6hwQfrgRHIDDXO2le49x7jnWJHMJrJoBQ"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
##### Device keys
|
||||
|
||||
|
|
@ -1239,22 +1241,24 @@ keys in [Server-side key backups](#server-side-key-backups) but adds the
|
|||
|
||||
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..."
|
||||
```
|
||||
[
|
||||
{
|
||||
"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
|
||||
|
||||
|
|
@ -1297,19 +1301,21 @@ 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>"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
|
@ -1334,18 +1340,20 @@ 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>"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
|
@ -1418,25 +1426,29 @@ Devices that support Megolm must support Olm, and include
|
|||
|
||||
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>"
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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>"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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.
|
||||
|
|
@ -1554,22 +1566,24 @@ 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
|
||||
}
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
|
|
|
|||
|
|
@ -332,21 +332,23 @@ 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"
|
||||
}
|
||||
}
|
||||
```
|
||||
{
|
||||
...
|
||||
"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
|
||||
|
||||
|
|
|
|||
|
|
@ -18,12 +18,14 @@ Mentions apply only to [m.room.message]() events where the `msgtype` is
|
|||
To make a mention, reference the entity being mentioned in the
|
||||
`formatted_body` using an anchor, like so:
|
||||
|
||||
{
|
||||
"body": "Hello Alice!",
|
||||
"msgtype": "m.text",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"body": "Hello Alice!",
|
||||
"msgtype": "m.text",
|
||||
"format": "org.matrix.custom.html",
|
||||
"formatted_body": "Hello <a href='https://matrix.to/#/@alice:example.org'>Alice</a>!"
|
||||
}
|
||||
```
|
||||
|
||||
#### Client behaviour
|
||||
|
||||
|
|
|
|||
|
|
@ -282,15 +282,17 @@ user. By default this rule is disabled.
|
|||
|
||||
Definition
|
||||
|
||||
{
|
||||
"rule_id": ".m.rule.master",
|
||||
"default": true,
|
||||
"enabled": false,
|
||||
"conditions": [],
|
||||
"actions": [
|
||||
"dont_notify"
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.master",
|
||||
"default": true,
|
||||
"enabled": false,
|
||||
"conditions": [],
|
||||
"actions": [
|
||||
"dont_notify"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
######## `.m.rule.suppress_notices`
|
||||
|
||||
|
|
@ -298,21 +300,23 @@ 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",
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -320,35 +324,37 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -356,21 +362,23 @@ 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"
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -379,26 +387,28 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -408,29 +418,31 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -439,28 +451,30 @@ Matches any message whose content is unencrypted and contains the text
|
|||
|
||||
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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
|
|
@ -471,22 +485,24 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
|
|
@ -496,25 +512,27 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -526,29 +544,31 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -556,29 +576,31 @@ 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"
|
||||
}
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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`
|
||||
|
||||
|
|
@ -586,21 +608,23 @@ 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"
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.message",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "type",
|
||||
"pattern": "m.room.message"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
######## `.m.rule.encrypted`
|
||||
|
||||
|
|
@ -611,21 +635,23 @@ 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"
|
||||
]
|
||||
}
|
||||
```json
|
||||
{
|
||||
"rule_id": ".m.rule.encrypted",
|
||||
"default": true,
|
||||
"enabled": true,
|
||||
"conditions": [
|
||||
{
|
||||
"kind": "event_match",
|
||||
"key": "type",
|
||||
"pattern": "m.room.encrypted"
|
||||
}
|
||||
],
|
||||
"actions": [
|
||||
"notify"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
##### Push Rules: API
|
||||
|
||||
|
|
|
|||
|
|
@ -68,15 +68,17 @@ 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> }
|
||||
},
|
||||
...
|
||||
```
|
||||
{
|
||||
<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`.
|
||||
|
|
|
|||
|
|
@ -114,37 +114,43 @@ 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": {
|
||||
// ...
|
||||
}
|
||||
}
|
||||
```
|
||||
{
|
||||
"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
|
||||
}
|
||||
```
|
||||
{
|
||||
"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
|
||||
}
|
||||
```
|
||||
{
|
||||
"name": "Some other key",
|
||||
"algorithm": "m.secret_storage.v1.aes-hmac-sha2",
|
||||
// ... other properties according to algorithm
|
||||
}
|
||||
```
|
||||
|
||||
###### `m.secret_storage.v1.aes-hmac-sha2`
|
||||
|
||||
|
|
@ -247,24 +253,28 @@ correctly entered the key, clients should:
|
|||
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"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"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"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"encrypted": {
|
||||
"key_id": {
|
||||
"iv": "16+bytes+base64",
|
||||
"ciphertext": "base64+encoded+encrypted+data",
|
||||
"mac": "base64+encoded+mac"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
###### Key representation
|
||||
|
||||
|
|
@ -339,15 +349,17 @@ in the `iterations` parameter.
|
|||
|
||||
Example:
|
||||
|
||||
{
|
||||
"passphrase": {
|
||||
"algorithm": "m.pbkdf2",
|
||||
"salt": "MmMsAlty",
|
||||
"iterations": 100000,
|
||||
"bits": 256
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
{
|
||||
"passphrase": {
|
||||
"algorithm": "m.pbkdf2",
|
||||
"salt": "MmMsAlty",
|
||||
"iterations": 100000,
|
||||
"bits": 256
|
||||
},
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
#### Sharing
|
||||
|
||||
|
|
@ -407,12 +419,14 @@ previous request. It is sent as an unencrypted to-device event.
|
|||
|
||||
Example:
|
||||
|
||||
{
|
||||
"name": "org.example.some.secret",
|
||||
"action": "request",
|
||||
"requesting_device_id": "ABCDEFG",
|
||||
"request_id": "randomly_generated_id_9573"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"name": "org.example.some.secret",
|
||||
"action": "request",
|
||||
"requesting_device_id": "ABCDEFG",
|
||||
"request_id": "randomly_generated_id_9573"
|
||||
}
|
||||
```
|
||||
|
||||
###### `m.secret.send`
|
||||
|
||||
|
|
@ -444,7 +458,9 @@ an `m.secret.request` event. It must be encrypted as an
|
|||
|
||||
Example:
|
||||
|
||||
{
|
||||
"request_id": "randomly_generated_id_9573",
|
||||
"secret": "ThisIsASecretDon'tTellAnyone"
|
||||
}
|
||||
```json
|
||||
{
|
||||
"request_id": "randomly_generated_id_9573",
|
||||
"secret": "ThisIsASecretDon'tTellAnyone"
|
||||
}
|
||||
```
|
||||
|
|
|
|||
|
|
@ -125,19 +125,21 @@ This module adds the following properties to the \_ response:
|
|||
|
||||
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"]
|
||||
}
|
||||
}
|
||||
]
|
||||
```json
|
||||
{
|
||||
"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"]
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue