diff --git a/api/client-server/v1/membership.yaml b/api/client-server/v1/membership.yaml index 04922656d..17b5795e4 100644 --- a/api/client-server/v1/membership.yaml +++ b/api/client-server/v1/membership.yaml @@ -66,11 +66,16 @@ paths: aliases: - /join/{roomId} - "/rooms/{roomId}/invite": + # With an extra " " to disambiguate from the 3pid invite endpoint + # The extra space makes it sort first for what I'm sure is a good reason. + "/rooms/{roomId}/invite ": post: summary: Invite a user to participate in a particular room. - # It's a crying shame that I don't know how to force line breaks. description: |- + *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.* + 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. @@ -82,6 +87,9 @@ paths: Only users currently in a particular room can invite other users to join that room. + + If the user was invited to the room, the home server will append a + ``m.room.member`` event to the room. security: - accessToken: [] parameters: @@ -92,7 +100,7 @@ paths: required: true x-example: "!d41d8cd:matrix.org" - in: body - name: user_id + name: body required: true schema: type: object @@ -112,7 +120,107 @@ paths: application/json: |- {} schema: - type: object # empty json object + type: object + 403: + 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: + - The invitee has been banned from the room. + - The invitee is already a member of the room. + - The inviter is not currently in the room. + - The inviter's power level is insufficient to invite users to the room. + examples: + application/json: |- + {"errcode": "M_FORBIDDEN", "error": "@cheeky_monkey:matrix.org is banned from the room"} + 429: + description: This request was rate-limited. + schema: + "$ref": "definitions/error.yaml" + + "/rooms/{roomId}/invite": + post: + summary: Invite a user to participate in a particular room. + description: |- + *Note that there are two forms of this API, which are documented separately. + This version of the API does not require that the inviter know the Matrix + identifier of the invitee, and instead relies on third party identifiers.* + + 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. + + This serves two purposes; firstly, to notify the user that the room + exists (and that their presence is requested). Secondly, some rooms can + only be joined if a user is invited to join it; sending the invite gives + that user permission to join the room. + + Only users currently in a particular room can invite other users to + join that room. + + If the identity server does not know a Matrix user identifier for the + passed third party identifier, the homeserver will issue an invitation + which can be accepted upon providing proof of ownership of the third + party identifier. This is achieved by requesting a nonce and digest from + the identity server. When a user binds the invited third party + identifier to a Matrix user ID, the identity server will give the user a + list of pending invitations, each containing: + + - The room ID to which they were invited + + - The digest given to the homeserver + + - A secret which, when appended to the nonce, digests to the above digest + + The digest algorithm to be used is SHA256. + + If the identity server did know the Matrix user identifier for the + third party identifier, the home server will append a ``m.room.member`` + event to the room. + + If a digest and nonce are requested from the identity server, the home + server will append a ``m.room.token_based_invite`` event to the room. + security: + - accessToken: [] + parameters: + - in: path + type: string + name: roomId + description: The room identifier (not alias) to which to invite the user. + required: true + x-example: "!d41d8cd:matrix.org" + - in: body + name: body + required: true + schema: + type: object + example: |- + { + "identity_server": "matrix.org", + "medium": "email", + "address": "cheeky@monkey.com", + "display_name": "A very cheeky monkey" + } + properties: + identity_server: + type: string + description: The hostname+port of the identity server which should be used for third party identifier lookups. + medium: + type: string + description: The kind of address being passed in the address field. + address: + type: string + description: The invitee's third party identifier. + display_name: + type: string + description: A user-friendly string describing who has been invited. It should not contain the address of the invitee, to avoid leaking mappings between third party identities and matrix user IDs. + required: ["identity_server", "medium", "address", "display_name"] + responses: + 200: + description: The user has been invited to join the room. + examples: + application/json: |- + {} + schema: + type: object 403: 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: diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index d8cc213de..150b0942b 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -110,7 +110,7 @@ class MatrixUnits(Units): "title": single_api.get("summary", ""), "desc": single_api.get("description", single_api.get("summary", "")), "method": method.upper(), - "path": full_path, + "path": full_path.strip(), "requires_auth": "security" in single_api, "rate_limited": 429 in single_api.get("responses", {}), "req_params": [],