Skip to content
Reoclo Reoclo Reoclo Docs

Matrix Notifications

Reoclo delivers Matrix notifications as m.notice messages from a bot user on your homeserver. A severity icon leads each message: red for critical, yellow for warnings, blue for info, green for recoveries. Reoclo talks directly to your homeserver. No third-party relay sits between.

Prerequisites

Section titled “Prerequisites”
  • A Matrix homeserver that Reoclo can reach over HTTPS (Synapse or any compatible server)
  • Permission to create a user on that homeserver
  • A room for the alerts

If you do not have a homeserver yet, you can deploy Matrix Synapse with Reoclo. Open the Service Directory and search for Synapse.

Step 1: Create the bot user

Section titled “Step 1: Create the bot user”

Create a dedicated user for Reoclo, for example reoclo-bot. Do not reuse a personal account.

On Synapse, run this command on the server:

Terminal window
register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008

Answer the prompts with the bot’s username and a strong password. Answer no when it asks to make the user an admin.

Step 2: Get an access token

Section titled “Step 2: Get an access token”

Log in as the bot and read the access_token field from the response:

Terminal window
curl -s -X POST https://matrix.example.com/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "m.login.password",
    "identifier": {"type": "m.id.user", "user": "reoclo-bot"},
    "password": "<bot-password>",
    "initial_device_display_name": "Reoclo alerts"
  }'

You can also log in as the bot in Element and copy the token from Settings → Help & About.

If you later log the bot out of that session, the homeserver revokes the token and deliveries stop.

Step 3: Invite the bot and copy the room ID

Section titled “Step 3: Invite the bot and copy the room ID”
  1. In Element, open the alert room.
  2. Invite the bot user, for example @reoclo-bot:example.com.
  3. Open Room Settings → Advanced.
  4. Copy the Internal room ID. It starts with !.

Nobody has to accept the invite. Reoclo joins the bot automatically on the first send.

Step 4: Create the channel in Reoclo

Section titled “Step 4: Create the channel in Reoclo”

Dashboard

Section titled “Dashboard”
  1. Open Settings → Notification Channels.
  2. Click Add Channel → Matrix.
  3. Give it a name (for example, ops-room).
  4. Enter the Homeserver URL and the Room ID.
  5. Paste the token into Access Token.
  6. Click Send Test. A [TEST] message appears in the room within a second.
  7. Pick which events this channel receives.
  8. Save.

CLI

Section titled “CLI”
Terminal window
reoclo channels create matrix \
  --name "ops-room" \
  --config homeserver_url=https://matrix.example.com,room_id='!abcdef:example.com' \
  --secret "<access-token>" \
  --events deploy_failed,monitoring_uptime_down,incident_created

Quote the room ID. The ! character triggers history expansion in bash and zsh.

Or via YAML:

kind: matrix
name: ops-room
config:
  homeserver_url: https://matrix.example.com
  room_id: "!abcdef:example.com"
secret: ${env:MATRIX_ACCESS_TOKEN}
events:
  deploy_failed: true
  monitoring_uptime_down: true
Terminal window
MATRIX_ACCESS_TOKEN="syt_..." \
  reoclo channels create matrix --from-file matrix-alerts.yaml

Message format

Section titled “Message format”

Each notification is one m.notice message with two renderings. Clients that render HTML show a bold title, label/value facts, and a code block. All other clients show an equivalent plain-text body. Other bots and bridges ignore m.notice messages, so alerts cannot start a reply loop.

SeverityIcon
critical🔴
warn🟡
info🔵
recovery🟢

The channel accepts the room ID only (!abcdef:example.com), not a room alias (#alerts:example.com).

Troubleshooting

Section titled “Troubleshooting”
SymptomCauseFix
403 M_FORBIDDENThe bot was never invited to the roomInvite the bot user, then send the test again
401 M_UNKNOWN_TOKENThe token was revoked, or the bot session was logged outLog in again and update the channel secret
429 M_LIMIT_EXCEEDEDThe homeserver rate limit was hitFor one alert bot, the Synapse defaults are enough. Raise rc_message in homeserver.yaml if you burst
Alerts show a red warning shieldThe room is encrypted, alerts are notCreate an unencrypted room for alerts
Message renders without formattingThe client does not render HTMLExpected. The plain-text body carries the same content
Test passes, real events silentEvent toggles disabledOpen the channel and enable the events you want

Routing tips

Section titled “Routing tips”
  • One room per concern. Separate rooms for deploys, monitoring, and incidents keep the signal high.
  • The bot posts notices. Notices do not trigger normal notification sounds in most clients. Set the room to All messages if you want a ping per alert.
  • Reuse the bot across rooms. One bot user and one token can serve many channels. Give each channel its own room ID.

Next Steps

Section titled “Next Steps”