From 7b4c532ab70079bfda251f9ef1e44aa70e726249 Mon Sep 17 00:00:00 2001 From: babolivier Date: Tue, 30 Nov 2021 14:28:51 +0000 Subject: deploy: e713855dca17a7605bae99ea8d71bc7f8657e4b8 --- latest/admin_api/rooms.html | 215 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 204 insertions(+), 11 deletions(-) (limited to 'latest/admin_api/rooms.html') diff --git a/latest/admin_api/rooms.html b/latest/admin_api/rooms.html index 4d9b06b619..8e31f898fd 100644 --- a/latest/admin_api/rooms.html +++ b/latest/admin_api/rooms.html @@ -99,7 +99,7 @@ @@ -188,8 +188,12 @@
  • Room Details API
  • Room Members API
  • Room State API
    • +
  • Block Room API
  • Delete Room API
    • @@ -536,6 +540,61 @@ end of the list.

    ] } +

    Block Room API

    +

    The Block Room admin API allows server admins to block and unblock rooms, +and query to see if a given room is blocked. +This API can be used to pre-emptively block a room, even if it's unknown to this +homeserver. Users will be prevented from joining a blocked room.

    +

    Block or unblock a room

    +

    The API is:

    +
    PUT /_synapse/admin/v1/rooms/<room_id>/block
+
    +

    with a body of:

    +
    {
+    "block": true
+}
+
    +

    A response body like the following is returned:

    +
    {
+    "block": true
+}
+
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    The following JSON body parameters are available:

    + +

    Response

    +

    The following fields are possible in the JSON response body:

    + +

    Get block status

    +

    The API is:

    +
    GET /_synapse/admin/v1/rooms/<room_id>/block
+
    +

    A response body like the following is returned:

    +
    {
+    "block": true,
+    "user_id": "<user_id>"
+}
+
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    Response

    +

    The following fields are possible in the JSON response body:

    +

    Delete Room API

    The Delete Room admin API allows server admins to remove rooms from the server and block these rooms.

    @@ -545,15 +604,27 @@ leave the room without any information.

    The new room will be created with the user specified by the new_room_user_id parameter as room administrator and will contain a message explaining what happened. Users invited to the new room will have power level -10 by default, and thus be unable to speak.

    -

    If block is True it prevents new joins to the old room.

    +

    If block is true, users will be prevented from joining the old room. +This option can in Version 1 also be used to pre-emptively +block a room, even if it's unknown to this homeserver. In this case, the room will be +blocked, and no further action will be taken. If block is false, attempting to +delete an unknown room is invalid and will be rejected as a bad request.

    This API will remove all trace of the old room from your database after removing all local users. If purge is true (the default), all traces of the old room will be removed from your database after removing all local users. If you do not want this to happen, set purge to false. -Depending on the amount of history being purged a call to the API may take +Depending on the amount of history being purged, a call to the API may take several minutes or longer.

    The local server will only have the power to move local user and room aliases to the new room. Users on other servers will be unaffected.

    +

    To use it, you will need to authenticate by providing an access_token for a +server admin: see Admin API.

    +

    Version 1 (old version)

    +

    This version works synchronously. That means you only get the response once the server has +finished the action, which may take a long time. If you request the same action +a second time, and the server has not finished the first one, the second request will block. +This is fixed in version 2 of this API. The parameters are the same in both APIs. +This API will become deprecated in the future.

    The API is:

    DELETE /_synapse/admin/v1/rooms/<room_id>
    @@ -566,8 +637,6 @@ the new room. Users on other servers will be unaffected.

    "purge": true } -

    To use it, you will need to authenticate by providing an access_token for a -server admin: see Admin API.

    A response body like the following is returned:

    {
     "kicked_users": [
@@ -581,6 +650,31 @@ server admin: see Admin API.
    
     "new_room_id": "!newroomid:example.com"
 }
    +

    The parameters and response values have the same format as +version 2 of the API.

    +

    Version 2 (new version)

    +

    Note: This API is new, experimental and "subject to change".

    +

    This version works asynchronously, meaning you get the response from server immediately +while the server works on that task in background. You can then request the status of the action +to check if it has completed.

    +

    The API is:

    +
    DELETE /_synapse/admin/v2/rooms/<room_id>
+
    +

    with a body of:

    +
    {
+    "new_room_user_id": "@someuser:example.com",
+    "room_name": "Content Violation Notification",
+    "message": "Bad Room has been shutdown due to content violations on this server. Please review our Terms of Service.",
+    "block": true,
+    "purge": true
+}
+
    +

    The API starts the shut down and purge running, and returns immediately with a JSON body with +a purge id:

    +
    {
+    "delete_id": "<opaque id>"
+}
+

    Parameters

    The following parameters should be set in the URL:

    The JSON body must not be empty. The body must be at least {}.

    -

    Response

    +

    Status of deleting rooms

    +

    Note: This API is new, experimental and "subject to change".

    +

    It is possible to query the status of the background task for deleting rooms. +The status can be queried up to 24 hours after completion of the task, +or until Synapse is restarted (whichever happens first).

    +

    Query by room_id

    +

    With this API you can get the status of all active deletion tasks, and all those completed in the last 24h, +for the given room_id.

    +

    The API is:

    +
    GET /_synapse/admin/v2/rooms/<room_id>/delete_status
+
    +

    A response body like the following is returned:

    +
    {
+    "results": [
+        {
+            "delete_id": "delete_id1",
+            "status": "failed",
+            "error": "error message",
+            "shutdown_room": {
+                "kicked_users": [],
+                "failed_to_kick_users": [],
+                "local_aliases": [],
+                "new_room_id": null
+            }
+        }, {
+            "delete_id": "delete_id2",
+            "status": "purging",
+            "shutdown_room": {
+                "kicked_users": [
+                    "@foobar:example.com"
+                ],
+                "failed_to_kick_users": [],
+                "local_aliases": [
+                    "#badroom:example.com",
+                    "#evilsaloon:example.com"
+                ],
+                "new_room_id": "!newroomid:example.com"
+            }
+        }
+    ]
+}
+
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    Query by delete_id

    +

    With this API you can get the status of one specific task by delete_id.

    +

    The API is:

    +
    GET /_synapse/admin/v2/rooms/delete_status/<delete_id>
+
    +

    A response body like the following is returned:

    +
    {
+    "status": "purging",
+    "shutdown_room": {
+        "kicked_users": [
+            "@foobar:example.com"
+        ],
+        "failed_to_kick_users": [],
+        "local_aliases": [
+            "#badroom:example.com",
+            "#evilsaloon:example.com"
+        ],
+        "new_room_id": "!newroomid:example.com"
+    }
+}
+
    +

    Parameters

    +

    The following parameters should be set in the URL:

    + +

    Response

    The following fields are returned in the JSON response body:

    Undoing room deletions

    Note: This guide may be outdated by the time you read it. By nature of room deletions being performed at the database level, -- cgit 1.5.1