manual-room-upgrade.md

Upgrading a room the hard way manually

Disclaimer: Normally you should just use the upgrade endpoints or built-in upgrade functionality of your client. Manual upgrades are required under some circumstances, but should be used rarely. This guide assumes you have basic knowledge of Matrix as well as JSON.

Before you begin: Be sure to disconnect any bridges from the room and be prepared to have to manually reconfigure bots, bridges, and other integrations.

1. In the room you want to upgrade, get the event ID from the most recent event in the room. In Riot, click the 3 dots to the right of the message then "View Source". The dialog should contain an event_id.
2. Create a room which will serve as the new room. Be sure to use the right room version. Noting the strings needing to be replaced, an example curl call would be:

   curl -s -X POST -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" --data-binary '{"name":"My New Room","room_version":"3","creation_content":{"predecessor":{"room_id":"THE_OLD_ROOM_ID","event_id":"THE_LAST_EVENT_ID_IN_THE_OLD_ROOM"}}}' https://YOUR_HOMESERVER/_matrix/client/r0/createRoom
   

   See also: https://matrix.org/docs/spec/client_server/unstable.html#post-matrix-client-r0-createroom
3. Remembering the room_id of the new room, send a tombstone event into the old room.

   curl -s -X PUT -H "Authorization: Bearer YOUR_ACCESS_TOKEN" -H "Content-Type: application/json" --data-binary '{"replacement_room":"THE_NEW_ROOM_ID"}' 'https://YOUR_HOMESERVER/_matrix/client/r0/rooms/!OLD_ROOM_ID/state/m.room.tombstone'
   

   See also: https://matrix.org/docs/spec/client_server/unstable.html#m-room-tombstone
4. Point room aliases at the new room and set up any integrations.

The script that partially automates things (requires $ACCESS_TOKEN environment variable, the rest is passed in parameters):

#!/bin/sh

CSAPI_URL="$1/_matrix/client/r0"
OLD_ROOM_ID=$2
LAST_EVENT_ID=$3

NEW_ROOM_ID=`curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" --data-binary "{\"room_version\":\"5\",\"creation_content\":{\"predecessor\":{\"room_id\":\"$OLD_ROOM_ID\",\"event_id\":\"$LAST_EVENT_ID\"}}}" "$CSAPI_URL/createRoom" | awk -F\" '{ printf $4 }'`
echo "New room id: $NEW_ROOM_ID"

curl -s -X PUT -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" --data-binary "{\"replacement_room\":\"$NEW_ROOM_ID\"}" "$CSAPI_URL/rooms/$OLD_ROOM_ID/state/m.room.tombstone"

Here is a version to use if you have jq installed and a little more information on where to find the particular bits needed:

#!/bin/sh

# This is the host of your room
DOMAIN=matrix.org
CSAPI_URL="https://$DOMAIN/_matrix/client/r0"

# In Element, hover over the last message in the room, click the ellipses (options) and select "View Source"
OLD_ROOM_ID=''
LAST_EVENT_ID=''

# In Element, User Settings -> Help & About, Advanced, Access Token <click to reveal>
ACCESS_TOKEN=''

# Ask someone to verify this
ROOM_VERSION=6

NEW_ROOM_ID=`curl -s -X POST -H "Authorization: Bearer $ACCESS_TOKEN"   \
     -H "Content-Type: application/json"                                \
     --data-binary "{                                                   \
                        \"room_version\":\"$ROOM_VERSION\",             \
                        \"creation_content\":{                          \
                            \"predecessor\":{                           \
                                 \"room_id\":\"$OLD_ROOM_ID\",          \
                                 \"event_id\":\"$LAST_EVENT_ID\"        \
                            }                                           \
                        }                                               \
                    }" "$CSAPI_URL/createRoom" | jq -r .room_id`
echo "New room id: $NEW_ROOM_ID"

curl -s -X PUT -H "Authorization: Bearer $ACCESS_TOKEN"                 \
     -H "Content-Type: application/json"                                \
     --data-binary "{                                                   \
                        \"replacement_room\":\"$NEW_ROOM_ID\"           \
                    }"                                                  \
     "$CSAPI_URL/rooms/$OLD_ROOM_ID/state/m.room.tombstone"           | \
     ( echo -n "Event id for room replacment: "; jq -r .event_id )