Matrix Output Reference
Matrix output
Section titled “Matrix output”The matrix output sends selected Adder events to one or more Matrix rooms as
plain text m.room.message events. This guide covers configuration,
authentication, room validation, Matrix Client-Server API delivery, retry
behavior, and operational limits.
Prerequisites
Section titled “Prerequisites”- Use a Matrix account with an access token.
- Join the account to every destination room.
- Grant the account permission to send messages in every destination room.
- Prepare a dedicated test room for the live check in this guide.
Configuration
Section titled “Configuration”Select the output with output: matrix and configure its options under
plugins.output.matrix:
output: matrix
plugins: output: matrix: homeserver-url: "https://matrix.example.org" access-token: "<secret-managed-access-token>" room-ids: "!alerts:example.org,!operations:example.org" event-types: "blocks,rollbacks,governance"Store access-token in a secret-managed configuration source. Adder sends the
token as a bearer credential and does not expose it in the message body.
Configuration fields
Section titled “Configuration fields”| Field | Required | Default | Description |
|---|---|---|---|
homeserver-url | Yes | None | Matrix homeserver base URL. Configure HTTPS, or configure HTTP only with localhost, 127.0.0.1, or ::1 for loopback testing. |
access-token | Yes | None | Access token for the Matrix account that sends the messages. |
room-ids | Yes | None | Comma separated Matrix room IDs. Provide at least one ID beginning with !. |
event-types | No | blocks,rollbacks,governance | Comma separated event names to send. |
URL and room validation
Section titled “URL and room validation”Adder validates the configuration before it starts the output:
homeserver-urlmust be a valid HTTP URL without credentials, a query, or a fragment.- Configure
homeserver-urlwith HTTPS for a remote homeserver. Configure HTTP only for loopback testing withlocalhost,127.0.0.1, or::1. access-tokenmust not be empty.room-idsmust contain at least one room ID.- Each room ID must begin with
!and must not contain spaces, tabs, carriage returns, or newlines. - Matrix room version 12 IDs can omit the legacy
:serversuffix.
Adder trims comma separated room IDs before it validates each entry. A room ID that fails validation prevents the output from starting.
Event selection
Section titled “Event selection”By default, Adder sends these event types:
blocksrollbacksgovernance
The event-types option also accepts:
transactionsdrep-registrationdrep-updatedrep-retirement
Adder ignores events outside the configured selection. The option must name at least one supported event type when it is present.
Matrix delivery contract
Section titled “Matrix delivery contract”For each selected event, Adder sends one request to every configured room. The output uses the Matrix Client-Server API room send endpoint:
PUT /_matrix/client/v3/rooms/{room}/send/m.room.message/{txnId}Authorization: Bearer <access-token>Content-Type: application/jsonAdder sends a plain text message in this JSON body:
{ "msgtype": "m.text", "body": "Adder <event-type>\n<event-json>"}<event-type> identifies the selected event, and <event-json> contains the
complete Adder event JSON. Adder creates a transaction ID for each room and
event. It reuses that same transaction ID for every retry of that room and
event, while sends to different rooms use different transaction IDs.
A successful 200 response with an event_id confirms that the homeserver
accepted the request. It does not confirm that a user received or read the
message.
Retry and rate limit behavior
Section titled “Retry and rate limit behavior”Adder makes an initial request and retries a failed delivery up to three times. The output retries these conditions:
- Network or HTTP request errors.
- HTTP
408request timeout responses. - HTTP
5xxserver errors. - HTTP
429rate limit responses.
The output uses exponential backoff between retries. For HTTP 429, Adder
uses a valid Retry-After value when the homeserver provides one. It accepts a
decimal delay in seconds or an HTTP date. Adder also accepts the legacy
retry_after_ms response field when the homeserver omits the header. A rate
limit delay cannot exceed one minute. If no usable rate limit hint exists, Adder
uses its bounded backoff instead.
Other HTTP 4xx responses permanently fail delivery and do not trigger retries.
After the retry limit, Adder reports the delivery failure in the output.matrix
logs and sends it through the output error channel.
Shutdown and restart behavior
Section titled “Shutdown and restart behavior”Shutdown cancels in flight Matrix requests and any retry backoff waits. Adder does not maintain a persistent queue for Matrix messages. Stopping Adder can lose events that remain in flight, and Adder does not replay them after a restart.
Live check
Section titled “Live check”Use a dedicated Matrix account and test room. Do not place a production access token in a test configuration.
- Join the test account to the room and grant it permission to send messages.
- Configure
output: matrixwith the test homeserver, access token, room ID, and one event type. - Start Adder and trigger an event that matches the selected type.
- Confirm that the test room receives an
m.room.messagecontaining the event type and event JSON. - Confirm that Adder reports no output error.
- If delivery fails, check the
output.matrixlogs and verify the token, room membership, send permission, and homeserver URL.
Related references
Section titled “Related references”- Command reference for the Matrix output CLI options.
- Output integration overview for Adder’s CLI event pipeline and output integrations.
Docs authored by Doc Holiday