Matrix (Element)

Matrix integration provides end-to-end encrypted messaging through the Matrix protocol, compatible with Element and other Matrix clients.

Features

✅ End-to-end encryption (E2EE) support
✅ Matrix homeserver compatibility
✅ User ID-based access control
✅ Group chat with configurable policies
✅ Media attachment support with size limits
✅ Room mention handling

Prerequisites

Install Matrix dependencies:

pip install nanobot-ai[matrix]

Setup

Create or choose Matrix account

Create a dedicated Matrix account for your bot
You can use any homeserver (e.g., matrix.org, or your own)
Example: @nanobot:matrix.org
Confirm you can log in with Element client

Get credentials

You need three pieces of information:

userId: Your Matrix user ID (e.g., @nanobot:matrix.org)
accessToken: Authentication token
deviceId: Device identifier (recommended for session persistence)

Option 1: Using Element Web

Log in to Element Web
Settings → Help & About
Scroll to bottom → Access Token
Click to reveal token (starts with syt_)

Option 2: Using homeserver API

curl -X POST "https://matrix.org/_matrix/client/v3/login" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "identifier": {"type": "m.id.user", "user": "nanobot"},
    "password": "your-password",
    "device_id": "NANOBOT01"
  }'

Get your User ID

Your Matrix user ID is shown in Element settings:

Open Element
Click your profile
Copy your User ID (format: @youruser:matrix.org)

Configure nanobot

Edit ~/.nanobot/config.json:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@nanobot:matrix.org",
      "accessToken": "syt_xxx",
      "deviceId": "NANOBOT01",
      "e2eeEnabled": true,
      "allowFrom": ["@your_user:matrix.org"],
      "groupPolicy": "open",
      "groupAllowFrom": [],
      "allowRoomMentions": false,
      "maxMediaBytes": 20971520
    }
  }
}

Start the gateway

nanobot gateway

You should see:

Matrix channel connected
E2EE enabled

Test the connection

Open Element and find your bot user
Start a direct message
Send a message
Your bot should respond!

Configuration Options

enabled

boolean

required

Enable the Matrix channel

homeserver

string

required

Matrix homeserver URLExamples:

https://matrix.org
https://your-homeserver.com

userId

string

required

Matrix user ID for the bot (format: @username:homeserver)

accessToken

string

required

Access token for authentication (format: syt_xxx)

Keep this private. Never commit to version control.

deviceId

string

required

Device identifier (recommended for session persistence)

Keep a persistent matrix-store and stable deviceId — encrypted session state is lost if these change across restarts.

e2eeEnabled

boolean

default:"true"

Enable end-to-end encryption supportSet to false for plaintext-only mode (not recommended).

allowFrom

array

default:"[]"

List of Matrix user IDs allowed to interact with the botExamples:

Single user: ["@alice:matrix.org"]
Multiple: ["@alice:matrix.org", "@bob:matrix.org"]
All users: [] (empty array)

groupPolicy

string

default:"open"

Controls how the bot responds in rooms:

"open" (default) — Respond to all messages
"mention" — Only respond when mentioned
"allowlist" — Only respond in specific rooms

groupAllowFrom

array

default:"[]"

Room IDs to allow (used when groupPolicy is "allowlist")Example: ["!roomid1:matrix.org", "!roomid2:matrix.org"]

allowRoomMentions

boolean

default:"false"

Accept @room mentions in mention modeIf true, bot responds to @room mentions in addition to direct mentions.

maxMediaBytes

number

default:"20971520"

Maximum attachment size in bytes (default: 20MB)Set to 0 to block all media uploads.

End-to-End Encryption

Understanding E2EE in Matrix

Matrix supports end-to-end encryption for secure messaging.

Enabled by default

{
  "e2eeEnabled": true
}

Bot can send/receive encrypted messages
Requires matrix-store for session state
Supports device verification

Plaintext only

{
  "e2eeEnabled": false
}

Bot only works in unencrypted rooms
Simpler setup, no encryption overhead
Not recommended for sensitive conversations

Important notes

Keep deviceId stable across restarts
Keep matrix-store directory persistent
Lost encryption state = can’t decrypt old messages
Verify devices in Element for trusted communication

Group Chat Policies

Configuring group chat behavior

Open mode (default)

{
  "groupPolicy": "open"
}

Bot responds to all messages in all rooms.

Mention mode

{
  "groupPolicy": "mention",
  "allowRoomMentions": false
}

Bot only responds when directly mentioned (e.g., @nanobot:matrix.org).With @room support:

{
  "groupPolicy": "mention",
  "allowRoomMentions": true
}

Bot responds to both direct mentions and @room.

Allowlist mode

{
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["!abc123:matrix.org"]
}

Bot only responds in specified rooms.

Troubleshooting

Matrix dependencies not installed

Error: ModuleNotFoundError: No module named 'nio'Solution: Install Matrix dependencies

pip install nanobot-ai[matrix]

Bot doesn't respond

Check user ID is in allowFrom (or use empty array for all)
Check groupPolicy settings for room behavior
Verify access token is valid
Check homeserver is reachable
Look for errors in logs: nanobot gateway -v

Encryption errors

If you see encryption-related errors:

Lost session state:
- Check matrix-store directory exists and is writable
- Ensure deviceId hasn’t changed
- May need to re-verify device in Element
Unable to decrypt:
- Verify bot account in Element
- Check E2EE is enabled: "e2eeEnabled": true
- Clear encryption state and restart

Start fresh:

rm -rf ~/.nanobot/matrix-store
nanobot gateway

Then re-verify device in Element.

Connection to homeserver fails

Verify homeserver URL is correct (include https://)
Check homeserver is online and accessible
Verify access token is valid (not expired/revoked)
Check firewall allows outbound HTTPS
Try alternative homeserver if using matrix.org (can be slow)

Media uploads fail

Check file size is under maxMediaBytes limit
Verify homeserver allows media uploads
Check bot has permission to upload to room
Increase limit if needed:
```
{
  "maxMediaBytes": 52428800
}
```
(50MB in bytes)

Bot appears offline

Verify gateway is running: nanobot gateway
Check access token hasn’t expired
Verify homeserver status
Check network connectivity
Try logging out and back in to get new token

Complete Example

Full configuration with all options:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "userId": "@nanobot:matrix.org",
      "accessToken": "syt_abcdefghijklmnopqrstuvwxyz123456",
      "deviceId": "NANOBOT01",
      "e2eeEnabled": true,
      "allowFrom": ["@alice:matrix.org", "@bob:matrix.org"],
      "groupPolicy": "mention",
      "groupAllowFrom": [],
      "allowRoomMentions": false,
      "maxMediaBytes": 20971520
    }
  }
}

Configuration Overview

Learn about channel configuration

Security Settings

Set up access control

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

Matrix (Element)

Features

Prerequisites

Setup

Configuration Options

End-to-End Encryption

Enabled by default

Plaintext only

Important notes

Group Chat Policies

Open mode (default)

Mention mode

Allowlist mode

Troubleshooting

Complete Example

Configuration Overview

Security Settings

Build docs developers (and LLMs) love

Get Started

Core Concepts

Configuration

Chat Channels

Deployment

Advanced

​Features

​Prerequisites

​Setup

​Configuration Options

​End-to-End Encryption

​Enabled by default

​Plaintext only

​Important notes

​Group Chat Policies

​Open mode (default)

​Mention mode

​Allowlist mode

​Troubleshooting

​Complete Example

​Related Pages

Configuration Overview

Security Settings

Build docs developers (and LLMs) love

Features

Prerequisites

Setup

Configuration Options

End-to-End Encryption

Enabled by default

Plaintext only

Important notes

Group Chat Policies

Open mode (default)

Mention mode

Allowlist mode

Troubleshooting

Complete Example

Related Pages