Matrix Channel Configuration Guide
1. Example Configuration
Add this to config.json:
{
"channels": {
"matrix": {
"enabled": true,
"homeserver": "https://matrix.org",
"user_id": "@your-bot:matrix.org",
"access_token": "YOUR_MATRIX_ACCESS_TOKEN",
"device_id": "",
"join_on_invite": true,
"allow_from": [],
"group_trigger": {
"mention_only": true
},
"placeholder": {
"enabled": true,
"text": "Thinking..."
},
"reasoning_channel_id": ""
}
}
}
2. Field Reference
| Field |
Type |
Required |
Description |
| enabled |
bool |
Yes |
Enable or disable the Matrix channel |
| homeserver |
string |
Yes |
Matrix homeserver URL (for example https://matrix.org) |
| user_id |
string |
Yes |
Bot Matrix user ID (for example @bot:matrix.org) |
| access_token |
string |
Yes |
Bot access token |
| device_id |
string |
No |
Optional Matrix device ID |
| join_on_invite |
bool |
No |
Auto-join invited rooms |
| allow_from |
[]string |
No |
User whitelist (Matrix user IDs) |
| group_trigger |
object |
No |
Group trigger strategy (mention_only / prefixes) |
| placeholder |
object |
No |
Placeholder message config |
| reasoning_channel_id |
string |
No |
Target channel for reasoning output |
3. Currently Supported
- Text message send/receive
- Incoming image/audio/video/file download (MediaStore first, local path fallback)
- Incoming audio normalization into existing transcription flow (
[audio: ...])
- Outgoing image/audio/video/file upload and send
- Group trigger rules (including mention-only mode)
- Typing state (
m.typing)
- Placeholder message + final reply replacement
- Auto-join invited rooms (can be disabled)
4. TODO
- Rich media metadata improvements (for example image/video size and thumbnails)
