@beeper/chat-adapter-matrix

Matrix adapter for Chat SDK. It runs over Matrix sync instead of webhooks and works with Beeper conversations and bridged networks such as WhatsApp, Telegram, Instagram, and Signal.

Installation

Requires Node.js >=22.

pnpm add chat @beeper/chat-adapter-matrix

Usage

createMatrixAdapter() reads its config from environment variables when called without arguments.

import { Chat } from "chat";
import { createMemoryState } from "@chat-adapter/state-memory";
import { createMatrixAdapter } from "@beeper/chat-adapter-matrix";

const matrix = createMatrixAdapter();

const bot = new Chat({
  userName: process.env.MATRIX_BOT_USERNAME ?? "beeper-bot",
  state: createMemoryState(),
  adapters: { matrix },
});

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`Hi ${message.author.userName}. Mention me or run /ping.`);
});

bot.onSlashCommand("/ping", async (event) => {
  await event.channel.post("pong");
});

await bot.initialize();

Chat SDK concepts such as Chat, Thread, Message, subscriptions, and handlers work the same here. See the upstream docs for the core API:

• Getting Started
• Usage
• Threads, Messages, and Channels
• Direct Messages

Authentication

Access token

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
});

Username/password

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "password",
    username: process.env.MATRIX_USERNAME!,
    password: process.env.MATRIX_PASSWORD!,
    userID: process.env.MATRIX_USER_ID,
  },
});

Defaults

• Persistence behavior is active whenever Chat provides a state adapter.
• Redis or another durable state adapter is recommended for restart durability.
• deviceID is inferred from auth when possible, then reused from state, and only generated as a last resort.
• recoveryKey enables E2EE.
• inviteAutoJoin: {} enables invite auto-join.

Common Options

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  recoveryKey: process.env.MATRIX_RECOVERY_KEY,
  commandPrefix: "/",
  roomAllowlist: ["!room:beeper.com"],
  inviteAutoJoin: {
    inviterAllowlist: ["@alice:beeper.com", "@ops:beeper.com"],
  },
  matrixSDKLogLevel: "error",
});

Advanced tuning stays in code config:

createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  e2ee: {
    useIndexedDB: false,
    cryptoDatabasePrefix: "beeper-matrix-bot",
  },
  persistence: {
    keyPrefix: "my-bot",
    session: {
      ttlMs: 86_400_000,
    },
    sync: {
      persistIntervalMs: 10_000,
    },
  },
});

Environment Variables

createMatrixAdapter() with no arguments uses only these env vars:

*Use either MATRIX_ACCESS_TOKEN, or MATRIX_USERNAME plus MATRIX_PASSWORD.

Thread Model

• A Matrix room is a Chat SDK channel.
• Top-level room messages belong to the channel timeline.
• Matrix threaded replies map to Chat SDK threads using roomID + rootEventID.
• openDM(userId) reuses existing direct rooms when possible and creates one when needed.

Features

Persistence

For production, pair the adapter with a durable Chat state adapter such as Redis.

import { Chat } from "chat";
import { createRedisState } from "@chat-adapter/state-redis";
import { createMatrixAdapter } from "@beeper/chat-adapter-matrix";

const matrix = createMatrixAdapter({
  baseURL: process.env.MATRIX_BASE_URL!,
  auth: {
    type: "accessToken",
    accessToken: process.env.MATRIX_ACCESS_TOKEN!,
    userID: process.env.MATRIX_USER_ID,
  },
  recoveryKey: process.env.MATRIX_RECOVERY_KEY,
});

const bot = new Chat({
  userName: process.env.MATRIX_BOT_USERNAME ?? "beeper-bot",
  state: createRedisState({ url: process.env.REDIS_URL! }),
  adapters: { matrix },
});

Persistence covers:

• generated or inferred device IDs
• password login sessions
• DM room mappings
• Matrix sync snapshots
• E2EE secrets bundles when E2EE is enabled

Message and History APIs

The adapter supports:

• fetchMessage(threadId, messageId)
• fetchMessages(threadId, options)
• fetchChannelMessages(channelId, options)
• fetchThread(threadId)
• fetchChannelInfo(channelId)
• listThreads(channelId, options)
• openDM(userId)

Limitations

• handleWebhook() returns 501 by design because Matrix uses sync polling here.
• Cards, modals, and ephemeral messages are not implemented.
• Native streaming is not implemented at the adapter layer.
• Slash commands are parsed from plain text messages; Matrix does not provide native slash command events.

Examples

• examples/bot.ts uses in-memory state for local development.
• examples/bot.redis.ts uses Redis-backed state for restart durability.
• examples/.env.example lists the supported env vars for the examples.
• scripts/get-access-token.ts helps generate Beeper credentials interactively.

For release-specific changes, see CHANGELOG.md.

License

MIT