All the bridges here use the Matrix Application Service API. It's mostly the same as the client-server API, but there are a few key differences. Primarily, it means that the bridges
- can control any user ID in a predefined namespace, e.g. all user IDs starting
@telegram_and ending with
- don't have rate limits, and
- have events pushed to them via HTTP, instead of pulling with long polling like normal Matrix clients do.
To get these special privileges, the bridge must be registered on the homeserver as an appservice. In general, this requires root access to the server. Instructions for individual homeserver implementations can be found below.
All of the instructions below require you to have the
ready, so make sure you've reached the point in the bridge setup instructions
where it tells you to register the bridge on your homeserver.
The registration file is only necessary for the homeserver. None of the mautrix bridges will try to read it at runtime, as all the relevant information is also in the bridge-specific config file. However, this also means that if you change certain config fields, you must regenerate the registration file (or manually apply the relevant changes). The config fields that affect the registration are:
usernamein Go bridges)
If necessary, copy the registration file somewhere where Synapse can read it.
Then add the path to the file under
app_service_config_files in Synapse's
homeserver.yaml file. The field must be an array of strings, for example:
After updating the config, restart Synapse to apply changes. If you change or regenerate the registration file, you will need to restart Synapse every time.
If Synapse fails to start after editing the config, it means you either made a YAML syntax error, or the file path is incorrect or not readable. See the Synapse logs to find out what went wrong exactly.
Some things to keep in mind:
- When using Docker, the file needs to be mounted inside the container
- If Synapse is running through systemd, the service file might have security hardening features that block access to certain paths.
Follow the instructions at github.com/beeper/bridge-manager.
N.B. Dendrite is not a supported environment, as it often has serious bugs. It is strongly recommended to use Synapse or Conduit instead.
Dendrite works the same way as Synapse, except the relevant config field is
(and the config file is usually called
dendrite.yaml rather than
Conduit doesn't use a config file, instead it has an admin command for
registering appservices. Go to the admin room (which is created automatically
when the first user is registered on the server), copy the contents of the
registration YAML file, then send a
paste registration.yaml contents here
your.server.name with the server name. You can also use tab
autocompletion to mention the
@conduit user in most clients).
You can confirm it worked using the
list_appservices command (which should
id field of the just registered appservice):
Review the following to tweak your registration.yaml:
Add the prefix "bridge_" to the
sender_localparthave to match. Choose a simple name such as the service being bridged.
A bridge user and room will be created automatically based on the
!id:localhost). It is also okay if these already exist.
registration.jsonusing a yaml2json converter such as
reserializeor a website.
apt-get -y install reserialize reserialize yaml2json registration.yaml > registration.json
Use the console to enter the command:
bridge set /path/to/registration.json
If the bridge has already been registered before then the prior configuration will be overwritten.
The registration will take effect immediately without restarting the server or reloading the bridge module.
The console command
bridgewill list all bridges by ID.
bridge <id>will confirm the configuration for the bridge.
The following are all functionally equivalent:
- With terminal access strike
bridge set /path/to/registration.jsonat the prompt.
- Operator sends message
bridge set /path/to/registration.jsonto the
- Operator sends server-side private-command prefix
\\control bridge set /path/to/registration.json(any client, any room).
- Non-interactive registration add the argument
-execute "bridge set /path/to/registration.json"when running the server.
- Non-interactive registration for multiple bridges: use multiple
-execute "bridge set registration1.json" -execute "bridge set registration2.json"
- With terminal access strike