Matrix Notifications

Overview

• Source: https://matrix.org/
• Image Support: Yes
• Attachment Support: Yes
• Message Character Limits:
  • Body: 65000
• Build Your Apprise URL

Account Setup

By default, Apprise communicates directly with your Matrix server using the official Client API.

Alternatively, you may use the Matrix Webhook service. At the time of writing, this is still considered late beta. Webhook usage is enabled by specifying ?mode=matrix or ?mode=slack, assuming you have configured the webhook service (for example via https://github.com/turt2live/matrix-appservice-webhooks).

Syntax

Valid syntax is as follows:

• matrix://{user}:{password}@{hostname}/#{room_alias}
• matrixs://{user}:{password}@{hostname}/!{room_id}

You may specify multiple rooms:

• matrixs://{user}:{password}@{matrixhost}/!{room_id}/#{room_alias}/

Note: If no user and/or password is specified, the Matrix registration process may be invoked. Some Matrix servers allow automatic registration of temporary users, depending on server configuration. In most production environments you should always provide both {user} and {password}.

Room Identifiers and Homeserver Behaviour

Matrix supports both:

• Room aliases (prefixed with #)
• Room IDs (prefixed with !)

Room identifiers may include a homeserver component (for example :example.com). In Matrix, room aliases are typically written with a homeserver, and room IDs are generally expected to include one as well.

Examples:

• #general
• #general:example.com
• !abc123
• !abc123:example.com

Default Behaviour (Recommended)

By default, Apprise enforces a homeserver on room identifiers when it is missing.

If you provide:

• #room: it is internally interpreted as #room:{hostname}
• !room: it is internally interpreted as !room:{hostname}

If you explicitly include a homeserver component, Apprise honours it exactly as specified.

Opt-out Behaviour (Compatibility Mode)

You may disable homeserver enforcement by specifying ?hsreq=no. In this setting:

• #room is used exactly as provided.
• !room is used exactly as provided.

This is intended for environments where a reverse proxy, non-standard server behaviour, or strict URL routing makes :homeserver suffixing undesirable.

If you are using room IDs (prefixed with !), note that many Matrix deployments expect fully-qualified room IDs. If your server rejects !room:{hostname} but accepts !room as-is, hsreq=no may be required.

For example; given:

matrix://user:pass@localhost/#room/!abc123

With default behaviour (hsreq=yes):

• #room becomes #room:localhost
• !abc123 becomes !abc123:localhost

With enforcement disabled:

matrix://user:pass@localhost/#room/!abc123?hsreq=no

• #room is used as #room
• !abc123 is used as !abc123

Webhook Mode

When specifying the ?mode= argument, the plugin switches entirely to webhook behaviour and the syntax changes:

• matrix://{user}:{token}@{hostname}?mode=matrix
• matrixs://{token}@{hostname}:{port}?mode=matrix
• matrix://{user}:{token}@{hostname}?mode=slack&format=markdown
• matrixs://{token}@{hostname}?mode=slack&format=markdown

If you use t2bot.io, you may use:

• matrix://{t2bot_webhook_token}
• matrix://{user}@{t2bot_webhook_token}

Or directly:

• https://webhooks.t2bot.io/api/v1/matrix/hook/{t2bot_webhook_token}

Parameter Breakdown

Variable	Required	Description
hostname	*Yes	The Matrix server you wish to connect to.
t2bot_webhook_token	*Yes	Used when leveraging t2bot webhook mode. Acts as hostname in this case.
user	No	The user to authenticate (and/or register) with the Matrix server.
password	No	The password to authenticate (and/or register) with the Matrix server.
port	No	The server port Matrix is listening on. By default matrixs:// uses port 443, while matrix:// uses port 80.
room_alias	No	The room alias to join and notify. It is recommended to prefix with #.
room_id	No	The room ID to join and notify. You must prefix this with !.
thumbnail	No	Displays an image before each notification identifying the notification type. Default is False.
mode	No	Enables webhook mode. Valid values are matrix or slack.
msgtype	No	Matrix message type: text or notice. Default is text.
version	No	Overrides the Matrix Client API version. Supported values are 2 and 3. Default is 3. This does not affect room ID formatting.
hsreq	No	When enabled, enforces Room Version 12 semantics (such as hashed room IDs) as defined in the Matrix v1.17 specification. This patches state-reset vulnerabilities and formalizes room creator power levels. By default, this is set to yes.

Note: If neither a {room_alias} nor a {room_id} is specified, Apprise will query the server for currently joined rooms and notify all of them.

Global Parameters

Variable	Description
overflow	This parameter can be set to either split, truncate, or upstream. This determines how Apprise delivers the message you pass it. By default this is set to upstream 👉 upstream: Do nothing at all; pass the message exactly as you received it to the service. 👉 truncate: Ensure that the message will fit within the service’s documented upstream message limit. If more information was passed then the defined limit, the overhead information is truncated. 👉 split: similar to truncate except if the message doesn’t fit within the service’s documented upstream message limit, it is split into smaller chunks and they are all delivered sequentially there-after.
format	This parameter can be set to either text, html, or markdown. Some services support the ability to post content by several different means. The default of this varies (it can be one of the 3 mentioned at any time depending on which service you choose). You can optionally force this setting to stray from the defaults if you wish. If the service doesn’t support different types of transmission formats, then this field is ignored.
verify	External requests made to secure locations (such as through the use of https) will have certificates associated with them. By default, Apprise will verify that these certificates are valid; if they are not then no notification will be sent to the source. In some occasions, a user might not have a certificate authority to verify the key against or they trust the source; in this case you will want to set this flag to no. By default it is set to yes.
cto	This stands for Socket Connect Timeout. This is the number of seconds Requests will wait for your client to establish a connection to a remote machine (corresponding to the connect()) call on the socket. The default value is 4.0 seconds.
rto	This stands for Socket Read Timeout. This is the number of seconds the client will wait for the server to send a response. The default value is 4.0 seconds.
emojis	Enable Emoji support (such as providing :+1: would translate to 👍). By default this is set to no. Note: Depending on server side settings, the administrator has the power to disable emoji support at a global level; but default this is not the case.
tz	Identify the IANA Time Zone Database you wish to operate as. By default this is detected based on the configuration the server hosting Apprise is running on. You can set this to things like America/Toronto, or any other properly formated Timezone describing your area.

Examples

Send a secure Matrix notification:

# Assuming {hostname} is matrix.example.com
# Assuming {user} is nuxref
# Assuming {password} is abc123
# Notify #general and #apprise
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   matrixs://nuxref:abc123@matrix.example.com/#general/#apprise

Disable homeserver enforcement:

apprise -vv -t "Test Message Title" -b "Test Message Body" \
   matrixs://nuxref:abc123@matrix.example.com/!abc123?hsreq=no

Use API v2 (required for attachments in some deployments):

apprise -vv -t "Test Message Title" -b "Test Message Body" \
   matrixs://nuxref:abc123@matrix.example.com/#general?v=2

Send a t2bot.io webhook request:

# Assuming {webhook} is ABCDEFG12345
apprise -vv -t "Test Message Title" -b "Test Message Body" \
   matrix://ABCDEFG12345