84 lines
2.9 KiB
Markdown
84 lines
2.9 KiB
Markdown
---
|
|
created: '2026-04-11T16:20:05+00:00'
|
|
id: e4dd5e53-a9a4-4f2e-9ed2-40a55b991ba5
|
|
keywords:
|
|
- matrix_bridge.py
|
|
- FastAPI
|
|
- Synapse
|
|
- Element Web
|
|
- appservice
|
|
- ConversationService
|
|
- send_notification.py
|
|
- matrix-deployment.md
|
|
- matrix_rooms.json
|
|
- aipa_appservice.yaml
|
|
links: []
|
|
modified: '2026-04-11T16:20:05+00:00'
|
|
summary: 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.
|
|
tags:
|
|
- aipa
|
|
- matrix
|
|
- bridge
|
|
- deployment
|
|
- integration
|
|
title: Matrix Bridge — Application Service Integration
|
|
---
|
|
|
|
# Matrix Bridge — Application Service Integration
|
|
|
|
## Overview
|
|
|
|
AIPA integrates with a self-hosted [Matrix](https://matrix.org/) 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`)
|
|
|
|
```bash
|
|
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` |