Discord → Matrix Migration Bot

A Python Discord bot that migrates channels, messages, and attachments into a Matrix server. It can create Matrix rooms automatically or use a manual mapping to pre-existing rooms. Attachments are size-checked against the Matrix server upload limit before migration.

Features

• Migrate Discord text channels into Matrix rooms
• Uploads message attachments to Matrix media
• Enforces Matrix media size limits (server-config or override)
• Auto-create rooms or use manual channel→room mapping
• Simple /migrate slash command to start migration

Setup

1) Install dependencies

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2) Configure the bot

Copy the example config and fill values:

cp config.yaml.example config.yaml

Create a mapping file if using manual mode:

cp mapping.json.example mapping.json

3) Run config validation

python validate_config.py

4) Run the bot

python bot.py

Usage

• Run /migrate in a Discord channel to migrate all text channels in the configured guild.
• Run /migrate channel:#some-channel to migrate a single channel (use the channel picker in Discord).

Configuration Notes

• matrix.auto_create_rooms: If true, missing mappings will create rooms automatically.
• matrix.space_id: Optional Matrix space ID (e.g. !abc123:example.org). When set, newly created rooms are added as children of this space. Non-private channels use a restricted join rule so only space members can join; private channels remain invite-only.
• mapping.mode: auto to create new rooms on-demand, manual to rely on mapping.json.
• matrix.max_upload_size: Set to an integer (bytes) to override server limit.
• discord.allowed_user_ids: Optional list of Discord user IDs allowed to run migration.
• discord.include_channel_ids: Optional allowlist of channels to migrate.

Required Discord Bot Permissions

• Read Messages / View Channels
• Read Message History
• Send Messages
• Use Slash Commands
• Attach Files (if you want it to post info messages)

Matrix Requirements

• Matrix access token for a bot user
• Homeserver URL reachable from your machine

Troubleshooting

• If attachments are skipped, raise matrix.max_upload_size or adjust your Matrix media config.
• If you want custom room mapping, set mapping.mode: manual and fill mapping.json.