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 options to disable TLS or skip certificate verification
  • Idempotent Sending: Uses transaction IDs to prevent duplicate messages

URL Format

matrix://[user:password@]host[:port]/[?rooms=!roomID1[,roomAlias2]][&disabletls=yes][&skiptlsverify=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 - Connect over HTTP instead of HTTPS Default: ❌ No

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

  • skiptlsverify - Skip TLS certificate verification Default: ❌ No

  • title - Notification title, optionally set by the sender 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). The first send logs in. Later sends reuse that login while the homeserver, user, and password stay the same. When code changes the service's config to another homeserver or account, the next send logs in again, so an access token only goes to the homeserver that issued it.

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

Rate Limits

A homeserver that rate-limits a request answers with a 429 status and says how long to wait. Shoutrrr waits that long and sends the request again, up to three times. It reads the wait from the Retry-After header, in seconds or as a date, and falls back to the deprecated retry_after_ms field of the error body. A wait that would end after the send's deadline fails the request at once. Waits count toward the send's time budget, and each room keeps its share of it. A message send keeps its transaction ID, so a retry cannot post the message twice.

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. When the user has joined no room, the send fails.

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. A disabletls send param applies to that send only, including a login the send makes. The first send without TLS logs a warning.

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.

Set skiptlsverify=yes when the homeserver's certificate cannot be verified, such as a self-signed one on its reverse proxy. The connection stays encrypted, but Shoutrrr does not check which server it talks to. A skiptlsverify send param also applies to that send only, including a login the send makes. A custom HTTP client set through SetHTTPClient keeps its own TLS settings, so skiptlsverify does not change it. The first send that skips certificate verification through Shoutrrr's own client logs a warning.

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