Skip to content

Matrix

Matrix is an open protocol for real-time communication. It is designed to allow users with accounts at one communications service provider to communicate with users of a different service provider via online chat. Upstream docs: https://matrix.org/

Features

  • Matrix API v3 Compliance: Implements the Matrix Client-Server API v3 specification
  • Token-based Authentication: Use pre-generated access tokens or password-based login
  • Room Management: Send messages to specific rooms or all joined rooms
  • Auto-Join: Automatically accepts room invites when rooms are explicitly specified in the configuration
  • TLS Support: Secure connections with optional TLS disabling
  • Idempotent Sending: Uses transaction IDs to prevent duplicate messages

URL Format

matrix://[user:password@]host[:port]/[?rooms=!roomID1[,roomAlias2]][&disableTLS=yes]

If the port is omitted, the default port 443 (HTTPS) is used.

URL Fields

  • User - Username or empty when using access token Default: empty
    URL part: matrix://user:password@host/
  • Password - Password or access token (Required)
    URL part: matrix://user:password@host/
  • Host (Required)
    URL part: matrix://user:password@host/

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • disabletls Default: ❌ No

  • rooms - Room aliases, or with ! prefix, room IDs Default: empty Aliases: room

  • title Default: empty

Authentication

The Matrix service supports two authentication methods:

Token-based Login (Default)

If no user is specified, the password is treated as an authentication token. This allows you to use a pre-generated access token from your Matrix server, which is useful for CI/CD pipelines or when you don't want to store your password. Simply omit the user parameter and provide your access token as the password.

Password Login

If a user and password are both supplied, the service will attempt to authenticate using the m.login.password flow (if supported by your server).

Matrix API v3 Compliance

The Matrix service implements the Matrix Client-Server API v3 specification. All API calls use v3 endpoints:

/_matrix/client/v3/...

HTTP Method

Messages are sent using the PUT method to /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}. This follows the v3 specification for idempotent message sending, ensuring that retrying a request due to network issues won't result in duplicate messages.

Transaction IDs

The service automatically generates and includes a transaction ID (txnId) with each message send request.

This provides:

  • Deduplication: If a request is retried, the server recognizes the same transaction ID and doesn't create duplicate messages
  • Reliability: Safe to retry failed requests without worrying about message duplication

Authorization Header

The service passes the access token via the Authorization: Bearer <token> HTTP header, which is the recommended method per the v3 specification.

Matrix v3 Compliance

As of Matrix Client-Server API v1.11, passing the access token via query parameter is deprecated. The service now exclusively uses the Authorization: Bearer header for all API requests. This ensures compliance with the latest specification and compatibility with Matrix Authentication Service (MAS).

Authorization Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Title Parameter

The Matrix service now supports the title parameter. When provided, the title is prepended to the message body.

With Title

shoutrrr send --title "Notification Title" --message "This is the message body" matrix://...

Output in Matrix:

Notification Title

This is the message body

Rooms

If rooms are not specified, the service will send the message to all the rooms that the user has currently joined.

Otherwise, the service will only send the message to the specified rooms. If the user is not in any of those rooms, but has been invited to any of those rooms, it will automatically accept that invite.

Room Joining

The service will not join any rooms unless they are explicitly specified in rooms. If you need the user to join those rooms, you can send a notification with rooms explicitly set once.

Room Lookup

Rooms specified in rooms will be treated as room IDs if they start with a ! and used directly to identify rooms. If they have no such prefix (or use a correctly escaped #) they will instead be treated as aliases, and a directory lookup will be used to resolve their corresponding IDs.

Auto-prepending: For convenience, rooms that don't start with # or ! will automatically have # prepended. For example, rooms=general becomes rooms=#general. This allows you to use simple channel names without worrying about the prefix.

You can use either rooms (for multiple rooms) or room (for a single room) - both parameters work identically.

URL Encoding

Don't use unescaped # for the channel aliases as that will be treated as the fragment part of the URL. Either omit them or URL encode them, i.e. rooms=%23alias:server or rooms=alias:server

TLS

If you do not have TLS enabled on the server you can disable it by providing disableTLS=yes. This will effectively use http instead of https for the API calls.

Security Risk

Disabling TLS exposes your credentials and messages in plain text over the network. Only use this option in trusted local networks or testing environments.

Examples

Basic Notification

matrix://user:[email protected]

To Specific Room

matrix://user:[email protected]?rooms=!roomID:matrix.example.com

With Room Alias

matrix://user:[email protected]?rooms=%23general:matrix.example.com

Multiple Rooms

matrix://user:[email protected]?rooms=!room1:matrix.example.com,%23room2:matrix.example.com

With Custom Port

matrix://user:[email protected]:8448?rooms=!roomID:matrix.example.com

Without TLS (Not Recommended)

matrix://user:[email protected]?disableTLS=yes&rooms=!roomID:matrix.example.com