n8n-nodes-matrix

Official community node for n8n to interact with any Matrix homeserver using the full Matrix Client-Server specification.

Supports Spaces, Rooms & Direct Chats, Messages & Threads, Reactions, Media Upload/Download, End-to-End Encryption (E2EE), Room State Management, User Directory/Profiles, Device Management, and Real-time Trigger Polling.

Features

1. Spaces & Hierarchy

• List / Search Spaces: List all joined Matrix Spaces with name/keyword filtering.
• List / Search Rooms in Space: Traverse Space hierarchies (/hierarchy) with customizable max depth and name filtering.
• Manage Space Hierarchy: Add or remove child rooms/sub-spaces and establish parent-space relationships.
• Create Spaces: Dedicated Space room creation with alias and visibility settings.

2. Messages & Media

• Rich Message Types: Plain text, Formatted HTML, Notices (bot alerts), Emotes (/me), Locations, and Custom JSON.
• Relations & Threading: In-reply-to message ID, thread replies (m.thread), and message editing (m.replace).
• Send Media: Seamless 1-step send for images, video, audio, voice messages, and files directly from n8n binary payloads.
• Message History: Fetch messages with pagination and customizable limits (default: 10).
• Reactions & Redactions: Send emoji reactions and redact events.

3. Rooms & Direct Chats

• List / Search Rooms: View all joined rooms with resolved display names, member counts, and avatars.
• List / Search Direct Chats (1:1 DMs): Resolves user DMs from account data.
• Lifecycle & Moderation: Create (with encryption toggle), Join, Leave, Forget, Knock, Invite, Kick, Ban, and Unban.
• Public Directory Search: Discover public rooms across the homeserver.

4. Room State & Administration

• Read / Set State: Name, Topic, Avatar, Join rules, History visibility, Power levels, and arbitrary custom state JSON.

5. Media Repository

• Upload: Direct binary upload to Matrix Content Repository (mxc://...).
• Download: Fetch files and generate thumbnails from MXC URIs into n8n binary data.
• URL Previews: OpenGraph metadata preview for external URLs.

6. Users, Profiles, Ephemeral & Devices

• User Directory: Search users by display name / Matrix ID.
• Profile: Read/update display names and avatar MXC URLs.
• Ephemeral: Typing indicators, public & private read receipts, presence status, and room tags.
• Devices: List active sessions, inspect device IDs, rename, and revoke sessions.

7. Matrix Trigger (MatrixTrigger)

• Long-polling /sync engine with persistent batch token tracking.
• Filter by event type (m.room.message, m.reaction, m.room.member, m.space.child, or all).
• Room ID filtering and self-event exclusion.

Installation

In your n8n root directory (or ~/.n8n/custom):

npm install n8n-nodes-matrix

Or install via Settings > Community Nodes in the n8n UI using package name n8n-nodes-matrix.

Credentials Setup

1. In n8n, create a new credential for Matrix Server API.
2. Homeserver Base URL: Enter your homeserver URL (e.g. https://matrix.org or https://matrix.example.com).
3. Access Token: Enter your Matrix access token.
   • In Element Web/Desktop: Go to Settings > Help & About > Advanced > Access Token (click to reveal and copy).
4. User ID (Optional):
   • Where to find: In Element, go to Settings > Help & About > User ID (e.g. @bot:matrix.org).
   • Tip: You can leave this blank — n8n will automatically fetch it from the homeserver.
5. Device ID (Optional):
   • Where to find: In Element, go to Settings > Sessions and look at the Device/Session ID for the session where you copied your Access Token.
   • Tip: Leaving this blank is recommended. When blank, n8n queries the server via /whoami to get the exact Device ID bound to your access token, preventing E2EE signature mismatch errors ([400] Device ID in keys uploaded does not match).
6. Enable End-to-End Encryption (E2EE):
   • Toggle on if you want messages sent to encrypted rooms to be automatically encrypted using native Matrix Rust crypto.

License

MIT