Hello from the other side: Matrix ↔ XMPP via ejabberd 25.03

In this guide, you'll learn how to send direct messages between Matrix and XMPP users, and even join public Matrix rooms using your favorite XMPP client.

Adrien
· 2 min read
Send by email
Photo by Dmitry Voronov / Unsplash


With ejabberd 25.03, the Matrix gateway (mod_matrix_gw) now supports not only one-to-one chats, but also joining Matrix rooms via XMPP. That’s right — your favorite XMPP client can now talk to Matrix users or hop into Matrix rooms just like regular MUCs. ✨

In this guide, we’ll show a quick demo of:

  1. One-to-one chat between an XMPP and a Matrix user.
  2. Joining a Matrix room and chatting from your XMPP client.

And the best part? You don’t need to install a Matrix client at all. Keep your favorite XMPP client near, welcome to the magic of federation & interoperability.

🛠 Setup Summary

We won’t repeat the full configuration steps here — they’re already covered in this earlier blogpost and the 25.03 release note.

In short, you’ll need:

  • A properly configured ejabberd server with mod_matrix_gw
  • Block outgoing connections to lethe.matrix.org to avoid conflicts with their XMPP instance

Here’s a minimal config snippet:

listen:
  -
    port: 8448
    module: ejabberd_http
    tls: true
    request_handlers:
      "/_matrix": mod_matrix_gw

modules:
  mod_matrix_gw:
    key_name: "xxxxxx"
    key: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    matrix_id_as_jid: true

Wondering what is the Matrix signing key? Please refer to previous blog post: Matrix gateway setup with ejabberd

Still not sure if your setup is correct? Try Matrix Federation Tester to check if everything is wired up properly.

🧪 One-to-One Chat (XMPP ↔ Matrix)

In your XMPP client (e.g. Psi), add a Matrix contact using this format:
matrixUser%theirMatrixServer.tld@yourXMPPserver.tld

In my case, that means:
adrien-p1%matrix.org@matrix.mickael.m.in-app.io

On the Matrix side (e.g. Element Web), your contact will get a request. Once accepted, you’re good to chat!

✅ Demo: XMPP user (Psi) chats with Matrix user (Element Web)

🧪 Join a Matrix Room from your XMPP Client

Alright, let’s join a public Matrix room now.

From your XMPP client, you can join any Matrix public room using this format:
#matrixRoom%theirMatrixServer.tld@yourXMPPserver.tld

We’ll use the following room: #ejabberd-demo:matrix.org, so in my case, that means joining:
#ejabberd-demo%matrix.org@matrix.mickael.m.in-app.io

Once connected, you’ll be able to send and receive messages from any other participant, just like in a regular MUC. :)

✅ Demo: Join and chat in a Matrix room from XMPP

🐞 Known Caveats

There's still a lot of work to do to make it seamless, here's a short list of currently known caveats:

  • Room presence can be overwhelming in large rooms (thousands of Matrix users may appear "online").
  • No E2EE support between Matrix and XMPP — encryption must be disabled for now.
  • If the server restarts, 1-to-1 conversations must be restarted (re-added), as persistence is not implemented yet.
  • Only Matrix room protocol versions 9, 10, and 11 are supported.

🧵 Wrapping Up

With this, ejabberd makes another step into being a powerful bridge into the Matrix federation, for both private and public communication.

It’s a great way to keep using your favorite XMPP tools while staying connected to Matrix communities.

Got feedback? Drop us a line in the comments or open a PR.

Happy bridging! 🙌

Written by Adrien