diff --git a/changelogs/client_server/newsfragments/1938.clarification b/changelogs/client_server/newsfragments/1938.clarification new file mode 100644 index 000000000..4bfd2a3cf --- /dev/null +++ b/changelogs/client_server/newsfragments/1938.clarification @@ -0,0 +1 @@ +The `reason` parameter in `POST /_matrix/client/v3/rooms/{roomId}/report/{eventId}` can be omitted instead of left blank as per [MSC2414](https://github.com/matrix-org/matrix-spec-proposals/pull/2414). diff --git a/changelogs/client_server/newsfragments/1938.new b/changelogs/client_server/newsfragments/1938.new new file mode 100644 index 000000000..718ee7550 --- /dev/null +++ b/changelogs/client_server/newsfragments/1938.new @@ -0,0 +1 @@ +Add `POST /_matrix/client/v3/rooms/{roomId}/report` as per [MSC4151](https://github.com/matrix-org/matrix-spec-proposals/pull/4151). diff --git a/content/client-server-api/modules/report_content.md b/content/client-server-api/modules/report_content.md index c482fbbc3..6489d8e5a 100644 --- a/content/client-server-api/modules/report_content.md +++ b/content/client-server-api/modules/report_content.md @@ -5,9 +5,6 @@ Users may encounter content which they find inappropriate and should be able to report it to the server administrators or room moderators for review. This module defines a way for users to report content. -Content is reported based upon a negative score, where -100 is "most -offensive" and 0 is "inoffensive". - #### Client behaviour {{% http-api spec="client-server" api="report_content" %}} @@ -19,6 +16,16 @@ This may be a dedicated room to alert server administrators to the reported content or some other mechanism for notifying the appropriate people. -{{< changed-in v="1.8" >}} The server MUST verify that the user -reporting the event is currently joined to the room the event is -in before accepting a report. +Particularly during waves of a harmful content, users may report whole +rooms instead of individual events. Server administrators and safety teams +should, therefore, be cautious not to shut down rooms that might otherwise +be legitimate. + +{{< changed-in v="1.8" >}} When processing event reports, servers MUST +verify that the reporting user is currently joined to the room the event +is in before accepting a report. + +{{< added-in v="1.12" >}} Contrarily, servers MUST NOT restrict room reports +based on whether or not the reporting user is joined to the room. This is +because users can be exposed to harmful content without being joined to a +room, for instance, through room directories. diff --git a/data/api/client-server/report_content.yaml b/data/api/client-server/report_content.yaml index f30e189d9..22131ef9c 100644 --- a/data/api/client-server/report_content.yaml +++ b/data/api/client-server/report_content.yaml @@ -16,6 +16,70 @@ info: title: Matrix Client-Server Report Content API version: 1.0.0 paths: + "/rooms/{roomId}/report": + post: + x-addedInMatrixVersion: "1.12" + summary: Report a room as inappropriate. + description: |- + Reports a room as inappropriate to the server, which may then notify + the appropriate people. The caller is not required to be joined to the + room to report it. + operationId: reportRoom + parameters: + - in: path + name: roomId + description: The room being reported. + required: true + example: "!637q39766251:example.com" + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + example: { + "reason": "this makes me sad" + } + properties: + reason: + type: string + description: The reason the room is being reported. + required: true + security: + - accessTokenQuery: [] + - accessTokenBearer: [] + responses: + "200": + description: The room has been reported successfully. + content: + application/json: + schema: + type: object + examples: + response: + value: {} + "404": + description: |- + The room was not found on the homeserver. + content: + application/json: + schema: + $ref: definitions/errors/error.yaml + examples: + response: + value: { + "errcode": "M_NOT_FOUND", + "error": "The room was not found." + } + "429": + description: This request was rate-limited. + content: + application/json: + schema: + $ref: definitions/errors/rate_limited.yaml + tags: + - Reporting content "/rooms/{roomId}/report/{eventId}": post: summary: Report an event in a joined room as inappropriate. @@ -29,7 +93,7 @@ paths: will require the homeserver to check whether a user is joined to the room. To combat this, homeserver implementations should add a random delay when generating a response. - operationId: reportContent + operationId: reportEvent parameters: - in: path name: roomId @@ -62,7 +126,7 @@ paths: and 0 is inoffensive. reason: type: string - description: The reason the content is being reported. May be blank. + description: The reason the content is being reported. required: true security: - accessTokenQuery: []