Usage

Any HTTP client can post to /notify:

# generic message
curl -X POST "http://localhost:5001/notify" \
     -H "Content-Type: application/json" \
     -d '{"body": "Hello from the bridge!"}'

# with a registered service formatter
curl -X POST "http://localhost:5001/notify?service=alertmanager" \
     -H "Content-Type: application/json" \
     -d '{"body": "plain text", "html": "<b>bold text</b>"}'

Query parameters

Parameter	Description
service	Activates a built-in formatter and selects the sender via service_users in config
room	Sends to this Matrix room ID, overriding any server-side routing

The sender (Matrix user localpart and token) is determined server-side: the service_users map in bridge.yml maps each service name to its user localpart. If the service is not listed, default_user is used.

Multi-room routing

By default all messages go to the global room_id in bridge.yml. You can route per service by adding a service_rooms map under server::

server:
  service_rooms:
    alertmanager:
      - "!abc123:matrix.example.org"
      - "!def456:matrix.example.org"
    borgmatic:
      - "!abc123:matrix.example.org"

Room resolution order (first match wins):

1. ?room=<id> — message is sent to exactly this one room, ignoring any config
2. service_rooms[service] — message is sent to all rooms listed for the service
3. matrix.room_id — fallback, single room

Autojoin rooms

When matrix.autojoin: true is set, the bridge joins every configured room at startup on behalf of each bot user. This is useful after adding a new room to service_rooms — instead of manually inviting each bot, the bridge handles it automatically.

matrix:
  autojoin: true

The bridge derives the set of (user, room) pairs from the config:

• default_user joins matrix.room_id
• Each entry in service_rooms is joined by the matching service_users entry, or default_user if no explicit mapping exists

Joining a room the bot is already in is a no-op. If a join fails (e.g. an invite-only room and the bot was never invited), the bridge retries once: default_user sends an invite to the bot, then the join is attempted again. This requires default_user to already have invite permission in that room (moderator-level by default on most homeservers) — if it doesn't, the invite itself fails and both failures are logged as errors, but the bridge still starts.

This invite fallback cannot bootstrap default_user into matrix.room_id itself: the inviter is always default_user, so for its own room that means default_user would have to invite itself, which Matrix does not allow (you need to already be a joined member with invite power to invite anyone). You must manually invite default_user into matrix.room_id before the first startup. The fallback only ever helps other bot users (service bots) — and only once default_user already has invite power in the room they're being invited to.