Skip to content

Matrix Output Reference

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.

  • 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.

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.

FieldRequiredDefaultDescription
homeserver-urlYesNoneMatrix homeserver base URL. Configure HTTPS, or configure HTTP only with localhost, 127.0.0.1, or ::1 for loopback testing.
access-tokenYesNoneAccess token for the Matrix account that sends the messages.
room-idsYesNoneComma separated Matrix room IDs. Provide at least one ID beginning with !.
event-typesNoblocks,rollbacks,governanceComma separated event names to send.

Adder validates the configuration before it starts the output:

  • homeserver-url must be a valid HTTP URL without credentials, a query, or a fragment.
  • Configure homeserver-url with HTTPS for a remote homeserver. Configure HTTP only for loopback testing with localhost, 127.0.0.1, or ::1.
  • access-token must not be empty.
  • room-ids must 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 :server suffix.

Adder trims comma separated room IDs before it validates each entry. A room ID that fails validation prevents the output from starting.

By default, Adder sends these event types:

  • blocks
  • rollbacks
  • governance

The event-types option also accepts:

  • transactions
  • drep-registration
  • drep-update
  • drep-retirement

Adder ignores events outside the configured selection. The option must name at least one supported event type when it is present.

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/json

Adder 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.

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 408 request timeout responses.
  • HTTP 5xx server errors.
  • HTTP 429 rate 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 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.

Use a dedicated Matrix account and test room. Do not place a production access token in a test configuration.

  1. Join the test account to the room and grant it permission to send messages.
  2. Configure output: matrix with the test homeserver, access token, room ID, and one event type.
  3. Start Adder and trigger an event that matches the selected type.
  4. Confirm that the test room receives an m.room.message containing the event type and event JSON.
  5. Confirm that Adder reports no output error.
  6. If delivery fails, check the output.matrix logs and verify the token, room membership, send permission, and homeserver URL.

Doc Holiday logo

Docs authored by Doc Holiday