Matrix

Client-Server API を介したフェデレーション Matrix プロトコル。インバウンドはロングポーリングデーモンとして動作し、HTTP webhook のエントリーポイントはありません。

🟡 アウトバウンド送信対応、インバウンドはロングポーリングデーモン経由。 Matrix はフェデレーションのため、単一の webhook URL は存在しません。Minara は /sync デーモンを起動し、イベントを Agent にストリーミングします。プレーンテキストのルームのみ対応しており、エンドツーエンド暗号化 (E2EE) ルームは現在サポートされていません。

できること

アウトバウンドテキスト送信 は Client-Server API で行います。
PUT /_matrix/client/v3/rooms/{roomId}/send/m.room.message/{txnId}
に Authorization: Bearer <access_token> と {msgtype:"m.text", body} を指定します。
ロングポーリングデーモン経由のインバウンド受信。 MESSAGING_MATRIX_INBOUND=1 を設定すると、Minara は GET /sync?since=<batch>&timeout=30000 のループを開きます。イベントは MATRIX_DEFAULT_ROOM_ID に指定したルームからのメッセージのみに絞り込まれます（セキュリティ上の修正により、参加中の全ルームからイベントを発行しない設計です）。
カーソルのディスク永続化。 <dataDir>/matrix-sync.json に保存されるため、再起動後も最後の next_batch から再開でき、過去のメッセージを再生しません。
テキストのみ対応。 画像・ファイルイベントは破棄されます。
65,000 文字のテキスト上限（Matrix 自体の制限です）。

セットアップ

1. Matrix アカウントを作成または取得する

matrix.org、自前の Synapse、Dendrite など、どの homeserver でも利用できます。Matrix クライアント（Element、Cinny など）で一度ログインしてください。

2. 長期アクセストークンを生成する

Element からコピーする方法が最も簡単です。

Element デスクトップ版 / Web 版: 設定 → ヘルプ & バージョン情報 → アクセストークン
（「詳細設定」の下に隠れています。展開してください）

または curl でも取得できます。

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

レスポンスとして {access_token, user_id, ...} が返ります。

以下の値を保存してください。

MATRIX_HOMESERVER（URL 例: https://matrix.org）
MATRIX_ACCESS_TOKEN（bearer トークン）
MATRIX_USER_ID（例: @bot:matrix.org）

3. 対象ルームに参加する

Bot アカウントから、Agent に監視させたいルームに参加します。ルーム ID を確認してください（Element: ルーム → 設定 → 詳細設定 → 「内部ルーム ID」）。!abc:matrix.org のような形式で表示されます。これを MATRIX_DEFAULT_ROOM_ID として保存します。

4. Minara を設定する

minara auth messaging add
# リストから `matrix` を選び、homeserver の URL、アクセストークン、
# ユーザー ID、デフォルトルーム ID を貼り付けます。

または環境変数で直接指定することもできます。

MATRIX_HOMESERVER=https://matrix.org
MATRIX_ACCESS_TOKEN=syt_...
MATRIX_USER_ID=@bot:matrix.org
MATRIX_DEFAULT_ROOM_ID=!abc:matrix.org

5. インバウンドを有効にする（任意）

MESSAGING_MATRIX_INBOUND=1

この設定をすると、Agent の起動時にロングポーリングデーモンも一緒に起動します。設定がない場合、Matrix はプッシュ送信のみとなります。

6. テストする

minara auth messaging test matrix

`/sync` の仕組み（ロングポーリングデーモン）

デーモンはバックグラウンドで動作し、homeserver に対してロングポーリングリクエストを送り続けます。

GET /sync?timeout=30000&since=<next_batch>&filter={"room":{"timeline":{"types":["m.room.message"]}}}

新しいイベントが届くか 30 秒のタイムアウトが切れるまで接続を保持し、イベントと新しい next_batch カーソルを返します。

3 つのガードレールを設けています。

初回同期での履歴破棄。 初回インストール時はカーソルがないため、通常は /sync がルームのタイムライン全体を返します。デーモンはこの初回バッチを破棄し、next_batch トークンのみ保存します。これにより、初回起動時に古いメッセージが再生されるのを防ぎます。
ルームスコープフィルター。 MATRIX_DEFAULT_ROOM_ID のイベントのみが Agent に転送されます。この制限がなければ、Bot が参加している全ルームから返信がトリガーされる可能性があり、共有環境でのプライバシーやスコープ上のリスクになります。
自己ループガード。 sender === MATRIX_USER_ID のイベントは除外されます。Bot 自身のアウトバウンド投稿が /sync 経由でラウンドトリップしても、インバウンドのトリガーにならないようにするためです。

再接続: デーモンはネットワーク障害時に、共有の daemon-runner を介してジッター付き指数バックオフ（1 秒 → 30 秒）で再試行します。

制限事項と注意点

エンドツーエンド暗号化 (E2EE) 非対応。 デーモンは m.room.encrypted イベントを無視します。プレーンテキストのルームのみ使用してください。olm / matrix-rust-sdk による E2EE 対応は規模の大きい将来の課題です。
フェデレーションハンドシェイク不要。 Bot は Matrix クライアントとして動作するため、参加していないルームのイベントは受信できません。
クエリパラメーターではなくヘッダーで Bearer を指定。 Matrix の ?access_token= クエリ形式は非推奨です。Minara は Authorization: Bearer を使用します。
帯域幅について。 ロングポーリングは 24 時間 365 日、HTTP 接続を維持し続けます。ほとんどの homeserver では問題になりませんが、ファイアウォールやロードバランサーの設定には注意が必要です（アイドル接続を 60 秒以内にドロップしない設定にしてください）。

トラブルシューティング

「デーモンが起動しない」

MESSAGING_MATRIX_INBOUND が設定されていません。1 に設定して再起動してください。

「デーモンがイベントを発行しない」

Bot が MATRIX_DEFAULT_ROOM_ID のルームに参加していません。Element または GET /joined_rooms で確認してください。
ルームが暗号化されています。プレーンテキストのルームのみ対応しています。

「起動時にすべての古いメッセージが再生される」

<dataDir>/matrix-sync.json が存在しないか、next_batch が null です。デーモンを停止してファイルを削除し、再起動してください。削除後の初回同期では履歴が正しく破棄されます。

「アウトバウンドで 401 エラー（M_UNKNOWN_TOKEN）」

アクセストークンの有効期限が切れているか、失効しています。上記のログインフローで新しいトークンを生成してください。

リファレンス

環境変数: MATRIX_*, MESSAGING_MATRIX_INBOUND
アウトバウンド: apps/agent/src/messaging/matrix.ts
インバウンドデーモン: apps/agent/src/messaging/inbound/matrix-daemon.ts
デーモンランナー: apps/agent/src/messaging/inbound/daemon-runner.ts
Client-Server API 仕様: spec.matrix.org / latest / client-server-api

目次