Exchange messages between matrix.org and Zulip! If you're looking to mirror an IRC channel in particular, we recommend our direct IRC integration.

Install the bridge software

1. Clone the Zulip API repository, and install its dependencies.

   git clone https://github.com/zulip/python-zulip-api.git
   cd python-zulip-api
   python3 ./tools/provision

   This will create a new Python virtualenv. You'll run the bridge service inside this virtualenv.

2. Activate the virtualenv by running the source command printed at the end of the output of the previous step.

3. Install the Matrix bridge software in your virtualenv, by running:

   pip install -r zulip/integrations/bridge_with_matrix/requirements.txt

Configure the bridge

1. Create a bot for Matrix. Make sure that you select Generic bot as the Bot type.

   Download the bot's zuliprc configuration file to your computer.

2. Subscribe the bot to the Zulip stream that will contain the mirror.

3. Inside the virtualenv you created above, run

   python zulip/integrations/bridge_with_matrix/matrix_bridge.py \
   --write-sample-config matrix_bridge.conf --from-zuliprc <path/to/zuliprc>

   where <path/to/zuliprc> is the path to the zuliprc file you downloaded.

4. Create a user on matrix.org or another matrix server, preferably with a descriptive name like zulip-bot.

5. Edit matrix_bridge.conf to look like this:

   [zulip]
   email = bridge-bot@chat.zulip.org
   api_key = aPiKeY
   site = https://chat.zulip.org
   stream = "stream name"
   topic = "Matrix mirror"
   [matrix]
   host = https://matrix.org
   username = <your matrix username>
   password = <your matrix password>
   room_id = #room:matrix.org

   The first three values should already be there; the rest you'll have to fill in. Make sure stream is set to the stream the bot is subscribed to.

6. Run the following command to start the matrix bridge:

   python zulip/integrations/bridge_with_matrix/matrix_bridge.py -c matrix_bridge.conf

Note: There are a handful of IRC channels that have temporarily banned the Matrix.org IRC bridge. You can't currently mirror those channels using this integration.