Matrix Plugin

The Matrix plugin connects Eliza agents to any Matrix homeserver, enabling messaging in rooms, direct messages, and optional end-to-end encryption.

Package: @elizaos/plugin-matrix

Installation

bash

eliza plugins install @elizaos/plugin-matrix

Setup

1. Create a Bot Account

Create a Matrix account for your bot on your preferred homeserver (e.g., matrix.org, or a self-hosted instance).

2. Obtain an Access Token

Generate an access token through your Matrix client or via the Client-Server API:

bash

curl -X POST https://matrix.example.com/_matrix/client/v3/login \
  -d '{"type":"m.login.password","user":"@bot:example.com","password":"botpassword"}'

3. Configure Eliza

json

{
  "env": {
    "MATRIX_ACCESS_TOKEN": "syt_your_access_token"
  },
  "connectors": {
    "matrix": {
      "enabled": true
    }
  }
}

Configuration

Variable	Required	Default	Description
`MATRIX_ACCESS_TOKEN`	Yes	—	Access token for homeserver authentication
`MATRIX_HOMESERVER`	No	—	Homeserver URL (e.g., `https://matrix.org`)
`MATRIX_USER_ID`	No	—	Bot user ID (e.g., `@bot:matrix.org`)
`MATRIX_DEVICE_ID`	No	—	Device identifier for encryption sessions
`MATRIX_ROOMS`	No	—	Comma-separated room IDs to join
`MATRIX_AUTO_JOIN`	No	`false`	Automatically accept room invitations
`MATRIX_ENCRYPTION`	No	`false`	Enable end-to-end encryption (Olm)
`MATRIX_REQUIRE_MENTION`	No	`false`	Only respond when @mentioned

Features

Private and room messaging
Auto-join on invitation
End-to-end encryption support
Mention filtering for rooms
Works with any spec-compliant homeserver

Auto-Enable

The plugin auto-enables when the connectors.matrix block contains token, botToken, or apiKey. Environment variables alone do not trigger auto-enable. Set "token": "syt_your_access_token" in the connector config to trigger auto-enable, or add the plugin to plugins.allow explicitly.

Matrix connector setup — full connector configuration
Connectors overview — all platform connectors