1
1
# Matrix <--> Zulip bridge
2
2
3
- This acts as a bridge between Matrix and Zulip.
3
+ This acts as a bridge between Matrix and Zulip. It also enables a
4
+ Zulip topic to be federated between two Zulip servers.
4
5
5
- ### Enhanced Features
6
- - Supporting multiple (Zulip topic, Matrix channel)-pairs.
7
- - Handling files according to their mimetype.
6
+ ## Usage
8
7
8
+ ### For IRC bridges
9
9
10
- ## Installation
11
-
12
- Run ` pip install -r requirements.txt ` in order to install the requirements .
10
+ Matrix has been bridged to the listed
11
+ [ IRC networks ] ( https://github.com/matrix-org/matrix-appservice-irc/wiki/Bridged-IRC-networks ) ,
12
+ where the 'Room alias format' refers to the ` room_id ` for the corresponding IRC channel .
13
13
14
- In case you'd like encryption to work, you need pip to install the ` matrix-nio `
15
- package with e2e support:
16
- - First, you need to make sure that the development files of the ` libolm `
17
- C-library are installed on your system! See [ the corresponding documentation
18
- of matrix-nio] ( https://github.com/poljar/matrix-nio#installation ) for further
19
- information on this point.
20
- - ` pip install matrix-nio[e2e] `
14
+ For example, for the freenode channel ` #zulip-test ` , the ` room_id ` would be
15
+ ` #freenode_#zulip-test:matrix.org ` .
21
16
17
+ Hence, this can also be used as a IRC <--> Zulip bridge.
22
18
23
19
## Steps to configure the Matrix bridge
24
20
@@ -31,43 +27,19 @@ details mentioned below. For example:
31
27
* If you are running from the Zulip GitHub repo: ` python matrix_bridge.py --write-sample-config matrix_bridge.conf `
32
28
33
29
### 1. Zulip endpoint
34
- 1 . Create a generic Zulip bot, with a full name such as ` Matrix Bot ` .
35
- 2 . The bot is able to subscribe to the necessary streams itself if they are
36
- public. (Note that the bridge will not try to create streams in case they
37
- do not already exist. In that case, the bridge will fail at startup.)
38
- Otherwise, you need to add the bot manually.
30
+ 1 . Create a generic Zulip bot, with a full name like ` IRC Bot ` or ` Matrix Bot ` .
31
+ 2 . Subscribe the bot user to the stream you'd like to bridge your IRC or Matrix
32
+ channel into.
39
33
3 . In the ` zulip ` section of the configuration file, enter the bot's ` zuliprc `
40
34
details (` email ` , ` api_key ` , and ` site ` ).
41
35
4 . In the same section, also enter the Zulip ` stream ` and ` topic ` .
42
36
43
37
### 2. Matrix endpoint
44
- 1 . Create a user on the matrix server of your choice, e.g. [ matrix.org] ( https://matrix.org/ ) ,
45
- preferably with a descriptive name such as ` zulip-bot ` .
46
- 2 . In the ` matrix ` section of the configuration file, enter the user's Matrix
47
- user ID ` mxid ` and password. Please use the Matrix user ID ([ MXID] ( https://matrix.org/faq/#what-is-a-mxid%3F ) )
48
- as format for the username!
49
- 3 . Create the Matrix room(s) to be bridged in case they do not exits yet.
50
- Remember to invite the bot to private rooms! Otherwise, this error will be
51
- thrown: ` Matrix bridge error: JoinError: M_UNKNOWN No known servers ` .
52
- 4 . Enter the ` host ` and ` room_id ` into the same section.
53
- In case the room is private you need to use the ` Internal room ID ` which has
54
- the format ` !aBcDeFgHiJkLmNoPqR:example.org ` .
55
- In the official Matrix client [ Element] ( https://github.com/vector-im ) , you
56
- can find this ` Internal room ID ` in the ` Room Settings ` under ` Advanced ` .
57
-
58
- ### Adding more (Zulip topic, Matrix channel)-pairs
59
- 1 . Create a new section with a name starting with ` additional_bridge ` .
60
- 2 . Add a ` room_id ` for the Matrix side and a ` stream ` and a ` topic ` for the
61
- Zulip side.
62
-
63
- Example:
64
- ```
65
- [additional_bridge1]
66
- room_id = #zulip:matrix.org
67
- stream = matrix test
68
- topic = matrix test topic
69
- ```
70
-
38
+ 1 . Create a user on [ matrix.org] ( https://matrix.org/ ) , preferably with
39
+ a formal name like to ` zulip-bot ` .
40
+ 2 . In the ` matrix ` section of the configuration file, enter the user's username
41
+ and password.
42
+ 3 . Also enter the ` host ` and ` room_id ` into the same section.
71
43
72
44
## Running the bridge
73
45
@@ -78,29 +50,9 @@ in a file called `matrix_bridge.conf`:
78
50
79
51
* If you are running from the Zulip GitHub repo: run ` python matrix_bridge.py -c matrix_bridge.conf `
80
52
81
-
82
- ## Notes regarding IRC
83
-
84
- ### Usage for IRC bridges
85
-
86
- This can also be used to indirectly bridge between IRC and Zulip.
87
-
88
- Matrix has been bridged to the listed
89
- [ IRC networks] ( https://matrix-org.github.io/matrix-appservice-irc/latest/bridged_networks.html ) ,
90
- where the 'Room alias format' refers to the ` room_id ` for the corresponding IRC channel.
91
-
92
- For example, for the Libera Chat channel ` #zulip-test ` , the ` room_id ` would be
93
- ` #zulip-test:libera.chat ` .
94
-
95
- ### Caveats for IRC mirroring
53
+ ## Caveats for IRC mirroring
96
54
97
55
There are certain
98
56
[ IRC channels] ( https://github.com/matrix-org/matrix-appservice-irc/wiki/Channels-from-which-the-IRC-bridge-is-banned )
99
57
where the Matrix.org IRC bridge has been banned for technical reasons.
100
58
You can't mirror those IRC channels using this integration.
101
-
102
-
103
- ## TODO
104
-
105
- - Adding support for editing and deleting messages?
106
- - Handling encryption on the Matrix side (may need further discussion).
0 commit comments