ContextQMD
Back to Eliza

@elizaos/plugin-matrix

plugins/plugin-matrix/README.md

2.0.14.2 KB
Original Source

@elizaos/plugin-matrix

Matrix messaging integration plugin for ElizaOS agents.

Features

  • Decentralized Messaging: Connect to any Matrix homeserver
  • End-to-End Encryption: Optional E2EE support for secure communications
  • Room Support: Join, leave, and manage Matrix rooms
  • Reactions: React to messages with emoji
  • Threading: Support for Matrix threads
  • Direct Messages: Handle DMs and group rooms
  • Typing Indicators: Send typing notifications
  • Read Receipts: Mark messages as read

Installation

bash
npm install @elizaos/plugin-matrix

Prerequisites

  1. Matrix Account: A Matrix account on any homeserver
  2. Access Token: Generate an access token for your account

Getting an Access Token

You can get an access token by:

  1. Element/Web Client: Settings -> Help & About -> Access Token
  2. API Login: Use the Matrix login API with your password
  3. Command Line: Use curl or a tool like matrix-commander

Configuration

Set the following environment variables:

Required

VariableDescription
MATRIX_HOMESERVERHomeserver URL (e.g., https://matrix.org)
MATRIX_USER_IDFull Matrix user ID (@user:homeserver.org)
MATRIX_ACCESS_TOKENAccess token for authentication

Optional

VariableDescriptionDefault
MATRIX_DEVICE_IDDevice ID for this sessionAuto-generated
MATRIX_ROOMSComma-separated room IDs/aliases to auto-join-
MATRIX_AUTO_JOINAuto-accept room invitesfalse
MATRIX_ENCRYPTIONEnable E2EE supportfalse
MATRIX_REQUIRE_MENTIONOnly respond when mentioned in roomsfalse

Usage

Basic Setup

typescript
import matrixPlugin from "@elizaos/plugin-matrix";

const agent = new Agent({
  plugins: [matrixPlugin],
});

Actions

Matrix messaging is exposed through the canonical message connector actions. Use source: "matrix" when a request needs to target Matrix explicitly.

Primary actionOperationDescription
MESSAGEsendSend a message to a Matrix room, channel, thread, or DM
MESSAGEreactReact to a Matrix message with an emoji
MESSAGElist_channelsList joined Matrix rooms
MESSAGEjoinJoin a Matrix room by ID or alias
MESSAGEleaveLeave a Matrix room

Providers

matrixRoomState

Provides context about the current Matrix room:

  • Room ID and name
  • Member count
  • Encryption status
  • Whether it's a DM

matrixUserContext

Provides context about the user in the conversation:

  • User ID
  • Display name
  • Avatar URL

Events

The plugin emits the following events:

EventDescription
MATRIX_MESSAGE_RECEIVEDA message was received
MATRIX_MESSAGE_SENTA message was sent
MATRIX_ROOM_JOINEDJoined a room
MATRIX_ROOM_LEFTLeft a room
MATRIX_INVITE_RECEIVEDReceived a room invite
MATRIX_REACTION_RECEIVEDReceived a reaction
MATRIX_SYNC_COMPLETEInitial sync completed
MATRIX_CONNECTION_READYClient connected
MATRIX_CONNECTION_LOSTConnection lost

Message Limits

  • Maximum message length: 4000 characters
  • Longer messages are split automatically

Matrix ID Formats

  • User ID: @localpart:homeserver.org
  • Room ID: !opaque_id:homeserver.org
  • Room Alias: #human_readable:homeserver.org

Security Considerations

  1. Token Security: Never expose your access token
  2. Homeserver Trust: Only connect to trusted homeservers
  3. E2EE: Enable encryption for sensitive communications
  4. Room Verification: Verify room members when using E2EE

Troubleshooting

Connection Issues

  1. Verify your homeserver URL is correct
  2. Check that your access token is valid
  3. Ensure your homeserver is reachable

Sync Issues

  1. The initial sync may take time for accounts with many rooms
  2. Check homeserver rate limits
  3. Verify network connectivity

Encryption Issues

  1. Ensure E2EE is enabled on both ends
  2. Verify device is properly set up
  3. Check for key verification requirements

License

MIT