- A signature of the token, signed with the identity server's private key
- A signature of the token, signed with the identity server's private key
- The matrix user ID who invited them to the room
- The matrix user ID who invited them to the room
If a token is requested from the identity server, the homeserver will
append a `m.room.third_party_invite` event to the room.
operationId:inviteBy3PID
operationId:inviteBy3PID
security:
security:
- accessTokenQuery:[]
- accessTokenQuery:[]
@ -72,6 +69,8 @@ paths:
example:"!d41d8cd:matrix.org"
example:"!d41d8cd:matrix.org"
schema:
schema:
type:string
type:string
format:mx-room-id
pattern:"^!"
requestBody:
requestBody:
content:
content:
application/json:
application/json:
@ -90,7 +89,9 @@ paths:
value:{}
value:{}
"403":
"403":
description:|-
description:|-
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:
You do not have permission to invite the user to the room. A
meaningful `errcode` and description error text will be returned.
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the state directly as there are a restricted set of valid transformations. For example, user A cannot force user B to join a room, and trying to force this state change directly will fail.
Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
(`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
state directly as there are a restricted set of valid transformations. For example, user A cannot
force user B to join a room, and trying to force this state change directly will fail.
The following membership states are specified:
The following membership states are specified:
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not participate in the room until they join.
- `invite` - The user has been invited to join a room, but has not yet joined it. They may not
- `join` - The user has joined the room (possibly after accepting an invite), and may participate in it.
participate in the room until they join.
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or possibly by being kicked).
- `join` - The user has joined the room (possibly after accepting an invite), and may participate
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they are un-banned from the room (by having their membership state set to a value other than `ban`).
in it.
- `knock` - The user has knocked on the room, requesting permission to participate. They may not participate in the room until they join.
- `leave` - The user was once joined to the room, but has since left (possibly by choice, or
possibly by being kicked).
- `ban` - The user has been banned from the room, and is no longer allowed to join it until they
are un-banned from the room (by having their membership state set to a value other than `ban`).
- `knock` - The user has knocked on the room, requesting permission to participate. They may not
participate in the room until they join.
The `third_party_invite` property will be set if this invite is an `invite` event and is the successor of an `m.room.third_party_invite` event, and absent otherwise.
The `third_party_invite` property will be set if this invite is an `invite` event and is the
successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
and absent otherwise.
This event may also include an `invite_room_state` key inside the event's `unsigned` data.
This event may also include an `invite_room_state` key inside the event's `unsigned` data.
If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
@ -57,63 +67,54 @@ properties:
- ban
- ban
type:string
type:string
is_direct:
is_direct:
description:Flag indicating if the room containing this event was created with the intention of being a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
description:|-
Flag indicating if the room containing this event was created with the intention of being
a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
type:boolean
type:boolean
join_authorised_via_users_server:
join_authorised_via_users_server:
x-addedInMatrixVersion:"1.2"
x-addedInMatrixVersion:"1.2"
type:string
type:string
description:|-
description:|-
Usually found on `join` events, this field is used to denote which homeserver (through representation of a user with sufficient power level)
Usually found on `join` events, this field is used to denote which homeserver (through
authorised the user's join. More information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
representation of a user with sufficient power level) authorised the user's join. More
information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules) of including this
Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
field in further events:in particular, the event must be signed by the server which
of including this field in further events:in particular, the event must be signed by the
owns the user ID in the field. When copying the membership event's `content`
server which owns the user ID in the field. When copying the membership event's `content`
(for profile updates and similar) it is therefore encouraged to exclude this
(for profile updates and similar) it is therefore encouraged to exclude this field in the
field in the copy, as otherwise the event might fail event authorization.
copy, as otherwise the event might fail event authorization.
reason:
reason:
x-addedInMatrixVersion:"1.1"
x-addedInMatrixVersion:"1.1"
type:string
type:string
description:|-
description:|-
Optional user-supplied text for why their membership has changed. For kicks and bans, this is typically the reason for the kick or ban.
Optional user-supplied text for why their membership has changed. For kicks and bans,
For other membership changes, this is a way for the user to communicate their intent without having to send a message to the room, such
this is typically the reason for the kick or ban. For other membership changes, this is a
as in a case where Bob rejects an invite from Alice about an upcoming concert, but can't make it that day.
way for the user to communicate their intent without having to send a message to the
room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
but can't make it that day.
Clients are not recommended to show this reason to users when receiving an invite due to the potential for spam and abuse. Hiding the
Clients are not recommended to show this reason to users when receiving an invite due to
reason behind a button or other component is recommended.
the potential for spam and abuse. Hiding the reason behind a button or other component is
recommended.
third_party_invite:
third_party_invite:
title:ThirdPartyInvite
description:|-
A third-party invite, if this `m.room.member` is the successor to an
description:"Acts as an `m.room.member` invite event, where there isn't a target user_id to invite. This event contains a token and a public key whose private key must be used to sign the token. Any user who can present that signature may use this invitation to join the target room."
description:|-
Acts as an `m.room.member` invite event, where there isn't a target user_id to
invite. This event contains a token and a public key whose private key must be
used to sign the token. Any user who can present that signature may use this
invitation to join the target room.
properties:
properties:
content:
content:
properties:
properties:
display_name:
display_name:
description:"A user-readable string which represents the user who has been invited. This should not contain the user's third-party ID, as otherwise when the invite is accepted it would leak the association between the matrix ID and the third-party ID."
description:|-
A user-readable string which represents the user who has been invited.
This should not contain the user's third-party ID, as otherwise when
the invite is accepted it would leak the association between the
matrix ID and the third-party ID.
type:string
type:string
key_validity_url:
key_validity_url:
description:"A URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'."
description:|-
A URL which can be fetched, with querystring public_key=public_key, to
validate whether the key has been revoked. The URL must return a JSON
object containing a boolean property named 'valid'.
type:string
type:string
format:uri
public_key:
public_key:
description:A base64-encoded ed25519 key with which token must be signed (though a signature from any entry in public_keys is also sufficient). This exists for backwards compatibility.
description:|-
An Ed25519 key with which the token must be signed (though a signature
from any entry in `public_keys` is also sufficient).
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
using the standard or URL-safe alphabets.
This exists for backwards compatibility.
type:string
type:string
public_keys:
public_keys:
description:Keys with which the token may be signed.
description:Keys with which the token may be signed.
items:
items:
properties:
properties:
key_validity_url:
key_validity_url:
description:"An optional URL which can be fetched, with querystring public_key=public_key, to validate whether the key has been revoked. The URL must return a JSON object containing a boolean property named 'valid'. If this URL is absent, the key must be considered valid indefinitely."
description:|-
An optional URL which can be fetched, with querystring
`public_key=<public_key>`, to validate whether the key has been
revoked. The URL must return a JSON object containing a boolean
property named `valid`. If this URL is absent, the key must be
considered valid indefinitely.
type:string
type:string
public_key:
public_key:
description:A base-64 encoded ed25519 key with which token may be signed.
description:|-
An Ed25519 key with which the token may be signed.
The key is encoded using [Unpadded Base64](/appendices/#unpadded-base64),
using the standard or URL-safe alphabets.
type:string
type:string
required:
required:
- public_key
- public_key
@ -35,11 +63,15 @@ properties:
- public_key
- public_key
type:object
type:object
state_key:
state_key:
description:'The token, of which a signature must be produced in order to join the room.'
description:|-
The token, of which a signature must be produced in order to join the
room.
type:string
type:string
type:
type:
enum:
enum:
- m.room.third_party_invite
- m.room.third_party_invite
type:string
type:string
title:'An invitation to a room issued to a third-party identifier, rather than a matrix user ID.'
title:|-
An invitation to a room issued to a third-party identifier, rather than a
Kévin Commaille
8 months ago
committed by