{"id":50136257,"url":"https://github.com/youngcoder45/discord-matrix-bridge","last_synced_at":"2026-05-23T22:03:00.057Z","repository":{"id":358454496,"uuid":"1241463586","full_name":"youngcoder45/discord-matrix-bridge","owner":"youngcoder45","description":"Discord ↔ Matrix bridge bot built with Node.js and TypeScript for syncing messages between servers and rooms.","archived":false,"fork":false,"pushed_at":"2026-05-17T12:34:06.000Z","size":43,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-17T14:37:01.194Z","etag":null,"topics":["bridge","contributions-welcome","discord","discord-bot","discord-matrix","matrix","matrix-bot","matrix-org","need-contribution","nodejs","opensou","oss","typescript","webhook","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/youngcoder45.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T12:26:36.000Z","updated_at":"2026-05-17T12:34:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/youngcoder45/discord-matrix-bridge","commit_stats":null,"previous_names":["youngcoder45/discord-matrix-bridge"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/youngcoder45/discord-matrix-bridge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngcoder45%2Fdiscord-matrix-bridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngcoder45%2Fdiscord-matrix-bridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngcoder45%2Fdiscord-matrix-bridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngcoder45%2Fdiscord-matrix-bridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/youngcoder45","download_url":"https://codeload.github.com/youngcoder45/discord-matrix-bridge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/youngcoder45%2Fdiscord-matrix-bridge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33413623,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T18:09:33.147Z","status":"ssl_error","status_checked_at":"2026-05-23T18:09:31.380Z","response_time":53,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bridge","contributions-welcome","discord","discord-bot","discord-matrix","matrix","matrix-bot","matrix-org","need-contribution","nodejs","opensou","oss","typescript","webhook","websocket"],"created_at":"2026-05-23T22:02:59.032Z","updated_at":"2026-05-23T22:03:00.049Z","avatar_url":"https://github.com/youngcoder45.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Discord ↔ Matrix Bridge Bot (simple)\n\nBridges one (or more) Discord channels to one (or more) Matrix rooms.\n\n## Features\n\n- Discord → Matrix: forwards messages, replies (as Matrix rich replies), and reactions (unicode emoji)\n- Matrix → Discord: forwards messages via a Discord webhook (impersonates Matrix displayname/avatar), replies as quoted text (`\u003e`), and reactions\n- Optional edit forwarding in both directions\n\n## Requirements\n\n- Node.js 18+ (Node 20+ recommended)\n- A Discord server where you can add bots + create webhooks\n- A Matrix account (ideally a dedicated “bot” account)\n- An **unencrypted** Matrix room (E2EE is not supported)\n\n## 1) Install\n\n```bash\nnpm install\n```\n\n## 2) Discord setup (create bot + invite it)\n\n### 2.1 Create the Discord application + bot\n\n1. Go to the Discord Developer Portal: https://discord.com/developers/applications\n2. Click **New Application** → give it a name.\n3. In the left sidebar: **Bot** → click **Add Bot**.\n4. Under **Token**, click **Reset Token** (or **Copy**) and save it for your `config.json`.\n\n### 2.2 Enable required intents\n\nIn the same **Bot** page, enable:\n\n- **MESSAGE CONTENT INTENT** (required so the bot can read message text)\n\nReactions usually work without special privileged intents, but you must still give the bot channel permissions (next step).\n\n### 2.3 Invite the bot to your server\n\n1. In the left sidebar: **OAuth2** → **URL Generator**.\n2. Scopes:\n\t - ✅ **bot**\n3. Bot permissions (minimum recommended for this bridge):\n\t - ✅ View Channels\n\t - ✅ Read Message History\n\t - ✅ Add Reactions\n\nThen copy/open the generated URL and add the bot to your server.\n\nTip: You can also construct an invite URL like:\n\n```\nhttps://discord.com/api/oauth2/authorize?client_id=YOUR_APPLICATION_CLIENT_ID\u0026scope=bot\u0026permissions=0\n```\n\nBut using the URL Generator is simpler because it calculates permissions for you.\n\n## 3) Discord setup (create a webhook for the target channel)\n\nMatrix → Discord messages are posted via a webhook (so they can show Matrix display name + avatar).\n\n1. Open your Discord server.\n2. Right-click the target channel → **Edit Channel**.\n3. Go to **Integrations** → **Webhooks** → **New Webhook**.\n4. Copy the **Webhook URL**.\n\n## 4) Matrix setup (create a bot user + access token)\n\n### 4.1 Create a Matrix bot account (recommended)\n\nCreate a dedicated Matrix user for the bridge bot (recommended so you don’t use your personal account token).\n\n- Matrix clients (pick one):\n\t- Element Web: https://app.element.io/\n\t- Element Desktop: https://element.io/get-started\n\nSign up on your homeserver (for example matrix.org) and log in.\n\n### 4.2 Get an access token (easy method: Element)\n\nIn Element:\n\n1. Click your profile picture → **All settings**.\n2. **Help \u0026 About**.\n3. Scroll to **Advanced** → copy **Access Token**.\n\nThis token goes into `matrix.accessToken` in `config.json`.\n\n### 4.3 Add the bot to the room\n\nThe bot must be in the Matrix room you want to bridge.\n\n- Invite the bot user to the room (Element: room → **Room info** → **People** → **Invite**).\n- This project uses auto-join on invites, so the bot should accept the invite automatically.\n\nImportant: the room must be **unencrypted** (no E2EE), otherwise the bot won’t be able to read messages.\n\n### 4.4 Find the Matrix room ID\n\nIn Element, open the room → **Room info** → **Settings** → **Advanced** and copy the **Internal room ID**.\nIt looks like:\n\n```\n!someroomid:example.org\n```\n\n## 5) Get the Discord channel ID\n\n1. Discord **User Settings** → **Advanced** → enable **Developer Mode**.\n2. Right-click the target channel → **Copy Channel ID**.\n\n## 6) Configure the bridge\n\nCopy the example config:\n\n```bash\ncp config.example.json config.json\n```\n\nFill in values in `config.json`:\n\n- `discord.botToken`: Discord bot token from the Developer Portal\n- `matrix.homeserverUrl`: your homeserver base URL (example: `https://matrix.org`)\n- `matrix.accessToken`: access token for the Matrix bot user\n- `matrix.botUserId` (optional but recommended): the Matrix bot user ID (example: `@mybot:matrix.org`)\n- `bridge.mappings[]`:\n\t- `discordChannelId`: the channel ID to listen to\n\t- `discordWebhookUrl`: webhook URL for that channel (Matrix → Discord)\n\t- `matrixRoomId`: Matrix room ID to send to\n\nNotes:\n\n- `bridge.statePath` stores message-id mappings so replies/reactions can map across platforms.\n- `bridge.matrixSyncPath` stores Matrix sync state so the bot can resume properly.\n\n## 7) Start the bot\n\nDevelopment mode (recommended while setting up):\n\n```bash\nnpm run dev\n```\n\nProduction build:\n\n```bash\nnpm run build\nnpm start\n```\n\n## 8) What replies/reactions look like\n\n- Discord → Matrix replies: sent as Matrix rich replies (reply threading)\n- Matrix → Discord replies: sent as quoted text using `\u003e`\n- Reactions: unicode emoji reactions are mirrored both ways (custom Discord emoji are not)\n\n## Troubleshooting\n\n- Discord messages not arriving:\n\t- Ensure **MESSAGE CONTENT INTENT** is enabled for the bot in the Developer Portal.\n\t- Ensure the bot has access to the channel and can read message history.\n\t- Ensure `discordChannelId` matches the channel you’re testing in.\n\n- Matrix messages not arriving:\n\t- Ensure the bot user is actually in the room.\n\t- Ensure the room is **unencrypted**.\n\t- Verify `matrix.homeserverUrl` and `matrix.accessToken`.\n\n- Matrix → Discord “impersonation” doesn’t work:\n\t- Matrix → Discord uses a **webhook**; make sure `discordWebhookUrl` is the webhook URL for the channel.\n\n- Error: `Unknown Webhook` / DiscordAPIError `10015`:\n\t- The webhook URL in `discordWebhookUrl` is invalid (deleted webhook or regenerated token).\n\t- Create a new webhook in the target channel and replace `discordWebhookUrl` in `config.json`.\n\n- Reactions don’t mirror Matrix → Discord:\n\t- The Discord bot must have permission to **Add Reactions** in that channel.\n\t- Only unicode emoji reactions are supported.\n\n## Notes / limitations\n\n- Matrix messages are sent by the Matrix bot user (Matrix has no native “webhook impersonation”). The bridge includes author info in the message formatting.\n- Custom Discord emojis are currently not mirrored to Matrix (unicode emoji reactions work).\n- E2EE rooms are not supported.\n\n## How “big / better” Matrix↔Discord bridges are usually built\n\nIf you’ve seen a Discord↔Matrix bridge that “feels native” (each Discord user appears as themselves in Matrix, replies/threading look correct, edits/reactions work reliably, etc.), it’s usually **not** a simple bot that posts messages.\n\nMost mature bridges use a **Matrix Application Service (AS)** bridge design:\n\n- **Application Service registration** on the Matrix homeserver\n\t- The bridge is trusted by the homeserver via an AS registration file (contains tokens + namespace rules).\n\t- This lets the bridge create/“own” many virtual users on Matrix.\n\n- **Puppeting / virtual users**\n\t- For each Discord user, the bridge creates a corresponding Matrix “ghost” user (or connects the user’s own Matrix account).\n\t- That’s how messages on Matrix appear as the real Discord author instead of `Bot: Alice: hello`.\n\n- **Real state + storage**\n\t- Uses a real database (SQLite/Postgres) for message ID mapping, reactions, edits, membership, and resuming after restarts.\n\n- **Protocol-aware mapping**\n\t- Handles Discord mentions/roles/channels, attachments, threads, replies, embeds, stickers, edits, deletes, and rate limits.\n\t- Implements backoff/retry so a single API failure doesn’t crash the bridge.\n\nExamples of popular open-source bridges (for reference):\n\n- `mautrix-discord` (Python, mature “puppeting” bridge): https://docs.mau.fi/bridges/go/discord/index.html\n- `matrix-appservice-discord` (Node, AS bridge): https://github.com/matrix-org/matrix-appservice-discord\n\nThis project is intentionally simpler: it’s a **relay bridge** (Discord bot + Matrix bot + Discord webhook). It’s easier to run, but it can’t match the UX of a full AS/puppeting bridge without a larger redesign.\n\n## Security\n\n- Treat `config.json` like a secret (it contains tokens). Do not commit it.\n- If you accidentally leaked a token, rotate it immediately:\n\t- Discord bot token: Developer Portal → Bot → Reset Token\n\t- Matrix access token: depends on homeserver/client; easiest is create a new token (or new bot account) if your client doesn’t support rotation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoungcoder45%2Fdiscord-matrix-bridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyoungcoder45%2Fdiscord-matrix-bridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyoungcoder45%2Fdiscord-matrix-bridge/lists"}