Skip to main content
The Matrix channel enables communication through the Matrix protocol with support for encrypted rooms.

​
Overview

Matrix is a decentralized, encrypted communication protocol used by:
  • Element (official client)
  • Government organizations
  • Privacy-focused communities
  • Federated chat systems
Features:
  • End-to-end encryption (E2EE)
  • Decentralized architecture
  • Room-based messaging
  • User allowlists
  • Mention-only mode

​
Configuration

​
Basic Setup

[channels.matrix]
homeserver = "https://matrix.org"
access_token = "syt_..."
room_id = "!roomid:matrix.org"  # Or #alias:matrix.org

​
With Allowlist

[channels.matrix]
homeserver = "https://matrix.org"
access_token = "syt_..."
room_id = "#zeroclaw:matrix.org"
allowed_users = ["@alice:matrix.org", "@bob:matrix.org"]
mention_only = true  # Only respond when mentioned

​
Getting Access Token

1

Create Matrix Account

Sign up at https://app.element.io or your homeserver
2

Get Access Token

Element Web:
  1. Settings → Help & About
  2. Scroll to “Advanced”
  3. Click “Access Token”
  4. Copy the token
3

Find Room ID

Element Web:
  1. Open room
  2. Room settings → Advanced
  3. Copy “Internal room ID” (e.g., !abc123:matrix.org)
Or use room alias: #roomname:matrix.org

​
Features

​
End-to-End Encryption

Matrix channel automatically handles E2EE rooms using the matrix-sdk library: 
[channels.matrix]
homeserver = "https://matrix.org"
access_token = "syt_..."
room_id = "!encrypted:matrix.org"
# E2EE is automatic - session data stored in ~/.zeroclaw/matrix/
First message in encrypted room may take a few seconds while keys are exchanged.

​
Session Persistence

Matrix sessions are stored in ~/.zeroclaw/matrix/ directory:
  • Crypto store: Encryption keys
  • Session data: Login session
  • State sync: Room membership

​
Mention-Only Mode

Only respond when bot is mentioned: 
[channels.matrix]
mention_only = true
Agent only replies to messages containing mention like: 
@zeroclaw:matrix.org please help with this

​
User Allowlist

Restrict who can interact: 
[channels.matrix]
allowed_users = [
    "@alice:matrix.org",
    "@bob:matrix.org"
]
Messages from other users are ignored.

​
Room Types

​
Public Rooms

room_id = "#public-room:matrix.org"

​
Private Rooms

room_id = "!privateabc123:matrix.org"

​
Encrypted Rooms

room_id = "!encryptedxyz789:matrix.org"
# E2EE handled automatically

​
Message Features

​
Send Messages

let message = SendMessage::new("Hello from ZeroClaw!", "#room:matrix.org");
channel.send(&message).await?;

​
Receive Messages

Automatically processes:
  • Text messages
  • Encrypted messages (auto-decrypted)
  • Mentions
  • Room invites

​
Implementation Details

Matrix SDK:
  • Uses matrix-sdk crate
  • Full E2EE support via Olm/Megolm
  • Automatic key backup
  • Device verification
Sync Mode:
  • Long-polling sync
  • Real-time message delivery
  • Encrypted room support
  • Automatic reconnection
Source: src/channels/matrix.rs

​
Troubleshooting

Solutions:
  1. Delete crypto store and re-login:
rm -rf ~/.zeroclaw/matrix/
zeroclaw daemon
  1. Verify bot has been invited to encrypted room
  2. Check logs for key exchange errors: 
RUST_LOG=matrix_sdk=debug zeroclaw daemon
Solutions:
  1. Check allowlist:
zeroclaw config get channels.matrix.allowed_users
  1. Verify room ID format:
# Should start with ! or #
zeroclaw config get channels.matrix.room_id
  1. Check mention_only mode:
zeroclaw config get channels.matrix.mention_only
Solutions:
  1. Verify homeserver URL:
curl https://matrix.org/_matrix/client/versions
  1. Check access token validity:
curl -H "Authorization: Bearer syt_..." \
  https://matrix.org/_matrix/client/v3/account/whoami
  1. Test with fresh token

​
Performance

Sync Latency:
  • Real-time: <1 second (long-polling)
  • Encrypted rooms: +500ms (decryption overhead)
Message Throughput:
  • Send: 10 messages/second
  • Receive: Limited by sync rate

​
Security

  • E2EE: All messages in encrypted rooms use Olm/Megolm
  • Access Control: User allowlists enforced
  • Token Storage: Access token stored in config (use environment variable in production)
  • Device Trust: Automatic device verification
Best practices: 
[channels.matrix]
homeserver = "https://matrix.org"
# Use environment variable for token
allowed_users = ["@trusted:matrix.org"]
mention_only = true

Build docs developers (and LLMs) love

Get started for freeTalk to us