Skip to main content

Using the Matrix XMPP 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.