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

• 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

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

ChannelWatch uses Apprise’s matrix:// URL syntax. The format depends on whether your homeserver uses HTTP or HTTPS:

# HTTPS homeserver (recommended)
matrixs://username:password@homeserver/#room-alias
matrixs://username:password@homeserver/!room-id

# HTTP homeserver (uncommon, self-hosted only)
matrix://username:password@homeserver/#room-alias

Examples:

# matrix.org account, room alias
matrixs://alice:s3cr3t@matrix.org/#channelwatch-alerts

# Self-hosted homeserver, room ID
matrixs://alice:s3cr3t@matrix.example.com/!abc123xyz:matrix.example.com

# Multiple rooms in one URL
matrixs://alice:s3cr3t@matrix.example.com/#general/!abc123xyz:matrix.example.com

Note

The matrixs:// scheme uses HTTPS (port 443). Use matrix:// only for homeservers that don’t have TLS configured. Most public homeservers, including matrix.org, require HTTPS.

Add Matrix in the web UI

1. Open the ChannelWatch web UI at http://your-server-ip:8501
2. Go to Settings > Notifications > Matrix
3. Enter your Apprise URL in the format above
4. Click Save, then use Diagnostics > Alert Tests to send a test notification

Add Matrix via environment variable

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

environment:
  CW_APPRISE_MATRIX: "alice:s3cr3t@matrix.example.com/#channelwatch-alerts"

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

Caution

Credentials in environment variables are visible to anyone who can run docker inspect on the container. For shared hosts, prefer the web UI, which stores credentials encrypted in /config/settings.json.

Troubleshooting room joins

”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

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

matrixs://alice:s3cr3t@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

Run a quick connectivity check from the container:

docker exec channelwatch python -c "
import apprise
a = apprise.Apprise()
a.add('matrixs://alice:s3cr3t@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.

Next steps

• Delivery Log - review sent notification history
• Custom (Apprise) - use any other Apprise-supported service