Matrix: Migrate an encrypted room to a clear text one

Publié le 24/03/2022

Some time ago, the Matrix team was pushing hard E2EE and activated it for all created rooms. Believing encryption was the future, we kept this default for all of our rooms. But now that one of our room starts being popular, it appears that E2EE does not work well with public rooms:

  1. the history is not available to newcomers
  2. we can not search the history of an encrypted room (or at least, I never managed to make it work even with the desktop app)
  3. notification options are more limited
  4. scaling issues
  5. many additional minor issues

It seems that Matrix developers are aware of these problems as if you create a “public room” now, you will not be proposed to encrypt it. But for existing rooms, we still have a problem: for security reasons, you can’t disable encryption in a room. Our only option is to create a new room and to point the old one to the new one.

Thankfully, Matrix has a feature named Tombstone that helps redirecting users from one room to another. This feature is used for room version upgrade, but we can “abuse” it to redirect people to a completely different room.

First, you must create a new clear text room. To provide the best experience to your users, take time to configure its picture, description, and so on. Now, go to your old room, remove all its aliases to be able to set them on the new room. You can set a new alias for your old room and send a message containing it on your new room, to “connect it with the old one”, eg:

Hi, this is the beginning of the history of this room. If you want to go back even more in time, check the old room: #myroom-old:example.tld

Finally, you need the identifier of your new room. It starts with a !. For example: ! Keep it somewhere accessible, and we are done configuring our new room.

We can now prepare the tombstone for the old room. First, you should inform your users with a message, something like:

Hi @room, we are migrating to a new room to fix some issues with this one. You will not be able to post new messages here, please follow the provided redirection to join the new room. Sorry for the inconvenience.

Now, open the developper tools in your old room by typing in the message box:


You can also open it by going in “Room Settings” -> “Advanced” -> “Open Devtools”

A window must appear. Click on “Send Custom Event”. Then click on the red button “Event” to create a “State Event”. Put as the Event Type, keep the State Key field empty, and finally enter the following content (replace the example room ID by the one of your new room):

  "body": "We migrated to a cleartext rooms as E2EE does not work well with large public rooms",
  "replacement_room": "!"

And that’s all, you have migrated your old encrypted room to a new clear text one!

If you want to explore all the possibilities offered by the developer tools, you can read Matrix specification. For example, our tombstone event is documented here: