| 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. |
| StrippedState Key | Type | Description |
|---|---|---|
| content | EventContent | Required. The content for the event. |
| state_key | string | Required. The state_key for the event. |
| type | string | Required. The type for the event. |
| sender | string | Required. The sender for the event. |
Examples:
{ "content": { "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid", "membership": "join" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "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" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "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" } } }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "@alice:example.org", "type": "m.room.member", "unsigned": { "age": 1234 } }
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.
| Content Key | Type | Description |
|---|---|---|
| ban | integer | The level required to ban a user. Defaults to 50 if unspecified. |
| events | {string: integer} | 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. |
| 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 | {string: integer} | 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 | Notifications | The power level requirements for specific notification types. This is a mapping from key to power level for that notifications key. |
| Notifications Key | Type | Description |
|---|---|---|
| room | integer | The level required to trigger an @room notification. Defaults to 50 if unspecified. |
Example:
{ "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "invite": 50, "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":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "state_key": "", "type": "m.room.power_levels", "unsigned": { "age": 1234 } }
Message Event
Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the redacts event level key.
| Content Key | Type | Description |
|---|---|---|
| reason | string | The reason for the redaction, if any. |
Example:
{ "content": { "reason": "Spamming" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "redacts": "$fukweghifu23:localhost", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "type": "m.room.redaction", "unsigned": { "age": 1234 } }
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.
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 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.
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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| 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 for more information. |
| since | string | A point in time to continue a sync from. |
| full_state | boolean | Controls whether to include the full state for all rooms the user is a member of. If this is set to true, then all state events will be returned, even if since is non-empty. The timeline will still be limited by the since parameter. In this case, the timeout parameter will be ignored and the query will return immediately, possibly with an empty timeline. If false, and since is non-empty, only state which has changed since the point indicated by since will be returned. By default, this is false. |
| set_presence | enum | Controls whether the client is automatically marked as online by polling this API. If this parameter is omitted then the client is automatically marked as online when it uses this API. Otherwise if the parameter is set to "offline" then the client is not marked as being online when it uses this API. When set to "unavailable", the client is marked as being idle. One of: ["offline", "online", "unavailable"] |
| 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. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| next_batch | string | Required. The batch token to supply in the since param of the next /sync request. |
| rooms | Rooms | Updates to rooms. |
| presence | Presence | The updates to the presence status of other users. |
| account_data | Account Data | The global private data created by this user. |
| to_device | ToDevice | Information on the send-to-device messages for the client device, as defined in Send-to-Device messaging. |
| device_lists | DeviceLists | Information on end-to-end device updates, as specified in End-to-end encryption. |
| device_one_time_keys_count | {string: integer} | Information on end-to-end encryption keys, as specified in End-to-end encryption. |
| Parameter | Type | Description |
|---|---|---|
| join | {string: Joined Room} | The rooms that the user has joined, mapped as room ID to room information. |
| invite | {string: Invited Room} | The rooms that the user has been invited to, mapped as room ID to room information. |
| leave | {string: Left Room} | The rooms that the user has left or been banned from, mapped as room ID to room information. |
| Parameter | Type | Description |
|---|---|---|
| summary | RoomSummary | Information about the room which clients may need to correctly render it to users. |
| 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. |
| timeline | Timeline | The timeline of messages and state changes in the room. |
| ephemeral | Ephemeral | The ephemeral events in the room that aren't recorded in the timeline or state of the room. e.g. typing. |
| account_data | Account Data | The private data that this user has attached to this room. |
| unread_notifications | Unread Notification Counts | Counts of unread notifications for this room. See the Receiving notifications section for more information on how these are calculated. |
| Parameter | 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.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. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| events | [Event] | List of events. |
| Parameter | Type | Description |
|---|---|---|
| highlight_count | integer | The number of unread notifications for this room with the highlight flag set |
| notification_count | integer | The total number of unread notifications for this room |
| Parameter | Type | Description |
|---|---|---|
| invite_state | InviteState | The state of a room that the user has been invited to. These state events may only have the sender, type, state_key and content keys present. These events do not replace any state that the client already has for the room, for example if the client has archived the room. Instead the client should keep two separate copies of the state: the one from the invite_state and one from the archived state. If the client joins the room then the current state will be given as a delta against the archived state not the invite_state. |
| Parameter | Type | Description |
|---|---|---|
| events | [StrippedState] | The StrippedState events that form the invite state. |
| Parameter | Type | Description |
|---|---|---|
| content | EventContent | Required. The content for the event. |
| state_key | string | Required. The state_key for the event. |
| type | string | Required. The type for the event. |
| sender | string | Required. The sender for the event. |
| Parameter | Type | Description |
|---|---|---|
| state | State | The state updates for the room up to the start of the timeline. |
| timeline | Timeline | The timeline of messages and state changes in the room up to the point when the user left. |
| account_data | Account Data | The private data that this user has attached to this room. |
| Parameter | Type | Description |
|---|---|---|
| events | [State Event] | List of events. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| events | [Room Event] | 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
| Parameter | Type | Description |
|---|---|---|
| events | [Event] | List of events. |
| Parameter | Type | Description |
|---|---|---|
| events | [Event] | List of events. |
| Parameter | 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' |
Example request:
GET /_matrix/client/r0/sync?filter=66696p746572&since=s72594_4483_1934&full_state=false&set_presence=offline&timeout=30000 HTTP/1.1
Response:
Status code 200:
The initial snapshot or delta for the client to use to update their state.
Example
{ "next_batch": "s72595_4483_1934", "presence": { "events": [ { "content": { "avatar_url": "mxc://localhost:wefuiwegh8742w", "last_active_ago": 2478593, "presence": "online", "currently_active": false, "status_msg": "Making cupcakes" }, "type": "m.presence", "sender": "@example:localhost" } ] }, "account_data": { "events": [ { "type": "org.example.custom.config", "content": { "custom_config_key": "custom_config_value" } } ] }, "rooms": { "join": { "!726s6s6q:example.com": { "summary": { "m.heroes": [ "@alice:example.com", "@bob:example.com" ], "m.joined_member_count": 2, "m.invited_member_count": 0 }, "state": { "events": [ { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!726s6s6q:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" } ] }, "timeline": { "events": [ { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!726s6s6q:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" }, { "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!726s6s6q:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } } ], "limited": true, "prev_batch": "t34-23535_0_0" }, "ephemeral": { "events": [ { "content": { "user_ids": [ "@alice:matrix.org", "@bob:example.com" ] }, "type": "m.typing", "room_id": "!jEsUZKDJdhlrceRyVU:example.org" } ] }, "account_data": { "events": [ { "content": { "tags": { "u.work": { "order": 0.9 } } }, "type": "m.tag" }, { "type": "org.example.custom.room.config", "content": { "custom_config_key": "custom_config_value" } } ] } } }, "invite": { "!696r7674:example.com": { "invite_state": { "events": [ { "sender": "@alice:example.com", "type": "m.room.name", "state_key": "", "content": { "name": "My Room Name" } }, { "sender": "@alice:example.com", "type": "m.room.member", "state_key": "@bob:example.com", "content": { "membership": "invite" } } ] } } }, "leave": {} } }
Warning
This API is deprecated and will be removed from a future release.
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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| from | string | The token to stream from. This token is either from a previous request to this API or from the initial sync API. |
| timeout | integer | The maximum time in milliseconds to wait for an event. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| start | string | A token which correlates to the first value in chunk. This is usually the same token supplied to from=. |
| end | string | A token which correlates to the last value in chunk. This token should be used in the next request to /events. |
| chunk | [Event] | An array of events. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
Example request:
GET /_matrix/client/r0/events?from=s3456_9_0&timeout=35000 HTTP/1.1
Responses:
Status code 200:
The events received, which may be none.
Example
{ "start": "s3456_9_0", "end": "s3457_9_0", "chunk": [ { "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } } ] }
Status code 400:
Bad pagination from parameter.
Warning
This API is deprecated and will be removed from a future release.
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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| limit | integer | The maximum number of messages to return for each room. |
| archived | boolean | Whether to include rooms that the user has left. If false then only rooms that the user has been invited to or has joined are included. If set to true then rooms that the user has left are included as well. By default this is false. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| end | string | 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. |
| account_data | [Event] | The global private data created by this user. |
| Parameter | Type | Description |
|---|---|---|
| room_id | string | Required. The ID of this room. |
| membership | enum | Required. The user's membership state in this room. One of: ["invite", "join", "leave", "ban"] |
| invite | InviteEvent | The invite event if membership is invite |
| messages | PaginationChunk | The pagination chunk for 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"] |
| account_data | [Event] | The private data that this user has attached to this room. |
| Parameter | Type | Description |
|---|---|---|
| content | EventContent | Required. |
| type | enum | Required. Must be 'm.room.member'. |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| avatar_url | string | The avatar URL for this user, if any. This is added by the homeserver. |
| displayname | string or null | The display name for this user, if any. This is added by the homeserver. |
| membership | enum | Required. The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"] |
| is_direct | boolean | Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging. |
| third_party_invite | Invite | |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| Parameter | 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. |
| Parameter | 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. |
| Parameter | Type | Description |
|---|---|---|
| content | EventContent | Required. The content for the event. |
| state_key | string | Required. The state_key for the event. |
| type | string | Required. The type for the event. |
| sender | string | Required. The sender for the event. |
| Parameter | Type | Description |
|---|---|---|
| start | string | Required. A token which correlates to the first value in chunk. Used for pagination. |
| end | string | Required. A token which correlates to the last value in chunk. Used for pagination. |
| 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
| Parameter | 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' |
Example request:
GET /_matrix/client/r0/initialSync?limit=2&archived=true HTTP/1.1
Responses:
Status code 200:
The user's current state.
Example
{ "end": "s3456_9_0", "presence": [ { "content": { "avatar_url": "mxc://localhost:wefuiwegh8742w", "last_active_ago": 2478593, "presence": "online", "currently_active": false, "status_msg": "Making cupcakes" }, "type": "m.presence", "sender": "@example:localhost" } ], "account_data": [ { "type": "org.example.custom.config", "content": { "custom_config_key": "custom_config_value" } } ], "rooms": [ { "membership": "join", "messages": { "chunk": [ { "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } }, { "content": { "body": "Gangnam Style", "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442", "info": { "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", "thumbnail_info": { "mimetype": "image/jpeg", "size": 46144, "w": 300, "h": 300 }, "w": 480, "h": 320, "duration": 2140786, "size": 1563685, "mimetype": "video/mp4" }, "msgtype": "m.video" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "state": [ { "content": { "join_rule": "public" }, "type": "m.room.join_rules", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" }, { "content": { "creator": "@example:example.org", "room_version": "1", "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" } }, "type": "m.room.create", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "invite": 50, "kick": 50, "redact": 50, "state_default": 50, "users": { "@example:localhost": 100 }, "users_default": 0, "notifications": { "room": 20 } }, "type": "m.room.power_levels", "event_id": "$143273582443PhrSn:example.org", "room_id": "!TmaZBKYIFrIPVGoUYp:localhost", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" } ], "visibility": "private", "account_data": [ { "type": "m.tag", "content": { "tags": { "work": { "order": 1 } } } }, { "type": "org.example.custom.room.config", "content": { "custom_config_key": "custom_config_value" } } ] } ] }
Status code 404:
There is no avatar URL for this user or this user does not exist.
Warning
This API is deprecated and will be removed from a future release.
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| eventId | string | Required. The event ID to get. |
Response format:
| Parameter | 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' |
Example request:
GET /_matrix/client/r0/events/%24asfDuShaf7Gafaw%3Amatrix.org HTTP/1.1
Responses:
Status code 200:
The full event.
Example
{ "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } }
Status code 404:
The event was not found or you do not have permission to read this event.
There are several APIs provided to GET events for a room:
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The ID of the room the event is in. |
| eventId | string | Required. The event ID to get. |
Response format:
| Parameter | 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' |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Amatrix.org/event/%24asfDuShaf7Gafaw%3Amatrix.org HTTP/1.1
Responses:
Status code 200:
The full event.
Example
{ "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:matrix.org", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } }
Status code 404:
The event was not found or you do not have permission to read this event.
Example
{ "errcode": "M_NOT_FOUND", "error": "Event not found." }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to look up the state in. |
| eventType | string | Required. The type of state to look up. |
| stateKey | string | Required. The key of the state to look up. Defaults to an empty string. When an empty string, the trailing slash on this endpoint is optional. |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.name/ HTTP/1.1
Responses:
Status code 200:
The content of the state event.
Example
{ "name": "Example room name" }
Status code 403:
You aren't a member of the room and weren't previously a member of the room.
Status code 404:
The room has no state with the given type or key.
Get the state events for the current state of a room.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to look up the state for. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| <body> | [StateEvent] | If the user is a member of the room this will be the current state of the room as a list of events. If the user has left the room then this will be the state of the room when they left as a list of events. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state HTTP/1.1
Responses:
Status code 200:
The current state of the room
Example
[ { "content": { "join_rule": "public" }, "type": "m.room.join_rules", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" }, { "content": { "creator": "@example:example.org", "room_version": "1", "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" } }, "type": "m.room.create", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "invite": 50, "kick": 50, "redact": 50, "state_default": 50, "users": { "@example:localhost": 100 }, "users_default": 0, "notifications": { "room": 20 } }, "type": "m.room.power_levels", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" } ]
Status code 403:
You aren't a member of the room and weren't previously a member of the room.
Get the list of members for this room.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to get the member events for. |
| query parameters | ||
| 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"] |
Response format:
| Parameter | Type | Description |
|---|---|---|
| chunk | [MemberEvent] |
| Parameter | Type | Description |
|---|---|---|
| content | EventContent | Required. |
| type | enum | Required. Must be 'm.room.member'. |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| avatar_url | string | The avatar URL for this user, if any. This is added by the homeserver. |
| displayname | string or null | The display name for this user, if any. This is added by the homeserver. |
| membership | enum | Required. The membership state of the user. One of: ["invite", "join", "knock", "leave", "ban"] |
| is_direct | boolean | Flag indicating if the room containing this event was created with the intention of being a direct chat. See Direct Messaging. |
| third_party_invite | Invite | |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| Parameter | 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. |
| Parameter | 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. |
| Parameter | Type | Description |
|---|---|---|
| content | EventContent | Required. The content for the event. |
| state_key | string | Required. The state_key for the event. |
| type | string | Required. The type for the event. |
| sender | string | Required. The sender for the event. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/members?at=YWxsCgpOb25lLDM1ODcwOA&membership=join¬_membership=leave HTTP/1.1
Responses:
Status code 200:
A list of members of the room. If you are joined to the room then this will be the current members of the room. If you have left the room then this will be the members of the room when you left.
Example
{ "chunk": [ { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" } ] }
Status code 403:
You aren't a member of the room and weren't previously a member of the room.
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to get the members of. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| joined | {string: RoomMember} | A map from user ID to a RoomMember object. |
| Parameter | Type | Description |
|---|---|---|
| display_name | string | The display name of the user this object is representing. |
| avatar_url | string | The mxc avatar url of the user this object is representing. |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/joined_members HTTP/1.1
Responses:
Status code 200:
A map of MXID to room member objects.
Example
{ "joined": { "@bar:example.com": { "display_name": "Bar", "avatar_url": "mxc://riot.ovh/printErCATzZijQsSDWorRaK" } } }
Status code 403:
You aren't a member of the room.
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 for more information.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to get events from. |
| query parameters | ||
| from | string | Required. The token to start returning events from. This token can be obtained from 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. |
| 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. |
| dir | enum | Required. The direction to return events from. One of: ["b", "f"] |
| limit | integer | The maximum number of events to return. Default: 10. |
| filter | string | A JSON RoomEventFilter to filter returned events with. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| start | string | The token the pagination starts from. If dir=b this will be the token supplied in from. |
| end | string | The token the pagination ends at. If dir=b this token should be used again to request even earlier events. |
| 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. |
| state | [RoomStateEvent] | 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/messages?from=s345_678_333&dir=b&limit=3&filter=%7B%22contains_url%22%3Atrue%7D HTTP/1.1
Responses:
Status code 200:
A list of messages with a new token to request more.
Example
{ "start": "t47429-4392820_219380_26003_2265", "end": "t47409-4357353_219380_26003_2265", "chunk": [ { "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } }, { "content": { "name": "The room name" }, "type": "m.room.name", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "body": "Gangnam Style", "url": "mxc://example.org/a526eYUSFFxlgbQYZmo442", "info": { "thumbnail_url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe", "thumbnail_info": { "mimetype": "image/jpeg", "size": 46144, "w": 300, "h": 300 }, "w": 480, "h": 320, "duration": 2140786, "size": 1563685, "mimetype": "video/mp4" }, "msgtype": "m.video" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } } ] }
Status code 403:
You aren't a member of the room.
Warning
This API is deprecated and will be removed from a future release.
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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to get the data. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| room_id | string | Required. The ID of 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. |
| 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"] |
| account_data | [Event] | The private data that this user has attached to this room. |
| Parameter | Type | Description |
|---|---|---|
| start | string | Required. A token which correlates to the first value in chunk. Used for pagination. |
| end | string | Required. A token which correlates to the last value in chunk. Used for pagination. |
| 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| Parameter | 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' |
| event_id | string | Required. The globally unique event identifier. |
| sender | string | Required. Contains the fully-qualified ID of the user who sent this event. |
| origin_server_ts | integer | Required. Timestamp in milliseconds on originating homeserver when this event was sent. |
| unsigned | UnsignedData | Contains optional extra information about the event. |
| 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. |
| prev_content | EventContent | Optional. The previous content for this event. If there is no previous content, this key will be missing. |
| 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. |
| Parameter | 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 | Optional. The event that redacted this event, if any. |
| transaction_id | string | The client-supplied transaction ID, if the client being given the event is the same one which sent it. |
| Parameter | 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' |
Example request:
GET /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/initialSync HTTP/1.1
Responses:
Status code 200:
The current state of the room
Example
{ "membership": "join", "messages": { "chunk": [ { "content": { "body": "This is an example text message", "msgtype": "m.text", "format": "org.matrix.custom.html", "formatted_body": "<b>This is an example text message</b>" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } }, { "content": { "body": "something-important.doc", "filename": "something-important.doc", "info": { "mimetype": "application/msword", "size": 46144 }, "msgtype": "m.file", "url": "mxc://example.org/FHyPlCeYUSFFxlgbQYZmoEoe" }, "type": "m.room.message", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 } } ], "end": "s3456_9_0", "start": "t44-3453_9_0" }, "room_id": "!636q39766251:example.com", "state": [ { "content": { "join_rule": "public" }, "type": "m.room.join_rules", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "membership": "join", "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }, "type": "m.room.member", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "@alice:example.org" }, { "content": { "creator": "@example:example.org", "room_version": "1", "m.federate": true, "predecessor": { "event_id": "$something:example.org", "room_id": "!oldroom:example.org" } }, "type": "m.room.create", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" }, { "content": { "ban": 50, "events": { "m.room.name": 100, "m.room.power_levels": 100 }, "events_default": 0, "invite": 50, "kick": 50, "redact": 50, "state_default": 50, "users": { "@example:localhost": 100 }, "users_default": 0, "notifications": { "room": 20 } }, "type": "m.room.power_levels", "event_id": "$143273582443PhrSn:example.org", "room_id": "!636q39766251:example.com", "sender": "@example:example.org", "origin_server_ts":<PHONE_NUMBER>653, "unsigned": { "age": 1234 }, "state_key": "" } ], "visibility": "private", "account_data": [ { "type": "m.tag", "content": { "tags": { "work": { "order": "1" } } } } ] }
Status code 403:
You aren't a member of the room and weren't previously a member of the room.
State events can be sent using this endpoint. These events will be overwritten if <room id>, <event type> and <state key> 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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to set the state in |
| eventType | string | Required. The type of event to send. |
| stateKey | string | Required. The state_key for the state to send. Defaults to the empty string. When an empty string, the trailing slash on this endpoint is optional. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| event_id | string | A unique identifier for the event. |
Example request:
PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/state/m.room.member/%40alice%3Aexample.com HTTP/1.1 Content-Type: application/json { "membership": "join", "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF", "displayname": "Alice Margatroid" }
Responses:
Status code 200:
An ID for the sent event.
Example
{ "event_id": "$YUwRidLecu:example.com" }
Status code 403:
The sender doesn't have permission to send the event into the room.
Example
{ "errcode": "M_FORBIDDEN", "error": "You do not have permission to send the event." }
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" }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room to send the event to. |
| eventType | string | Required. The type of event to send. |
| txnId | string | Required. The transaction ID for this event. Clients should generate an ID unique across requests with the same access token; it will be used by the server to ensure idempotency of requests. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| event_id | string | A unique identifier for the event. |
Example request:
PUT /_matrix/client/r0/rooms/%21636q39766251%3Aexample.com/send/m.room.message/35 HTTP/1.1 Content-Type: application/json { "msgtype": "m.text", "body": "hello" }
Response:
Status code 200:
An ID for the sent event.
Example
{ "event_id": "$YUwRidLecu:example.com" }
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.
Upon receipt of a redaction event, the server should strip off any keys not in the following list:
The content object should also be stripped of all keys, unless it is one of one of the following event types:
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.
Message Event
Events can be redacted by either room or server admins. Redacting an event means that all keys not required by the protocol are stripped off, allowing admins to remove offensive or illegal content that may have been attached to any event. This cannot be undone, allowing server owners to physically delete the offending data. There is also a concept of a moderator hiding a message event, which can be undone, but cannot be applied to state events. The event that has been redacted is specified in the redacts event level key.
| Content Key | Type | Description |
|---|---|---|
| reason | string | The reason for the redaction, if any. |
Example:
{ "content": { "reason": "Spamming" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "redacts": "$fukweghifu23:localhost", "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "type": "m.room.redaction", "unsigned": { "age": 1234 } }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room from which to redact the event. |
| eventId | string | Required. The ID of the event to redact |
| 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. |
| JSON body parameters | ||
| reason | string | The reason for the event being redacted. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| event_id | string | A unique identifier for the event. |
Example request:
PUT /_matrix/client/r0/rooms/%21637q39766251%3Aexample.com/redact/bai2b1i9%3Amatrix.org/37 HTTP/1.1 Content-Type: application/json { "reason": "Indecent material" }
Response:
Status code 200:
An ID for the redaction event.
Example
{ "event_id": "$YUwQidLecu:example.com" }
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:
See Room Events for more information on these events. To create a room, a client has to use the following API.
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:
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| 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"] |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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"] |
| 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. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| id_server | string | Required. The hostname+port of the identity server which should be used for third party identifier lookups. |
| 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. |
| medium | string | Required. The kind of address being passed in the address field, for example email. |
| address | string | Required. The invitee's third party identifier. |
| Parameter | Type | Description |
|---|---|---|
| type | string | Required. The type of event to send. |
| state_key | string | The state_key of the state event. Defaults to an empty string. |
| content | object | Required. The content of the event. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| room_id | string | Required. The created room's ID. |
Example request:
POST /_matrix/client/r0/createRoom HTTP/1.1 Content-Type: application/json { "preset": "public_chat", "room_alias_name": "thepub", "name": "The Grand Duke Pub", "topic": "All about happy hour", "creation_content": { "m.federate": false } }
Responses:
Status code 200:
Information about the newly created room.
Example
{ "room_id": "!sefiuhWgwghwWgh:example.com" }
Status code 400:
The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:
Example
{ "errcode": "M_UNKNOWN", "error": "An unknown error occurred" }
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 store a partial list of room aliases via the m.room.aliases state event. This alias list is partial because it cannot guarantee that the alias list is in any way accurate or up-to-date, as room aliases can point to different room IDs over time. Crucially, the aliases in this event are purely informational and SHOULD NOT be treated 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.
Create a new mapping from room alias to room ID.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomAlias | string | Required. The room alias to set. |
| JSON body parameters | ||
| room_id | string | Required. The room ID to set. |
Example request:
PUT /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1 Content-Type: application/json { "room_id": "!abnjk1jdasj98:capuchins.com" }
Responses:
Status code 200:
The mapping was created.
Example
{}
Status code 409:
A room alias with that name already exists.
Example
{ "errcode": "M_UNKNOWN", "error": "Room alias #monkeys:matrix.org already exists." }
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 auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomAlias | string | Required. The room alias. |
Response format:
| Parameter | 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. |
Example request:
GET /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1
Responses:
Status code 200:
The room ID and other information for this alias.
Example
{ "room_id": "!abnjk1jdasj98:capuchins.com", "servers": [ "capuchins.com", "matrix.org", "another.com" ] }
Status code 404:
There is no mapped room ID for this room alias.
Example
{ "errcode": "M_NOT_FOUND", "error": "Room alias #monkeys:matrix.org not found." }
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.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomAlias | string | Required. The room alias to remove. |
Example request:
DELETE /_matrix/client/r0/directory/room/%23monkeys%3Amatrix.org HTTP/1.1
Responses:
Status code 200:
The mapping was deleted.
Example
{}
Status code 404:
There is no mapped room ID for this room alias.
Example
{ "errcode": "M_NOT_FOUND", "error": "Room alias #monkeys:example.org not found." }
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
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:
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:
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
This API returns a list of the user's current rooms.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
No parameters
Response format:
| Parameter | Type | Description |
|---|---|---|
| joined_rooms | [string] | Required. The ID of each room in which the user has joined membership. |
Example request:
GET /_matrix/client/r0/joined_rooms HTTP/1.1
Response:
Status code 200:
A list of the rooms the user is in.
Example
{ "joined_rooms": [ "!foo:example.com" ] }
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.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier (not alias) to which to invite the user. |
| JSON body parameters | ||
| user_id | string | Required. The fully qualified user ID of the invitee. |
Example request:
POST /_matrix/client/r0/rooms/%21d41d8cd%3Amatrix.org/invite HTTP/1.1 Content-Type: application/json { "user_id": "@cheeky_monkey:matrix.org" }
Responses:
Status code 200:
The user has been invited to join the room.
Example
{}
Status code 400:
The request is invalid. A meaningful errcode and description error text will be returned. Example reasons for rejection include:
Example
{ "errcode": "M_UNKNOWN", "error": "An unknown error occurred" }
Status code 403:
You do not have permission to invite the user to the room. A meaningful errcode and description error text will be returned. Example reasons for rejections are:
Example
{ "errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room" }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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.
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.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier (not alias) to join. |
| JSON body parameters | ||
| third_party_signed | Third Party Signed | A signature of an m.third_party_invite token to prove that this user owns a third party identity which has been invited to the room. |
| Parameter | Type | Description |
|---|---|---|
| sender | string | Required. The Matrix ID of the user who issued the invite. |
| mxid | string | Required. The Matrix ID of the invitee. |
| token | string | Required. The state key of the m.third_party_invite event. |
| signatures | Signatures | Required. A signatures object containing a signature of the entire signed object. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| room_id | string | Required. The joined room ID. |
Example request:
POST /_matrix/client/r0/rooms/%21d41d8cd%3Amatrix.org/join HTTP/1.1 Content-Type: application/json { "third_party_signed": { "sender": "@alice:example.org", "mxid": "@bob:example.org", "token": "random8nonce", "signatures": { "example.org": { "ed25519:0": "some9signature" } } } }
Responses:
Status code 200:
The room has been joined.
The joined room ID must be returned in the room_id field.
Example
{ "room_id": "!d41d8cd:matrix.org" }
Status code 403:
You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are:
Example
{ "errcode": "M_FORBIDDEN", "error": "You are not invited to this room." }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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.
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.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomIdOrAlias | string | Required. The room identifier or alias to join. |
| query parameters | ||
| server_name | [string] | The servers to attempt to join the room through. One of the servers must be participating in the room. |
| JSON body parameters | ||
| third_party_signed | Third Party Signed | A signature of an m.third_party_invite token to prove that this user owns a third party identity which has been invited to the room. |
| Parameter | Type | Description |
|---|---|---|
| sender | string | Required. The Matrix ID of the user who issued the invite. |
| mxid | string | Required. The Matrix ID of the invitee. |
| token | string | Required. The state key of the m.third_party_invite event. |
| signatures | Signatures | Required. A signatures object containing a signature of the entire signed object. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| room_id | string | Required. The joined room ID. |
Example request:
POST /_matrix/client/r0/join/%23monkeys%3Amatrix.org?server_name=matrix.org&server_name=elsewhere.ca HTTP/1.1 Content-Type: application/json { "third_party_signed": { "sender": "@alice:example.org", "mxid": "@bob:example.org", "token": "random8nonce", "signatures": { "example.org": { "ed25519:0": "some9signature" } } } }
Responses:
Status code 200:
The room has been joined.
The joined room ID must be returned in the room_id field.
Example
{ "room_id": "!d41d8cd:matrix.org" }
Status code 403:
You do not have permission to join the room. A meaningful errcode and description error text will be returned. Example reasons for rejection are:
Example
{ "errcode": "M_FORBIDDEN", "error": "You are not invited to this room." }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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".
This API stops a user participating in a particular room.
If the user was already in the room, they will no longer be able to see new events in the room. If the room requires an invite to join, they will need to be re-invited before they can re-join.
If the user was invited to the room, but had not joined, this call serves to reject the invite.
The user will still be allowed to retrieve history from the room which they were previously allowed to see.
| Rate-limited: | Yes. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier to leave. |
Example request:
POST /_matrix/client/r0/rooms/%21nkl290a%3Amatrix.org/leave HTTP/1.1
Responses:
Status code 200:
The room has been left.
Example
{}
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier to forget. |
Example request:
POST /_matrix/client/r0/rooms/%21au1ba7o%3Amatrix.org/forget HTTP/1.1
Responses:
Status code 200:
The room has been forgotten.
Example
{}
Status code 400:
The user has not left the room
Example
{ "errcode": "M_UNKNOWN", "error": "User @example:matrix.org is in room !au1ba7o:matrix.org" }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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/<room id>/state/m.room.member/<user id>.
| Rate-limited: | No. |
|---|---|
| Requires auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier (not alias) from which the user should be kicked. |
| JSON body parameters | ||
| user_id | string | Required. The fully qualified user ID of the user being kicked. |
| 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. |
Example request:
POST /_matrix/client/r0/rooms/%21e42d8c%3Amatrix.org/kick HTTP/1.1 Content-Type: application/json { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" }
Responses:
Status code 200:
The user has been kicked from the room.
Example
{}
Status code 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:
Example
{ "errcode": "M_FORBIDDEN", "error": "You do not have a high enough power level to kick from this 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.
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier (not alias) from which the user should be banned. |
| JSON body parameters | ||
| user_id | string | Required. The fully qualified user ID of the user being banned. |
| 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. |
Example request:
POST /_matrix/client/r0/rooms/%21e42d8c%3Amatrix.org/ban HTTP/1.1 Content-Type: application/json { "reason": "Telling unfunny jokes", "user_id": "@cheeky_monkey:matrix.org" }
Responses:
Status code 200:
The user has been kicked and banned from the room.
Example
{}
Status code 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:
Example
{ "errcode": "M_FORBIDDEN", "error": "You do not have a high enough power level to ban from this room." }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room identifier (not alias) from which the user should be unbanned. |
| JSON body parameters | ||
| user_id | string | Required. The fully qualified user ID of the user being unbanned. |
Example request:
POST /_matrix/client/r0/rooms/%21e42d8c%3Amatrix.org/unban HTTP/1.1 Content-Type: application/json { "user_id": "@cheeky_monkey:matrix.org" }
Responses:
Status code 200:
The user has been unbanned from the room.
Example
{}
Status code 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:
Example
{ "errcode": "M_FORBIDDEN", "error": "You do not have a high enough power level to unban from this room." }
Gets the visibility of a given room on the server's public room directory.
| Rate-limited: | No. |
|---|---|
| Requires auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room ID. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| visibility | enum | The visibility of the room in the directory. One of: ["private", "public"] |
Example request:
GET /_matrix/client/r0/directory/list/room/%21curbf%3Amatrix.org HTTP/1.1
Responses:
Status code 200:
The visibility of the room in the directory
Example
{ "visibility": "public" }
Status code 404:
The room is not known to the server
Example
{ "errcode": "M_NOT_FOUND", "error": "Room not found" }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| roomId | string | Required. The room ID. |
| JSON body parameters | ||
| visibility | enum | The new visibility setting for the room. Defaults to 'public'. One of: ["private", "public"] |
Example request:
PUT /_matrix/client/r0/directory/list/room/%21curbf%3Amatrix.org HTTP/1.1 Content-Type: application/json { "visibility": "public" }
Responses:
Status code 200:
The visibility was updated, or no change was needed.
Example
{}
Status code 404:
The room is not known to the server
Example
{ "errcode": "M_NOT_FOUND", "error": "Room not found" }
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 auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| 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. |
| server | string | The server to fetch the public room lists from. Defaults to the local server. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| chunk | [PublicRoomsChunk] | 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. |
| Parameter | Type | Description |
|---|---|---|
| aliases | [string] | Aliases of the room. May be empty. |
| canonical_alias | string | The canonical alias of the room, if any. |
| 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. |
| 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. |
| avatar_url | string | The URL for the room's avatar, if one is set. |
Example request:
GET /_matrix/client/r0/publicRooms HTTP/1.1
Response:
Status code 200:
A list of the rooms on the server.
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 }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| query parameters | ||
| server | string | The server to fetch the public room lists from. Defaults to the local server. |
| JSON body parameters | ||
| 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. |
| 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. |
| 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. |
| Parameter | Type | Description |
|---|---|---|
| generic_search_term | string | A string to search for in the room metadata, e.g. name, topic, canonical alias etc. (Optional). |
Response format:
| Parameter | Type | Description |
|---|---|---|
| chunk | [PublicRoomsChunk] | 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. |
| Parameter | Type | Description |
|---|---|---|
| aliases | [string] | Aliases of the room. May be empty. |
| canonical_alias | string | The canonical alias of the room, if any. |
| 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. |
| 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. |
| avatar_url | string | The URL for the room's avatar, if one is set. |
Example request:
POST /_matrix/client/r0/publicRooms HTTP/1.1 Content-Type: application/json { "limit": 10, "filter": { "generic_search_term": "foo" }, "include_all_networks": false, "third_party_instance_id": "irc" }
Response:
Status code 200:
A list of the rooms on the server.
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 }
Performs a search for users on the homeserver. 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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| JSON body parameters | ||
| search_term | string | Required. The term to search for |
| limit | integer | The maximum number of results to return. Defaults to 10. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| results | [User] | Required. Ordered by rank and then whether or not profile info is available. |
| limited | boolean | Required. Indicates if the result list has been truncated by the limit. |
| Parameter | Type | Description |
|---|---|---|
| user_id | string | Required. The user's matrix user ID. |
| display_name | string | The display name of the user, if one exists. |
| avatar_url | string | The avatar url, as an MXC, if one exists. |
Example request:
POST /_matrix/client/r0/user_directory/search HTTP/1.1 Content-Type: application/json { "search_term": "foo", "limit": 10 }
Responses:
Status code 200:
The results of the search.
Example
{ "results": [ { "user_id": "@foo:bar.com", "display_name": "Foo", "avatar_url": "mxc://bar.com/foo" } ], "limited": false }
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user whose display name to set. |
| JSON body parameters | ||
| displayname | string | The new display name for this user. |
Example request:
PUT /_matrix/client/r0/profile/%40alice%3Aexample.com/displayname HTTP/1.1 Content-Type: application/json { "displayname": "Alice Margatroid" }
Responses:
Status code 200:
The display name was set.
Example
{}
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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 auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user whose display name to get. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| displayname | string | The user's display name if they have set one, otherwise not present. |
Example request:
GET /_matrix/client/r0/profile/%40alice%3Aexample.com/displayname HTTP/1.1
Responses:
Status code 200:
The display name for this user.
Example
{ "displayname": "Alice Margatroid" }
Status code 404:
There is no display name for this user or this user does not exist.
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 auth: | Yes. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user whose avatar URL to set. |
| JSON body parameters | ||
| avatar_url | string | The new avatar URL for this user. |
Example request:
PUT /_matrix/client/r0/profile/%40alice%3Aexample.com/avatar_url HTTP/1.1 Content-Type: application/json { "avatar_url": "mxc://matrix.org/wefh34uihSDRGhw34" }
Responses:
Status code 200:
The avatar URL was set.
Example
{}
Status code 429:
This request was rate-limited.
Example
{ "errcode": "M_LIMIT_EXCEEDED", "error": "Too many requests", "retry_after_ms": 2000 }
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 auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user whose avatar URL to get. |
Response format:
| Parameter | Type | Description |
|---|---|---|
| avatar_url | string | The user's avatar URL if they have set one, otherwise not present. |
Example request:
GET /_matrix/client/r0/profile/%40alice%3Aexample.com/avatar_url HTTP/1.1
Responses:
Status code 200:
The avatar URL for this user.
Example
{ "avatar_url": "mxc://matrix.org/SDGdghriugerRg" }
Status code 404:
There is no avatar URL for this user or this user does not exist.
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 auth: | No. |
Request format:
| Parameter | Type | Description |
|---|---|---|
| path parameters | ||
| userId | string | Required. The user whose profile information to get. |
Response format:
| Parameter | 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. |
Example request:
GET /_matrix/client/r0/profile/%40alice%3Aexample.com HTTP/1.1
Responses:
Status code 200:
The avatar URL for this user.
Example
{ "avatar_url": "mxc://matrix.org/SDGdghriugerRg", "displayname": "Alice Margatroid" }
Status code 404:
There is no profile information for this user or this user does not exist.
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:
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.
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 are parts of the Client-Server API which are not universal to all endpoints. Modules are strictly defined within this specification and should not be mistaken for experimental extensions or optional features. A compliant server implementation MUST support all modules and supporting specification (unless the implementation only targets clients of certain profiles, in which case only the required modules for those feature profiles MUST be implemented). A compliant client implementation MUST support all the required modules and supporting specification for the Feature Profile it targets.
Matrix supports many different kinds of clients: from embedded IoT devices to desktop clients. Not all clients can provide the same feature sets as other clients e.g. due to lack of physical hardware such as not having a screen. Clients can fall into one of several profiles and each profile contains a set of features that the client MUST support. This section details a set of "feature profiles". Clients are expected to implement a profile in its entirety in order for it to be classified as that profile.
| Module / Profile | Web | Mobile | Desktop | CLI | Embedded |
|---|---|---|---|---|---|
| Instant Messaging | Required | Required | Required | Required | Optional |
| Direct Messaging | Required | Required | Required | Required | Optional |
| Mentions | Required | Required | Required | Optional | Optional |
| Presence | Required | Required | Required | Required | Optional |
| Push Notifications | Optional | Required | Optional | Optional | Optional |
| Receipts | Required | Required | Required | Required | Optional |
| Fully read markers | Optional | Optional | Optional | Optional | Optional |
| Typing Notifications | Required | Required | Required | Required | Optional |
| VoIP | Required | Required | Required | Optional | Optional |
| Ignoring Users | Required | Required | Required | Optional | Optional |
| Reporting Content | Optional | Optional | Optional | Optional | Optional |
| Content Repository | Required | Required | Required | Optional | Optional |
| Managing History Visibility | Required | Required | Required | Required | Optional |
| Server Side Search | Optional | Optional | Optional | Optional | Optional |
| Room Upgrades | Required | Required | Required | Required | Optional |
| Server Administration | Optional | Optional | Optional | Optional | Optional |
| Event Context | Optional | Optional | Optional | Optional | Optional |
| Third Party Networks | Optional | Optional | Optional | Optional | Optional |
| Send-to-Device Messaging | Optional | Optional | Optional | Optional | Optional |
| Device Management | Optional | Optional | Optional | Optional | Optional |
| End-to-End Encryption | Optional | Optional | Optional | Optional | Optional |
| Guest Accounts | Optional | Optional | Optional | Optional | Optional |
| Room Previews | Optional | Optional | Optional | Optional | Optional |
| Client Config | Optional | Optional | Optional | Optional | Optional |
| SSO Login | Optional | Optional | Optional | Optional | Optional |
| OpenID | Optional | Optional | Optional | Optional | Optional |
| Stickers | Optional | Optional | Optional | Optional | Optional |
| Server ACLs | Optional | Optional | Optional | Optional | Optional |
| Server Notices | Optional | Optional | Optional | Optional | Optional |
Please see each module for more details on what clients need to implement.
This is a web page which heavily uses Matrix for communication. Single-page web apps would be classified as a stand-alone web client, as would multi-page web apps which use Matrix on nearly every page.
This is a Matrix client specifically designed for consumption on mobile devices. This is typically a mobile app but need not be so provided the feature set can be reached (e.g. if a mobile site could display push notifications it could be classified as a mobile client).
This is a native GUI application which can run in its own environment outside a browser.
This is a client which is used via a text-based terminal.
This is a client which is embedded into another application or an embedded device.
This is a Matrix client which is embedded in another website, e.g. using iframes. These embedded clients are typically for a single purpose related to the website in question, and are not intended to be fully-fledged communication apps.
This is a client which is typically running on an embedded device such as a kettle, fridge or car. These clients tend to perform a few operations and run in a resource constrained environment. Like embedded applications, they are not intended to be fully-fledged communication systems.
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.
Message Event
This event is used when sending messages in a room. Messages are not limited to be text. The msgtype key outlines the type of message, e.g. text, audio, image, video, etc. The body key is text and MUST be used with every kind of msgtype as a fallback mechanism for when a client cannot render a message. This allows clients to display something even if it is just plain text. For more information on msgtypes, see m.room.message msgtypes.
| Content Key | Type | Description |
|---|---|---|
| body | string | Required. The textual representation of this message. |
| msgtype | string | Required. The type of message, e.g. m.image, m.text |
Examples:
{ "content": { "body": "Bee Gees - Stayin' Alive", "info": { "duration": 2140786, "mimetype": "audio/mpeg", "size": 1563685 }, "msgtype": "m.audio", "url": "mxc://example.org/ffed755USFFxlgbQYZGtryd" }, "event_id": "$143273582443PhrSn:example.org", "origin_server_ts":<PHONE_NUMBER>653, "room_id": "!jEsUZKDJdhlrceRyVU:example.org", "sender": "@example:example.org", "type": "m.room.message", "unsigned": { "age": 1234 } }