Matrix bridge (Matrix-Brücke)

The Matrix bridge connects a chat room in Coviqo with a room on any Matrix homeserver – for example matrix.org or your community's own server. Messages written in one place appear in the other: people on Matrix keep using their Matrix app (Element, FluffyChat …), people in Coviqo keep using Coviqo.

You find it under Space settings → Apps & integrations → Matrix bridge. You need to be an owner or administrator of the space (permission Manage space).

Before you start#

• Plan: the bridge is included from Community Pro (Free: not available). The plan decides how many rooms of a space can be connected.
• Organisation policy: companies can forbid bridges (Organisation → Policies → Allow Matrix bridges; the presets Medium and Closed switch it off). If it is off, no room of the organisation's spaces can be connected, and messages of managed members are never relayed to Matrix – from any space.
• A bot user on Matrix: create a dedicated Matrix user for the bridge on the homeserver of your choice (not your personal account) and get its access token (in Element: Settings → Help & About → Access token, or through the login API). Everything this user can see in connected rooms is relayed to Coviqo.
• Unencrypted rooms only: end-to-end encrypted Coviqo rooms and encrypted Matrix rooms cannot be connected.

Setting it up#

1. Switch on Matrix bridge in this space.
2. Click Add bot account and enter the homeserver address (e.g. https://matrix-client.matrix.org) and the access token. Coviqo checks the token with the homeserver and shows the Matrix user it belongs to. The token is stored encrypted and never shown again.
3. Click Connect room:
   • choose the Coviqo room and the bot account,
   • enter the Matrix room: #room:example.org (address) or !id:example.org (room ID); a matrix.to link works too. For a private Matrix room, invite the bot user there first,
   • optionally tick Import the last 50 Matrix messages,
   • read the notice – messages of this room are transferred to the homeserver – and confirm it.
4. The bot joins the Matrix room. From now on messages are relayed in both directions.

What is relayed#

Mentions become plain names (@Dana). People on Matrix cannot ping anybody in Coviqo, and @everyone from Matrix does nothing. Messages from Matrix cannot be edited in Coviqo; moderators can delete them (this removes them in Coviqo only).

The room notice#

Everybody in a connected room sees: "This room is connected with Matrix – messages are transferred to <homeserver>". Keep in mind that what you write there leaves Coviqo: the Matrix network distributes it to all servers taking part in the room. Deleting a message in Coviqo also removes its copy on Matrix, but copies that were already relayed stay on Matrix when a Coviqo account is deleted.

Status and problems#

Each bot account and each connection shows its state – Active, Degraded, Paused or Error – and when something was last relayed:

• Token invalid – the token was revoked or expired: use Replace token (same Matrix user).
• The homeserver is rate limiting / not reachable – Coviqo retries automatically.
• The Matrix room is encrypted now / The room is end-to-end encrypted now – not supported; disconnect the room.
• The bot is no longer in the Matrix room / may not write – invite the bot again or give it the right to write, then switch the connection on again.

Switching a connection off pauses it; messages written during a pause are not relayed later. Disconnect stops relaying for good, the bot leaves the Matrix room, and messages relayed so far stay on both sides. Remove bot account disconnects all its rooms and deletes the token in Coviqo – revoke it on the homeserver as well.