Matrix adapter for Chat SDK. Uses Matrix sync (no webhook server required).

If you are using Beeper, you can use Chat SDK with your Beeper Cloud accounts and Matrix chats. This lets you use Chat SDK with WhatsApp, Telegram, Instagram, Signal, X Chat, and more. For bridged chats, we recommend personal usage, since some networks may limit automated activity.

npm install chat @beeper/chat-adapter-matrix matrix-js-sdk

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

const bot = new Chat({
  userName: "beeper-bot",
  state: createMemoryState(),
  adapters: {
    matrix: createMatrixAdapter({
      baseURL: process.env.MATRIX_BASE_URL!,
      auth: {
        type: "accessToken",
        accessToken: process.env.MATRIX_ACCESS_TOKEN!,
      },
      recoveryKey: process.env.MATRIX_RECOVERY_KEY,
    }),
  },
});

bot.onNewMention(async (thread, message) => {
  await thread.subscribe();
  await thread.post(`Hi ${message.author.userName}`);
});

Access token:

auth: { type: "accessToken", accessToken: process.env.MATRIX_ACCESS_TOKEN! };

Username/password:

auth: {
  type: "password",
  username: process.env.MATRIX_USERNAME!,
  password: process.env.MATRIX_PASSWORD!,
};

Required:

• MATRIX_BASE_URL
• Access token mode: MATRIX_ACCESS_TOKEN
• Password mode: MATRIX_USERNAME, MATRIX_PASSWORD

Common optional:

• MATRIX_USER_ID
• MATRIX_DEVICE_ID
• MATRIX_RECOVERY_KEY

Advanced optional (only if needed): device ID persistence keys, E2EE storage settings, session settings, and MATRIX_SDK_LOG_LEVEL.

Copy examples/.env.example to examples/.env, then run:

npm run example:bun

Generate a Beeper access token interactively:

npm run token:bun

Use the interactive helper:

npm run token:bun

It prints:

• MATRIX_BASE_URL
• MATRIX_ACCESS_TOKEN
• MATRIX_USER_ID
• MATRIX_DEVICE_ID

Paste those values into examples/.env or your deployment secrets.

or:

bun --env-file=examples/.env run examples/bot.ts

• handleWebhook() returns 501 by design.
• Access-token auth resolves identity with whoami.
• Password auth sends configured device_id during login.
• Use Redis state in production for stable sessions and device IDs.

MIT