Bridges

Documentation covering how to use the various Matrix / Element bridges

Setting up Hookshot without E2EE support in encrypted rooms

If your Hookshot instance does not have E2EE support enabled but you still want to add it to an encrypted room, you can do this with a couple of caveats:

To set this up:

My message was sent without encryption and Hookshot responded. You can now use Hookshot via the widget normally.

Note that all messages sent by Hookshot remain unencrypted. Element warns you with the red shield on the messages.

Using the Matrix IRC Bridge

The Matrix IRC Bridge is an IRC bridge for Matrix that will pass all IRC messages through to Matrix, and all Matrix messages through to IRC.

If you're an end user of the bridge, it's unlikely you will need to use the below commands, your IRC Channels may already be bridged to specific Matrix Rooms so you can simply join the Room from Matrix, or the Channel from IRC and communicate with Matrix/IRC users. Our End User focused documentation might be better suited to getting started with Matrix and IRC - Using the Matrix IRC Bridge as an End User

Please also refer to the Bridge Documentation for additional guidance.

The bridge is currently used on the matrix.org homeserver to bridge a number of popular IRC networks.

Getting Started with the Matrix IRC Bridge

In this guide we will be using the Matrix.org bridge to the Open and Free Technology Community (OFTC) IRC network. The key information to note is the Room alias format (#_oftc_#channame:matrix.org) and Appservice user (@oftc-irc:matrix.org). Though note this may differ from time of writing, check the link above to up-to-date details.

The Appservice user is the bot that interacts with the bridge, from a Direct Message with this user you will issue commands to connect to the desired channels and perform specific functions. First, invite the user to a DM:

start_new_chat

inviting_bot_to_dm

Using @oftc-irc:matrix.org we start a chat, your first message can be anything to create the room. The bot should join the room and then be responsive to commands.

bot_joined_dm

Matrix IRC Bridge Bot Command Overview

Commands to the bot are prefixed with !, to get started try !help, which should result in the bot listing out the available commands for use. You should see something like the below:

Actions

Authentication

Info

Management

These commands only work for bridge administrators.

Using the Matrix IRC Bridge

Depending on your bridge setup you may have multiple IRC Networks accessible from your IRC Bridge bot, if so, you will need to specify the IRC Network after the each command. This guide is using @oftc-irc:matrix.org which is dedicated to the W3C IRC network so commands do not need to specify.

For any command given arguments wrapped in [] are optional, make sure to specify them if required for your usecase.

Joining a IRC Channel

The most basic usage of the bridge is to join IRC channels to talk with IRC users, you can do this with the !join command. Simply specify the channel you'd like the join:

join_command

The first time you run such a command, the bot will connect to the IRC network, then inform you that you are connected. The nickname your user appears as in IRC is dependant on the bridge's configuration. Using the example above, you can see [m] has been appended to the users Matrix display name.

If the Channel you are joining hasn't yet been joined via the bot, it will create a Matrix room linking it with the IRC Channel. If the room already exists, the command will simply invite you to the already created room. Likewise, if the Channel doesn't yet exist on the IRC Network, it will be created and your user sent an invite.

You will then recieve an invite to a Matrix room, connected to that IRC Channel.

invite_by_bot_to_room

Once you've joined the room, you can then communicate with others within the channel.

messaging_in_matrix

messaging_in_irc

Listing joined IRC Channels

After joining a number of IRC Channels you may want to retrieve a list of all the Channels you are joined to, and the associated Matrix rooms. You can do this with the !listrooms command. The bot will respond including clickable links to jump straight to the Matrix room.

list_command

Staying active

You can use the !active command to mark yourself as active, which will exclude you from any idleness kicks.

active_command

Changing your Nickname

To change the nickname presented to IRC users, simply use !nick. Provide your desired nickname and it will be updated on the IRC Network, you can also not provide any nickname for the bot to output your current nickname.

nick_command

changing_nickname

irc_nickname_change

Finding out more information on IRC / Matrix users

You can use the !whois command, supplying either a Matrix ID to retrieve their IRC nickname, or a IRC nickname to information on what channels that user is in. The !whois command is also useful to test your connection to the IRC network, supply your own Matrix ID and if there's any issues with the connection the command will produce an error.

whois_command

Direct Messaging between Matrix and IRC

You can start a DM with an IRC user by simply clicking there profile icon from an existing room linked to an IRC Channel. Then from their profile panel, click Message to start a chat. Enter a message to create the room (note they will not see this message), then wait for there user to join the room - once joined, you can send a message which will then be sent to the IRC user.

IRC users can also start DMs with Matrix users, they can do this by double clicking the Matrix users' name within the participants list of a channel, or if supported by your client, using the /query NICKNAME or /msg NICKNAME MESSAGE commands. Once a message is sent, the Matrix user will receive an invite from them to start chatting.

irc_user_dm_invite

If you know the configuration of your bridge (or by checking existing IRC users), you can also manually start a DM with a user. Simply start a new chat using the username format the bridge uses. In the example above we can see that the format is @_oftc_NICKNAME:matrix.org. So we can initiate chats with any nickname by following that format.

Leaving an IRC Channel

Leaving a Channel is simply a case of leaving the Matrix room. Find the room in the Left Panel, hoover over its name, then click the 3-dot menu then Leave.

room_3_dot_menu

Leaving all IRC Channels

If you wish to disconnect from IRC and leave all Channels (/ Matrix linked rooms) you can simply issue the !quit command. Doing so will remove you from all the rooms, you can find them again at the bottom of the Left Panel under Historical.

quit_command

Advanced Bridge Usage

IRC Authentication

If you need to join the IRC Network using authentication credentials you will need to use the !storepass and possibly !username commands. With these you can set NickServ / SASL password and username respectively. Once completed, simply use !reconnect to rejoin the network with the provided credentials.

You can also remove your stored password using, you will then need to use !reconnect to rejoin without the credential:

Troubleshooting bridge problems

If you are encountering issues with the bridge, first try using !reconnect, to see if disconnecting and reconnecting solves your issues. Otherwise !bridgeversion is a useful command to advise the version of the bridge. Supply this information, alongside any debug logs to the administrator of the bridge to help them troubleshoot your issue.

reconnect_and_bridgeversion_commands

Sending raw IRC commands

It's possible to use the bot to issue raw IRC commands, to do so you'll need to use !cmd, followed by the commmand (in CAPS) and any additional arguments. Unless there is an error with the command, sending !cmd will not produce a reply.

For example, if you wanted to send a private message without creating DM in Matrix, you could use the /PRIVMSG IRC command. To do so you'd send:

!cmd PRIVMSG USERNAME MESSAGE

The recipient will then receive the message, but a room in Matrix wont have been created.

Unlinking an IRC channel from a Matrix room

You can find the matrix room id by accessing the room's settings page, then within the Advanced section you will find the Internal Room ID.

room_setting_menu

advanced_settings

Using the Matrix IRC Bridge as an End User

If your homeserver has the Matrix IRC Bridge configured it will pass messages to and from IRC. Depending on your homeservers' IRC bridge configuration you will interact with IRC through various means; for instance your homeserver may have pre-configured Matrix Rooms bridged to IRC Channels; you may have the ability to join / create bridged rooms dynamically; or you may use private messaging to speak directly with a specific user in IRC.

Getting Started

Joining your first IRC Channel via a bridged Matrix Room

To start, the most basic usage of the IRC bridge would be to join an IRC Channel to communicate with both Matrix and IRC users together. Your homeserver administrators will have preconfigured bridging from specific IRC Channels to Matrix Rooms, they should be able to advise which rooms you should initially join, for instance, a #welcome Channel / Room.

When you join a bridged room and send a message for the first time, you'll be sent an invitation to a DM with your homeservers' IRC Bridge Bot. The Matrix User ID of the bridge bot is configurable by your homeservers administrator, but the DM room should be called IRC Bridge status prepended with the IRC Network name that the room was bridged to.

This room will allow you to keep check on your connection to the IRC network, the initial message from the bridge bot should confirm you connected successfully and the nick name in IRC you have connected as. This is customisable by your homeserver admin, in this guides' example environment, you can see Matrix users appear in IRC as their Display Name followed by [m].

Messaging in IRC Channels

Once you have joined a bridged Matrix Room you're already able to communicate with any IRC users connected to the IRC Channel bridged with the room. You can send messages, emoji 👋, even upload attachments or send voice messages. So what does an IRC user see?

While Matrix messages can be formatted in a number of ways, supporting Markdown and HTML, IRC messaging is mostly simple text. You'll find sending simple text messages and emoji works best whereas Markdown and HTML, whilst it will be sent, may not be correctly rendered in an IRC client.

When sending attachments, voice messages, and multi-line messages (if restricted by your homeserver) IRC users will instead see a message that you uploaded a file, a voice message or a truncated version of your multi-lined messages each with a link to download / listen / view.

From the below examples, of the Element Matrix and mIRC IRC clients respectively, you can see differences in how messages are rendered, that reactions are not supported in IRC etc.

Private Messaging IRC Users

So long as private messaging is enabled by your administrator you can do so just like with any other Matrix user. IRC users appear in Matrix as Matrix users, you can view the list of people in a room by clicking the i icon in the top-right of the client, then selecting People. Here you can see all users within the room, including those users created to represent IRC users. The format for their Matrix User IDs is configured by your homeserver administrator, but is usually prefixed with irc_ followed by their IRC nick name.

Just like with any other Matrix user; you can click on a person from this pane; click on their profile picture next to any message they've sent within the room; or simply search for them to initiate the DM. Compose your initial message and send to start a Direct Message with the IRC user. IRC user can likewise start a private message with you, using your IRC nickname - if they do, you will be invited to a DM just like any other Direct Message.

Going Further

Changing your IRC Nickname

If permitted, you may wish to change the nick name used when you connect to the IRC Network. You can do this by speaking with the bridge bot within the IRC Bridge status room you were invited too. Don't worry if you left the room, simply invite the bridge bot into a new DM and it'll work just the same.

You can do this by sending !nick to the bot, you'll notice the bot will respond advising on how to format the command to change your nick name and supply the nick name your are currently using on each connect IRC Network.

Joining an as-yet unbridged IRC Channel

If permitted, you may want to join a conversation within an IRC Channel, not yet bridged to any specific Matrix room. Just like with changing your nick name, you can do this by speaking with the bridge bot within the IRC Bridge status room you were invited too.

Send the !join [irc.example.net] #channel [key] command, making sure to specify the IRC Network if there are multiple, then the IRC Channel name. Make sure to include the key if needed. A complete command to join the #locked IRC Channel requiring a key of password would look like, !join irc.example.com #locked password.

Assuming you have permission to use the !join command, and that the channel specified is not excluded, you will recieve an invite to the newly created room for the specified IRC Channel.

Using the bridge bot

To delve deeper into using the bridge bot and it's commands, or for a more in-depth doc on the IRC Bridge, you can check out Using the Matrix IRC Bridge.

Using the Matrix XMPP Bridge as an End User

If your homeserver has the Matrix XMPP Bridge configured it will pass messages to and from XMPP. You will interact with XMPP by; joining Matrix Rooms specifically bridged to existing XMPP rooms; speaking with XMPP users who have joined public Matrix rooms; or you may use private messaging to speak directly with a specific user in XMPP.

Getting Started

Messaging in public Matrix Rooms

To start, the most basic usage of the XMPP bridge would be to join a Public Matrix room that XMPP users also join to communicate. You or your homeserver administrators will have created a Public room, which XMPP users can search for using a configured endpoint, by default matrix instead of conference.

That's it, by messaging in this room, anyone who is joined from XMPP will be able to see and respond to your messages. As far as how you appear in XMPP, you'll be displayed in room member lists using your Matrix display name, with a full username formatted based on how your homeserver administrators configured. Usually in a format like DISPLAYNAME_HOMESERVER@EXTERNALCOMPONENT.XMPPSERVER, so an example user would look like:

alice_example.com@matrix.xmpp.example.com

In Matrix, XMPP users will appear with Matrix User IDs, following a format like @PREFIX_USERNAME=40XMPPSERVER:HOMESERVER, so an example user would look like:

@xmpp_alice=40xmpp.example.com:example.com

However it's unlikely you will ever need to directly type these, you can use your native clients' functions to interact with users, just like any other Matrix user in Element, or XMPP user in your XMPP client.

Messaging in an XMPP room via a bridged Matrix Room

The alternative to speaking with XMPP users in a public Matrix room they join, is to join an existing XMPP room. To do this all you need to know is the XMPP rooms name and how your homeservers have configured the room name format in Matrix. By default, XMPP rooms in Matrix are translated following a format like #PREFIX_XMPPROOMNAME_CONFERENCE.XMPPSERVER:HOMESERVER, so an example room alias would look like:

#_xmpp_exampleroom_conference.xmpp.example.com:example.com

So you can either enter this in the room search prompt, or simply send /join #_xmpp_exampleroom_conference.xmpp.example.com:example.com in any room (nothing is sent to the room you send this to), for the Element Client to automatically join you to the room.

Once joined, exactly as with public Matrix rooms, you can communicate with anyone else in the room just as you normally would in Matrix.

Private Messaging XMPP Users

XMPP users appear in Matrix as Matrix users, you can view the list of people in a room by clicking the i icon in the top-right of the client, then selecting People. Here you can see all users within the room, including those users created to represent XMPP users. The format for their Matrix User IDs is configured by your homeserver administrator, see above for defaults.

Just like with any other Matrix user; you can click on a person from this pane; click on their profile picture next to any message they've sent within the room; or simply search for them to initiate the DM. Compose your initial message and send to start a Direct Message with the XMPP user. A XMPP user can likewise start a private message with you, using your XMPP username - if they do, you will be invited to a DM just like any other Direct Message.

Using the WhatsApp bridge

Overview

This guide describes how to bridge your Element and WhatsApp accounts. This allows you to chat with WhatsApp contacts and groups natively within Element.

Before you can carry out the steps in this guide, ensure you have the following:

Note: When setting up the Whatsapp bridge you will need to scan a QR code generated in Element from your phone. To make this process as easy as possible, we recommend using Element Web for the initial setup, once set up you can then login to any platform with your Element account and use the bridge which you have set up. However, it is possible with two mobile phones if you can quickly take a photo of the QR code with one phone and then scan it with the original phone.

Setting up

Sign into Element Web using your Element username and password.

(If asked to verify your login, see docs on verifying a new login.

Once signed in, start a new direct message with the WhatsApp bridge bot. (It will not work if you create a room with the bridge bot, it needs to be a direct message)

The username of the bot will be @whatsappbot:your.server (for example @whatsappbot:matrix.org)

Ensure that your.server is the homeserver where the bridge is hosted. This may be different to the homeserver hosting your own account.

Click on the suggested WhatsApp bridge bot, and click Go to start the direct message.

scr-20231103-ktgi-new-copy2.png

You will be taken into a new room with the WhatsApp bridge bot. The bot automatically joins the room.

kulm-copy.png

Remaining in the room, send the login command by sending login into the room.

Tip: You can also send the command **help** to get a list of all available commands.

The bot will generate a QR code to scan from WhatsApp on your phone.

scr-20231103-kvet-copy.png

Leaving Element open, open WhatsApp on your phone for the next step

In WhatsApp, tap the three dots (⋮) in the top right corner of the app.

From the drop-down menu tap Linked devices.

scr-20231103-kwvi-new.png

Tap OK to begin scanning the QR code.

Scan the QR code generated by the WhatsApp bot in Element.

The WhatsApp bridge now shows as a linked device in DEVICE STATUS.

If this doesn't work the first time, it is likely that the QR code has expired, you will need to repeat the steps again and scan the QR code before it expires.

scr-20231103-kxmz-new.png

Back in Element, the bridge bot will confirm that you have logged in to WhatsApp.

The bridge then creates rooms to allow you to chat with WhatsApp contacts and groups. By default the bridge automatically creates rooms for people or groups you have interacted with in the last week. Others are created as new messages arrive. See below for how to use bridged rooms.

Note: WhatsApp requires your phone to connect to your WhatsApp account every 14 days to keep the bridge active, otherwise you will need to QR code scan again. So ensure you open the WhatsApp app every 14 days to ensure you are not disconnected.

Using direct messages

The bridge will automatically invite you to new rooms for your recent contacts.

You will be able to see in the upper left-hand corner that WhatsApp contacts automatically have (WA) added to their display name.

To start, click on a room invite and join the room.You will be taken into the new room for your WhatsApp contact.

You can now begin chatting with your WhatsApp contact in the same way as any other Element user.

(Note that the bridge does not support voice or video calling.)

Starting new chats (or resuming older ones that were not automatically set up) can be done with the pm command, followed by the number for the other person in international format. For example to invite whatsapp number +4412345678 you would send the command pm +4412345678 into the WhatsApp bridge bot room.

Tip: Using the list contacts command retrieves your existing WhatsApp contacts, including their numbers. You can then click on the contact and click message to start chatting.

Once the pm command is sent the bridge will invite you to a new room for the WhatsApp chat.

Using rooms

You will automatically be invited to some rooms for WhatsApp group chats that have been automatically created by the bridge. If this has not happened you can manually open an existing group chat.

To open an existing WhatsApp group in Element, you can use the list groups command (send the message list groups into the WhatsApp bridge bot room) to get a list of all WhatsApp groups. All groups will be shown in a list together with their group IDs.

Use the open command, followed by the ID of the group. For example you can see the Office part group chat has the room ID 441234567891-9876543219, so you would send the command open 441234567891-9876543219.

The bridge will then create a room for the group and invite you.

scr-20231107-kcks-copy.png

Disconnecting from WhatsApp

To disconnect WhatsApp from Element enter the logout command, by sending logout into the WhatsApp brtidge bot room. This will remove the linked device from WhatsApp.

As a further option, the connection to WhatsApp can be forcibly disconnected by using the delete-session command. This removes the connection at the Element side but does not perform a graceful logout from WhatsApp.

Once logged out, the delete-all-portals command can be used to clean up rooms previously created by the bridge.

scr-20231107-kfqi-new.png

Using the Telegram Bridge

Overview

This guide describes how to bridge your Element and Telegram accounts. This allows you to chat with Telegram contacts and groups natively within Element.

Before you can carry out the steps in this guide, ensure you have the following:

Setting up

Sign into Element Web using your Element username and password.

(If asked to verify your login, see docs on verifying login.)

Once signed in, start a new direct message with the Telegram bridge bot. (It will not work if you create a room with the bridge bot, it needs to be a direct message)

The username of the bot will be @telegram:your.server (for example @telegram:matrix.org)

Ensure that your.server is the homeserver where the bridge is hosted. This may be different to the homeserver hosting your own account.

Click on the suggested Telegram bridge bot, and click Go to start the direct message.

You will be taken into a new room with the Telegram bridge bot. The bot automatically joins the room.

Remaining in the room, send the login command by sending login into the room.

Tip: You can also send the command **help** to get a list of all available commands.

Then enter the number of the Telegram account you are wanting to connect to in international format e.g +4412345678.

Your Telegram account will then receive a 4 digit login code, enter this code into the Element room to connect.

Note: If you get this wrong the first time, you will need to use the "cancel" command and start again from "login".

Your Telegram account should now be linked to your Element account and the bot should confirm this in your room.

SCR-20231123-nbbs.png

Using direct messages

The bridge will automatically invite you to new rooms for your recent contacts.

To start, click on a room invite and join the room. You will be taken into the new room for your Telegram contact.

You can now begin chatting with your Telegram contacts in the same way as any other Element user.

Note: The bridge does not support voice or video calling.

To start a chat with a new contact, first ensure you have added the contact in your Telegram contacts. If you send your first message from Telegram you will then get a new invite in Element to join the room.

Or it can be done with the pm command, followed by the number for the other person in international format. For example to invite Telegram contact number +4412345678 you would send the command pm +4412345678 into the Telegram bridge bot room.

SCR-20231123-nbzw.png

Using rooms

You will automatically be invited to some rooms for Telegram group chats that have been automatically created by the bridge. If this has not happened you can manually open an existing group chat.