Matrix

Connecter PRX a the Matrix network en utilisant le Client-Server API with optional de bout en bout encryption (E2EE) and room-based messaging.

Prerequis

• A Matrix homeserver (e.g., matrix.org, or self-hosted Synapse/Dendrite)
• A bot account sur le homeserver avec unn access token
• The room ID where le bot should listen
• PRX built avec le channel-matrix feature flag

Quick Setup

1. Create a Bot Account

Create an account on your Matrix homeserver for le bot. You can use Element or la commande line:

# Using curl against the homeserver API
curl -X POST "https://matrix.org/_matrix/client/v3/register" \
  -H "Content-Type: application/json" \
  -d '{"username": "prx-bot", "password": "secure-password", "auth": {"type": "m.login.dummy"}}'

2. Get an Access Token

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

3. Invite the Bot vers un Room

From your Matrix client, invite le bot account vers le room where it should operate. Nonte the room ID (format: !abc123:matrix.org).

4. Configure

[channels_config.matrix]
homeserver = "https://matrix.org"
access_token = "syt_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
room_id = "!abc123def456:matrix.org"
allowed_users = ["@alice:matrix.org", "@bob:matrix.org"]

5. Verify

prx channel doctor matrix

Configuration Reference

Champ	Type	Defaut	Description
homeserver	String	required	Matrix homeserver URL (e.g., "https://matrix.org")
access_token	String	required	Matrix access token for le bot account
user_id	String	null	Matrix user ID (e.g., "@bot:matrix.org"). Used for session restoration
device_id	String	null	Matrix device ID. Used for E2EE session continuity
room_id	String	required	Room ID to listen in (e.g., "!abc123:matrix.org")
allowed_users	[String]	[]	Allowed Matrix user IDs. Empty = deny all. "*" = allow all

Fonctionnalites

• End-to-end encryption -- supports encrypted rooms using matrix-sdk with Vodozemac
• Room-based messaging -- listens and responds in a specific Matrix room
• Message reactions -- reacts to messages to acknowledge receipt and completion
• Read receipts -- sends read receipts for processed messages
• Session persistence -- stocke crypto sessions locally for E2EE continuity across restarts
• Homeserver agnostic -- works avec unny Matrix homeserver (Synapse, Dendrite, Conduit, etc.)

Limiteations

• Currently listens in un seul room (set via room_id)
• Requires the channel-matrix feature flag a la compilation
• E2EE key backup and cross-signing verification are not yet supported
• Large rooms with high message volume may increase resource usage
• Le bot doit etre invited vers le room before it can listen

Depannage

Bot ne fait pas respond in encrypted rooms

• Ensure user_id and device_id are set for proper E2EE session management
• Delete the local crypto store and restart to re-establish encryption sessions
• Verify le bot account a ete verified/trusted by room members

"Room not found" error

• Confirm the room ID format is correct (! prefix, :homeserver suffix)
• Ensure le bot a ete invited to and has joined the room
• Room aliases (e.g., #room:matrix.org) ne sont pas pris en charge; use the room ID

Access token rejected

• Access tokens can expire; generate un nouveau one via le journalin API
• Ensure le token belongs vers le correct homeserver