Skip to content

Instantly share code, notes, and snippets.

Last active July 19, 2021 14:59
  • Star 7 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
What would you like to do?

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:
  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/'
    See also:
  4. Point room aliases at the new room and set up any integrations.
Copy link

KitsuneRal commented Nov 1, 2019

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



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/"

Copy link

hexmode commented Apr 21, 2021

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


# This is the host of your room

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

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

# Ask someone to verify this

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/"           | \
     ( echo -n "Event id for room replacment: "; jq -r .event_id )

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment