{"id":48236014,"url":"https://github.com/beeper/chat-adapter-matrix","last_synced_at":"2026-04-16T00:33:20.253Z","repository":{"id":340445439,"uuid":"1166060508","full_name":"beeper/chat-adapter-matrix","owner":"beeper","description":"Matrix adapter for Vercel's Chat SDK","archived":false,"fork":false,"pushed_at":"2026-04-13T12:15:12.000Z","size":278,"stargazers_count":13,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-13T12:19:11.991Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beeper.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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-02-24T20:49:59.000Z","updated_at":"2026-04-07T00:00:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beeper/chat-adapter-matrix","commit_stats":null,"previous_names":["beeper/chat-adapter-matrix"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/beeper/chat-adapter-matrix","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fchat-adapter-matrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fchat-adapter-matrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fchat-adapter-matrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fchat-adapter-matrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beeper","download_url":"https://codeload.github.com/beeper/chat-adapter-matrix/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beeper%2Fchat-adapter-matrix/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31866347,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"ssl_error","status_checked_at":"2026-04-15T15:24:39.138Z","response_time":63,"last_error":"SSL_read: 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":[],"created_at":"2026-04-04T20:00:26.649Z","updated_at":"2026-04-16T00:33:20.242Z","avatar_url":"https://github.com/beeper.png","language":"TypeScript","funding_links":[],"categories":["🧠 AI \u0026 Agents"],"sub_categories":[],"readme":"# @beeper/chat-adapter-matrix\n\nMatrix adapter for [Chat SDK](https://chat-sdk.dev/docs). It runs over Matrix sync instead of webhooks and works with Beeper conversations and bridged networks such as WhatsApp, Telegram, Instagram, and Signal.\n\n## Installation\n\nRequires Node.js `\u003e=22`.\n\n```bash\npnpm add chat @beeper/chat-adapter-matrix\n```\n\n## Usage\n\n`createMatrixAdapter()` reads its config from environment variables when called without arguments.\n\n```ts\nimport { Chat } from \"chat\";\nimport { createMemoryState } from \"@chat-adapter/state-memory\";\nimport { createMatrixAdapter } from \"@beeper/chat-adapter-matrix\";\n\nconst matrix = createMatrixAdapter();\n\nconst bot = new Chat({\n  userName: process.env.MATRIX_BOT_USERNAME ?? \"beeper-bot\",\n  state: createMemoryState(),\n  adapters: { matrix },\n});\n\nbot.onNewMention(async (thread, message) =\u003e {\n  await thread.subscribe();\n  await thread.post(`Hi ${message.author.userName}. Mention me or run /ping.`);\n});\n\nbot.onSlashCommand(\"/ping\", async (event) =\u003e {\n  await event.channel.post(\"pong\");\n});\n\nawait bot.initialize();\n```\n\nChat SDK concepts such as `Chat`, `Thread`, `Message`, subscriptions, and handlers work the same here. See the upstream docs for the core API:\n\n- [Getting Started](https://chat-sdk.dev/docs/getting-started)\n- [Usage](https://chat-sdk.dev/docs/usage)\n- [Threads, Messages, and Channels](https://chat-sdk.dev/docs/threads-messages-channels)\n- [Direct Messages](https://chat-sdk.dev/docs/direct-messages)\n\n## Authentication\n\n### Access token\n\n```ts\ncreateMatrixAdapter({\n  baseURL: process.env.MATRIX_BASE_URL!,\n  auth: {\n    type: \"accessToken\",\n    accessToken: process.env.MATRIX_ACCESS_TOKEN!,\n    userID: process.env.MATRIX_USER_ID,\n  },\n});\n```\n\n### Username/password\n\n```ts\ncreateMatrixAdapter({\n  baseURL: process.env.MATRIX_BASE_URL!,\n  auth: {\n    type: \"password\",\n    username: process.env.MATRIX_USERNAME!,\n    password: process.env.MATRIX_PASSWORD!,\n    userID: process.env.MATRIX_USER_ID,\n  },\n});\n```\n\n## Defaults\n\n- Persistence behavior is active whenever Chat provides a `state` adapter.\n- Redis or another durable state adapter is recommended for restart durability.\n- `deviceID` is inferred from auth when possible, then reused from state, and only generated as a last resort.\n- `recoveryKey` enables E2EE.\n- `inviteAutoJoin: {}` enables invite auto-join.\n\n## Common Options\n\n```ts\ncreateMatrixAdapter({\n  baseURL: process.env.MATRIX_BASE_URL!,\n  auth: {\n    type: \"accessToken\",\n    accessToken: process.env.MATRIX_ACCESS_TOKEN!,\n    userID: process.env.MATRIX_USER_ID,\n  },\n  recoveryKey: process.env.MATRIX_RECOVERY_KEY,\n  commandPrefix: \"/\",\n  roomAllowlist: [\"!room:beeper.com\"],\n  inviteAutoJoin: {\n    inviterAllowlist: [\"@alice:beeper.com\", \"@ops:beeper.com\"],\n  },\n  matrixSDKLogLevel: \"error\",\n});\n```\n\nAdvanced tuning stays in code config:\n\n```ts\ncreateMatrixAdapter({\n  baseURL: process.env.MATRIX_BASE_URL!,\n  auth: {\n    type: \"accessToken\",\n    accessToken: process.env.MATRIX_ACCESS_TOKEN!,\n    userID: process.env.MATRIX_USER_ID,\n  },\n  e2ee: {\n    useIndexedDB: false,\n    cryptoDatabasePrefix: \"beeper-matrix-bot\",\n  },\n  persistence: {\n    keyPrefix: \"my-bot\",\n    session: {\n      ttlMs: 86_400_000,\n    },\n    sync: {\n      persistIntervalMs: 10_000,\n    },\n  },\n});\n```\n\n## Environment Variables\n\n`createMatrixAdapter()` with no arguments uses only these env vars:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `MATRIX_BASE_URL` | Yes | Matrix homeserver base URL |\n| `MATRIX_ACCESS_TOKEN` | Yes* | Access token for access-token auth |\n| `MATRIX_USERNAME` | Yes* | Username for password auth |\n| `MATRIX_PASSWORD` | Yes* | Password for password auth |\n| `MATRIX_USER_ID` | No | User ID hint |\n| `MATRIX_DEVICE_ID` | No | Explicit device ID override |\n| `MATRIX_RECOVERY_KEY` | No | Enables E2EE and key-backup bootstrap |\n| `MATRIX_BOT_USERNAME` | No | Mention-detection username |\n| `MATRIX_COMMAND_PREFIX` | No | Slash command prefix. Defaults to `/` |\n| `MATRIX_INVITE_AUTOJOIN` | No | Enable invite auto-join |\n| `MATRIX_INVITE_AUTOJOIN_ALLOWLIST` | No | Comma-separated Matrix user IDs allowed to invite the bot |\n| `MATRIX_SDK_LOG_LEVEL` | No | Matrix SDK log level |\n\n\\*Use either `MATRIX_ACCESS_TOKEN`, or `MATRIX_USERNAME` plus `MATRIX_PASSWORD`.\n\n## Thread Model\n\n- A Matrix room is a Chat SDK channel.\n- Top-level room messages belong to the channel timeline.\n- Matrix threaded replies map to Chat SDK threads using `roomID + rootEventID`.\n- `openDM(userId)` reuses existing direct rooms when possible and creates one when needed.\n\n## Features\n\n| Feature | Supported |\n|---------|-----------|\n| Mentions | Yes |\n| Rich text | Yes, via Matrix `formatted_body` and `m.mentions` |\n| Thread replies | Yes |\n| Reactions (add/remove) | Yes |\n| Message edits | Yes |\n| Message deletes | Yes |\n| Typing indicator | Yes |\n| Direct messages | Yes |\n| File uploads | Yes |\n| Message history | Yes |\n| Channel and thread metadata | Yes |\n| E2EE | Yes |\n| Invite auto-join | Yes |\n| Slash commands | Prefix-parsed from message text |\n| Webhooks | No, this adapter uses sync polling |\n| Cards | No |\n| Modals | No |\n| Ephemeral messages | No |\n| Native streaming | No |\n\n## Persistence\n\nFor production, pair the adapter with a durable Chat state adapter such as Redis.\n\n```ts\nimport { Chat } from \"chat\";\nimport { createRedisState } from \"@chat-adapter/state-redis\";\nimport { createMatrixAdapter } from \"@beeper/chat-adapter-matrix\";\n\nconst matrix = createMatrixAdapter({\n  baseURL: process.env.MATRIX_BASE_URL!,\n  auth: {\n    type: \"accessToken\",\n    accessToken: process.env.MATRIX_ACCESS_TOKEN!,\n    userID: process.env.MATRIX_USER_ID,\n  },\n  recoveryKey: process.env.MATRIX_RECOVERY_KEY,\n});\n\nconst bot = new Chat({\n  userName: process.env.MATRIX_BOT_USERNAME ?? \"beeper-bot\",\n  state: createRedisState({ url: process.env.REDIS_URL! }),\n  adapters: { matrix },\n});\n```\n\nPersistence covers:\n\n- generated or inferred device IDs\n- password login sessions\n- DM room mappings\n- Matrix sync snapshots\n- E2EE secrets bundles when E2EE is enabled\n\n## Message and History APIs\n\nThe adapter supports:\n\n- `fetchMessage(threadId, messageId)`\n- `fetchMessages(threadId, options)`\n- `fetchChannelMessages(channelId, options)`\n- `fetchThread(threadId)`\n- `fetchChannelInfo(channelId)`\n- `listThreads(channelId, options)`\n- `openDM(userId)`\n\n## Limitations\n\n- `handleWebhook()` returns `501` by design because Matrix uses sync polling here.\n- Cards, modals, and ephemeral messages are not implemented.\n- Native streaming is not implemented at the adapter layer.\n- Slash commands are parsed from plain text messages; Matrix does not provide native slash command events.\n\n## Examples\n\n- [`examples/bot.ts`](./examples/bot.ts) uses in-memory state for local development.\n- [`examples/bot.redis.ts`](./examples/bot.redis.ts) uses Redis-backed state for restart durability.\n- [`examples/.env.example`](./examples/.env.example) lists the supported env vars for the examples.\n- [`scripts/get-access-token.ts`](./scripts/get-access-token.ts) helps generate Beeper credentials interactively.\n\nFor release-specific changes, see [CHANGELOG.md](./CHANGELOG.md).\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fchat-adapter-matrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeeper%2Fchat-adapter-matrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeeper%2Fchat-adapter-matrix/lists"}