Skip to content
ChannelWatch

Matrix

Matrix is a decentralized, open-source messaging protocol. ChannelWatch sends notifications to Matrix rooms through Apprise, which handles the Matrix client API calls for you.

What you need

Section titled “What you need”
  • A Matrix account on any homeserver (matrix.org, your own Synapse instance, etc.)
  • The homeserver hostname (e.g. matrix.org, matrix.example.com)
  • Your Matrix username and password
  • The room ID or room alias of the room you want to notify

Room ID vs room alias

Section titled “Room ID vs room alias”

Matrix has two ways to identify a room:

Format Example Notes
Room alias #general:matrix.org Human-readable, starts with #
Room ID !abc123xyz:matrix.org Permanent internal ID, starts with !

Room aliases can change or be deleted. Room IDs are permanent. Either works with ChannelWatch, but the room ID is more reliable for automation.

To find a room’s ID in Element: open the room, go to Room Settings > Advanced, and copy the Internal room ID.

URL format

Section titled “URL format”

The dedicated Matrix field accepts the credential path after matrix://; ChannelWatch prepends that scheme. Enter values in this form:

<matrix-user>:<matrix-password>@homeserver/#room-alias
<matrix-user>:<matrix-password>@homeserver/!room-id

Examples:

# matrix.org account, room alias
<matrix-user>:<matrix-password>@matrix.org/#channelwatch-alerts


# Self-hosted homeserver, room ID
<matrix-user>:<matrix-password>@matrix.example.com/!abc123xyz:matrix.example.com


# Multiple rooms in one URL
<matrix-user>:<matrix-password>@matrix.example.com/#general/!abc123xyz:matrix.example.com

Add Matrix in the web UI

Section titled “Add Matrix in the web UI”
  1. Open the ChannelWatch web UI at http://your-server-ip:8501
  2. Go to Settings > Notifications and stay on the Global scope
  3. Enable Matrix and enter the credential path in the format above, without a matrix:// prefix
  4. Click Save, then open Diagnostics, find Diagnostic Tests > Notifications, and send a test notification

Add Matrix via environment variable

Section titled “Add Matrix via environment variable”

For headless or automated deployments, set CW_APPRISE_MATRIX in your compose file:

environment:
  CW_APPRISE_MATRIX: "<matrix-user>:<matrix-password>@matrix.example.com/#channelwatch-alerts"

ChannelWatch prepends matrix:// automatically, so you only provide the part after the scheme.

For a homeserver that requires matrixs://, configure the complete secure URL through CW_APPRISE_CUSTOM instead:

environment:
  CW_APPRISE_CUSTOM: "matrixs://<matrix-user>:<matrix-password>@matrix.example.com/#channelwatch-alerts"

Troubleshooting room joins

Section titled “Troubleshooting room joins”

“Room not found” or no notification arrives

Section titled ““Room not found” or no notification arrives”

Apprise joins the room automatically on first use. If the join fails:

  1. Confirm the room alias or ID is correct. Copy it directly from Element rather than typing it.
  2. Check that the room allows new members to join. Private rooms require an invite first. Invite your Matrix account to the room, then retry.
  3. Verify your homeserver hostname matches the one your account is registered on. A matrix.org account cannot authenticate against matrix.example.com.

Federated room IDs

Section titled “Federated room IDs”

If the room is on a different homeserver than your account, include the full server suffix in the room ID:

<matrix-user>:<matrix-password>@matrix.example.com/!abc123xyz:other-server.org

Without the suffix, Apprise assumes the room is on your homeserver and the join will fail.

Test the URL directly

Section titled “Test the URL directly”

Run a quick connectivity check from the container:

Terminal window
docker exec channelwatch python -c "
import apprise
a = apprise.Apprise()
a.add('matrixs://<matrix-user>:<matrix-password>@matrix.example.com/#channelwatch-alerts')
print(a.notify(title='Test', body='ChannelWatch test'))
"

A result of True means the notification was accepted by the homeserver. Check the room in your Matrix client to confirm delivery.

Section titled “Related pages”