Matrix

Manage Matrix rooms, messages, media, events, and members

Overview

The Matrix tool interacts with the Matrix Client-Server API (r0) to manage decentralized communication. Resources: Account (get current user info), Event (get a single event by ID), Media (upload a file to a room), Message (send text/HTML/emote/notice, get all messages with pagination), Room (create, join, leave, invite, kick), Room Member (get all members with membership filters). Media upload is a two-step process: the file is uploaded to the homeserver’s media repository to obtain an mxc:// URI, and a room message event is then posted referencing that URI. Messages are sent idempotently with a client-generated transaction ID.

Category: Communication
Tool Name: matrix
Version: 1

Appearance: Icon: si-matrix | Color: #0DBD8B

Node Type

Action (Binary) — handles file/binary data operations

Input / Output

Direction	Port(s)
Input	Input
Output	Output, Error

Credentials

This tool requires Matrix API credentials. See the Credentials Guide for setup instructions.

Resources

Resource	Value
Account	account
Event	event
Media	media
Message	message
Room	room
Room Member	roomMember

Operations

Operation	Value	Description
Me	me	Get current user’s account information
Get	get	Get a single event by ID
Upload	upload	Upload media to a room
Create	create	Send a message to a room
Get Many	getAll	Get messages from a room
Create	create	Create a new chat room
Invite	invite	Invite a user to a room
Join	join	Join a room
Kick	kick	Kick a user from a room
Leave	leave	Leave a room
Get Many	getAll	Get room members

The operation list is scoped to the resource you pick, which is why create and getAll each appear twice.

Parameters

Account: Me takes no parameters of its own — see All Operations.

Event: Get

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	The room ID containing the event. Supports expressions like {{ $json.roomId }}.
Event ID	string	Yes	—	The event ID to retrieve. Supports expressions.

Media: Upload

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	The room ID to send the uploaded media to. You can find room IDs by calling Account > Me to list joined rooms. Supports expressions.
Binary Property	string	Yes	data	Name of the binary property on the input item containing the file to upload. Names are case-sensitive — see the upstream node’s Binary Data panel for the exact names to use.
Media Type	options	Yes	image	The type of media being uploaded. Determines the message type (m.image, m.file, m.audio, m.video).
				Options: audio, file (general file), image, video
Additional Fields	collection	No	{}	Optional overrides for the uploaded file.
— File Name	string	No	—	Override the file name (defaults to the binary data file name). Supports expressions.

Message: Create

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	The room ID to send the message to. Supports expressions like {{ $json.roomId }}.
Text	string	No	—	The message text to send. When using HTML format, this becomes the formatted_body. Supports expressions like {{ $json.message }}.
Message Type	options	No	m.text	The type of message to send.
				Options: m.emote (perform an action, similar to /me in IRC), m.notice (send a notice), m.text (send a text message)
Message Format	options	No	plain	The format of the message body.
				Options: org.matrix.custom.html (HTML-formatted text), plain (text only)
Fallback Text	string	No	—	Plain text fallback when using HTML format. Displayed by clients that cannot render HTML. Supports expressions. (shown when Message Format is org.matrix.custom.html)

Message: Get Many

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	The room ID to retrieve messages from. Supports expressions.
Return All	boolean	Yes	false	Whether to return all messages or only up to a given limit.
Limit	number	No	100	Maximum number of messages to return. Accepts 1–500. (shown when Return All is false)
Other Options	collection	No	{}	Extra retrieval settings.
— Filter	string	No	—	A JSON RoomEventFilter to filter returned events. E.g.: {“types”:[“m.room.message”]}

Room: Create

Parameter	Type	Required	Default	Description
Room Name	string	Yes	—	Display name for the new room. Supports expressions.
Preset	options	Yes	public_chat	Room visibility preset.
				Options: private_chat (private room), public_chat (open and public chat)
Room Alias	string	No	—	Optional local alias for the room (e.g., coolest-room-around becomes #coolest-room-around:server). Supports expressions.

Room: Invite

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	Room ID to invite the user to. Supports expressions.
User ID	string	Yes	—	Fully qualified Matrix user ID to invite. Supports expressions like {{ $json.userId }}.

Room: Join

Parameter	Type	Required	Default	Description
Room ID or Alias	string	Yes	—	Room ID or alias to join (e.g., !abc:matrix.org or #room:matrix.org). Supports expressions.

Room: Kick

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	Room ID to kick the user from. Supports expressions.
User ID	string	Yes	—	Fully qualified Matrix user ID to kick. Supports expressions.
Reason	string	No	—	Optional reason for the kick. Supports expressions.

Room: Leave

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	Room ID to leave. Supports expressions.

Room Member: Get Many

Parameter	Type	Required	Default	Description
Room ID	string	Yes	—	Room ID to get members from. Supports expressions.
Filters	collection	No	{}	Narrow the member list by membership state.
— Membership	options	No	—	Only include members with this membership status.
				Options: ban (users removed from the room), invite (users invited to join), join (users currently in the room), leave (users who left) — leave unset for Any
— Exclude Membership	options	No	—	Exclude members with this membership status.
				Options: ban (users removed from the room), invite (users invited to join), join (users currently in the room), leave (users who left) — leave unset for no exclusion

All Operations

Parameter	Type	Required	Default	Description
Max Concurrency	number	No	10	Maximum number of items to process concurrently.

Output Data

The Matrix API response is merged into the item JSON at the top level, so the fields the input item already carried pass through unchanged and binary data is forwarded.

Operation	Output items
account / me	One item per input item, carrying the account information the homeserver returned
event / get	One item per input item, carrying the event
media / upload	One item per input item, carrying the send response plus content_uri, fileName and mimeType
message / create	One item per input item, carrying the send response
message / getAll	Fans out — one output item per message. A room with no matching messages yields a single item carrying messages: []
room / create	One item per input item, carrying the new room’s identifiers
room / invite, join, kick, leave	One item per input item. Matrix answers these with an empty or near-empty body, so the item is effectively the input passed through
roomMember / getAll	Fans out — one output item per member. A room with no matching members yields a single item carrying members: []

The two getAll operations are the only ones that change the item count: fifty messages become fifty items, each a copy of the input item’s JSON with one message’s fields merged on. No Split Out node is needed after them.

After a media upload, content_uri is the mxc:// address the homeserver assigned to the file — reference it downstream as {{ $json.content_uri }} to embed the same file in another message.

Usage Examples

• Send a text message to a Matrix room
• Upload an image to a Matrix room
• Get all messages from a Matrix room
• Create a new public Matrix room
• Invite a user to a Matrix room
• Kick a user from a Matrix room
• Get current Matrix account info
• Get an event by ID from a room
• Get all members of a Matrix room

Example Configuration

Get the account the credential belongs to:

{
  "type": "matrix",
  "parameters": {
    "resource": "account",
    "operation": "me"
  }
}

Fetch one event by ID:

{
  "type": "matrix",
  "parameters": {
    "resource": "event",
    "operation": "get",
    "roomId": "!abc123:matrix.org",
    "eventId": "$event123:matrix.org"
  }
}

Upload an image an upstream node produced:

{
  "type": "matrix",
  "parameters": {
    "resource": "media",
    "operation": "upload",
    "roomId": "!abc123:matrix.org",
    "binaryPropertyName": "data",
    "mediaType": "image",
    "additionalFields": {
      "fileName": "screenshot.png"
    }
  }
}

Send a plain text message:

{
  "type": "matrix",
  "parameters": {
    "resource": "message",
    "operation": "create",
    "roomId": "!abc123:matrix.org",
    "text": "Hello, Matrix!",
    "messageType": "m.text",
    "messageFormat": "plain"
  }
}

Send an HTML message with a plain-text fallback:

{
  "type": "matrix",
  "parameters": {
    "resource": "message",
    "operation": "create",
    "roomId": "!abc123:matrix.org",
    "text": "<strong>Hello</strong>, {{ $json.name }}!",
    "messageType": "m.text",
    "messageFormat": "org.matrix.custom.html",
    "fallbackText": "Hello, {{ $json.name }}!"
  }
}

Get the most recent messages in a room, restricted to real chat events:

{
  "type": "matrix",
  "parameters": {
    "resource": "message",
    "operation": "getAll",
    "roomId": "!abc123:matrix.org",
    "returnAll": false,
    "limit": 50,
    "otherOptions": {
      "filter": "{\"types\":[\"m.room.message\"]}"
    }
  }
}

Get every message in a room:

{
  "type": "matrix",
  "parameters": {
    "resource": "message",
    "operation": "getAll",
    "roomId": "!abc123:matrix.org",
    "returnAll": true
  }
}

Create a private room with an alias:

{
  "type": "matrix",
  "parameters": {
    "resource": "room",
    "operation": "create",
    "roomName": "Team Discussion",
    "preset": "private_chat",
    "roomAlias": "team-discussion"
  }
}

Join a room by alias:

{
  "type": "matrix",
  "parameters": {
    "resource": "room",
    "operation": "join",
    "roomIdOrAlias": "#general:matrix.org"
  }
}

Invite a user:

{
  "type": "matrix",
  "parameters": {
    "resource": "room",
    "operation": "invite",
    "roomId": "!abc123:matrix.org",
    "userId": "@user:matrix.org"
  }
}

Kick a user with a reason:

{
  "type": "matrix",
  "parameters": {
    "resource": "room",
    "operation": "kick",
    "roomId": "!abc123:matrix.org",
    "userId": "@user:matrix.org",
    "reason": "Violation of room rules"
  }
}

Leave a room:

{
  "type": "matrix",
  "parameters": {
    "resource": "room",
    "operation": "leave",
    "roomId": "!abc123:matrix.org"
  }
}

List the joined members of a room, excluding banned users:

{
  "type": "matrix",
  "parameters": {
    "resource": "roomMember",
    "operation": "getAll",
    "roomId": "!abc123:matrix.org",
    "filters": {
      "membership": "join",
      "notMembership": "ban"
    }
  }
}

Error Handling

Mode	Behavior
stop	Halts workflow on first error
continue	Skips failed items, passes successful ones through
errorPort	Routes failed items to Error output port

Tips

Matrix decentralized communication: send messages, upload media, manage rooms and members via the Client-Server API.

Parameter Dependencies Summary

• operation options depend on resource selection
• Event parameters require both roomId and eventId
• Media upload requires roomId, binaryPropertyName, and mediaType
• HTML messages should also set fallbackText when messageFormat is HTML
• Message retrieval with limits requires returnAll: false and limit
• Room operations require appropriate identifiers (roomId, userId, roomIdOrAlias)
• Collection parameters use flat object structure without arrays or _default keys

Key Notes

• Room IDs start with !, aliases with #. Only Room: Join accepts either; every other operation wants the ID. Account > Me is the quickest way to list the rooms you have joined.
• Filter takes a JSON string, not a keyword — for example {"types":["m.room.message"]}.
• Media upload is one node, two steps. The file is uploaded and then posted into the room in a single execution, so you do not need a separate send node afterwards.