Matrix Transport · rousseau-agent docs

Overview

The Matrix transport (internal/transport/matrix/) speaks the Matrix client-server API directly — no third-party SDK. /sync long-polling for inbound; /rooms/{room}/send/{event_type}/{txn_id} for outbound.

Works against any spec-compliant homeserver: Synapse, Dendrite, Conduit.

Prerequisites

A bot account on the homeserver of your choice. Register through the standard Matrix client or via the homeserver admin API.

An access token for that account. Log the bot into a normal Matrix client once, then copy the token from Settings → Help & About → Access Token. Alternatively, use the login API directly:

curl -X POST https://matrix.org/_matrix/client/v3/login \
  -H 'Content-Type: application/json' \
  -d '{"type":"m.login.password","user":"bot","password":"..."}'

The bot's full MXID (e.g. @rousseau-bot:matrix.org) for own-message echo suppression.

Configuration

matrix:
  homeserver_url: "https://matrix.org"
  access_token: "syt_..."
  user_id: "@rousseau-bot:matrix.org"
  reply_header: ""
  allowlist:
    - "@alice:matrix.org"
    - "@bob:example.com"

Field	Default	Effect
`homeserver_url`	required	Base URL (`https://matrix.org`).
`access_token`	required	Bot user's access token.
`user_id`	empty	Bot user's full MXID. Optional but recommended (own-message echo suppression).
`reply_header`	empty	Prepended to every outbound reply.
`allowlist`	`[]`	MXIDs whose messages are handled.

Command-line

rousseau matrix \
  --homeserver-url https://matrix.org \
  --access-token syt_... \
  --user-id @rousseau-bot:matrix.org \
  --allow @alice:matrix.org

Long-polling

PollTimeout defaults to 30 seconds. The since cursor from every /sync response is stored in memory and used on the next call, so messages are never redelivered across the process lifetime. On restart, the daemon rewinds to the earliest still-live cursor the homeserver returns — this is a normal sync semantic and matches every Matrix client.

Room invitations

The bot must already be a member of any room it should reply in. Invite it from a normal Matrix client. rousseau does not auto-accept invites; join is out-of-scope.

Failure modes

Symptom	Fix
401 on `/sync`	Access token expired or invalidated. Re-login.
Bot never sees a message	Confirm the bot is a member of the room, not just invited.
Own-message echo loop	Set `user_id` in config so rousseau can filter its own messages.