<!-- BusyBot node reference — https://busybot.net/tools/matrix/ -->

> Node: Matrix (`matrix`) · Action (binary) · v1
> Category: Communication · Credentials: Matrix API (`matrixApi`)
> Updated: 2026-08-16

# 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](https://busybot.net/credentials/matrix-api/) 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:

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

Fetch one event by ID:

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

Upload an image an upstream node produced:

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

Send a plain text message:

```json
{
  "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:

```json
{
  "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:

```json
{
  "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:

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

Create a private room with an alias:

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

Join a room by alias:

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

Invite a user:

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

Kick a user with a reason:

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

Leave a room:

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

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

```json
{
  "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.