VuongKB/projects/aipa/matrix-bridge.md

created, id, keywords, links, modified, summary, tags, title

created	id	keywords	links	modified	summary	tags	title
2026-04-11T16:20:05+00:00	e4dd5e53-a9a4-4f2e-9ed2-40a55b991ba5	matrix_bridge.py FastAPI Synapse Element Web appservice ConversationService send_notification.py matrix-deployment.md matrix_rooms.json aipa_appservice.yaml		2026-04-11T16:20:05+00:00	Matrix Application Service bridge for AIPA enabling bidirectional communication via Synapse. Includes a FastAPI event listener, auto-room-joining, agent routing, and a proactive push notification backend, with full deployment documentation.	aipa matrix bridge deployment integration	Matrix Bridge — Application Service Integration

Matrix Bridge — Application Service Integration

Overview

AIPA integrates with a self-hosted Matrix homeserver (Synapse) via an Application Service bridge, enabling users to interact with agents through Element Web or any Matrix client. The bridge receives events via push (no polling), routes messages to agents, and posts responses with markdown rendering, typing indicators, and threaded replies.

Components

core/matrix_bridge.py — Application Service Bridge

• Runs a FastAPI server on port 8009
• Receives event pushes from Synapse (no polling)
• Auto-accepts invitations: invite @atlas:matrix.pfi.local to a room → Atlas joins and owns that room permanently
• Routes m.room.message events to the correct agent via ConversationService
• Posts responses back with markdown→HTML formatting, typing indicators, and threaded replies
• Persists room→session mapping in sessions/matrix_rooms.json across restarts

tools/send_notification.py — Matrix Notification Backend

New Matrix backend so agents can proactively push messages to rooms (e.g., alerts, status updates) without being prompted.

docs/matrix-deployment.md — Deployment Guide

Complete step-by-step guide covering:

• Synapse Docker Compose setup
• Database configuration
• AppService registration YAML (aipa_appservice.yaml)
• Element Web client setup
• Admin account creation
• Troubleshooting table

Configuration

Environment Variables (add to env.sh)

export MATRIX_HOMESERVER_URL="http://localhost:8008"
export MATRIX_SERVER_NAME="matrix.pfi.local"
export MATRIX_AS_TOKEN="<as_token>"
export MATRIX_HS_TOKEN="<hs_token>"

Provider Config

Uncomment the matrix: block in config/providers.yaml.

Activation Steps

1. Follow docs/matrix-deployment.md to deploy Synapse on your VM
2. Generate two tokens (as_token, hs_token) and write aipa_appservice.yaml in Synapse's data directory
3. Set the four MATRIX_* environment variables in env.sh
4. Uncomment the matrix: block in config/providers.yaml
5. pip install markdown (or pip install -r requirements.txt)
6. python -m core.matrix_bridge
7. Open Element → DM @atlas:matrix.pfi.local