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

> Node: Mattermost (`mattermost`) · Action (binary) · v1
> Category: Communication · Credentials: Mattermost API (`mattermostApi`)
> Updated: 2026-08-16

# Mattermost

> Manage channels, messages, reactions, and users on Mattermost

## Overview

The Mattermost tool interacts with a self-hosted Mattermost server via its REST API v4. It supports four resources: Channel (create, delete, addUser, members, restore, search, statistics), Message (post with optional file attachments and rich attachments, delete, postEphemeral), Reaction (create, delete, getAll), and User (create, deactivate, getAll, getByEmail, getById, invite). The message:post operation supports binary file uploads.

**Category:** Communication  
**Tool Name:** `mattermost`  
**Version:** 1

**Appearance:** Icon: `si-mattermost` | Color: `#0058CC`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **Mattermost API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/mattermost-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Channel | `channel` |
| Message | `message` |
| Reaction | `reaction` |
| User | `user` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Add User | `addUser` | Add a user to a channel |
| Create | `create` | Create a new channel |
| Delete | `delete` | Soft-delete a channel |
| Members | `members` | Get members of a channel |
| Restore | `restore` | Restore a soft-deleted channel |
| Search | `search` | Search for channels in a team |
| Statistics | `statistics` | Get statistics for a channel |
| Delete | `delete` | Soft-delete a post |
| Post | `post` | Post a message into a channel |
| Post Ephemeral | `postEphemeral` | Post an ephemeral message visible to one user |
| Create | `create` | Add a reaction to a post |
| Delete | `delete` | Remove a reaction from a post |
| Get Many | `getAll` | Get all reactions for a post |
| Create | `create` | Create a new user |
| Deactivate | `deactivate` | Deactivate a user |
| Get By Email | `getByEmail` | Get a user by email |
| Get By ID | `getById` | Get users by their IDs |
| Get Many | `getAll` | Get many users |
| Invite | `invite` | Invite users to a team by email |

The operation list is scoped to the resource you pick, which is why `create`, `delete` and `getAll` each appear more than once.

### Parameters

#### Channel: Add User

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel to add the user to. Supports expressions. |
| User ID | `string` | Yes | — | The ID of the user to add to the channel. Supports expressions like {{ $json.userId }}. |

#### Channel: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Team ID | `string` | Yes | — | The ID of the team to create the channel in. Find in Mattermost team settings. Supports expressions. |
| Display Name | `string` | Yes | — | The non-unique display name for the channel (e.g. "Announcements"). Supports expressions. |
| Channel Name | `string` | Yes | — | The unique URL-safe handle for the channel (e.g. "announcements"). Supports expressions. |
| Type | `options` | No | `public` | The visibility of the channel. |
| | | | | Options: `public`, `private` |

#### Channel: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |

#### Channel: Members

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Team ID | `string` | Yes | — | The ID of the team (used for channel filtering). Supports expressions. |
| Channel ID | `string` | Yes | — | The ID of the channel to get members for. Supports expressions. |
| Resolve Data | `boolean` | No | `true` | Whether to resolve full user objects instead of just membership stubs. |
| Return All | `boolean` | No | `true` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Accepts 1–100. _(shown when Return All is `false`)_ |

#### Channel: Restore

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |

#### Channel: Search

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Team ID | `string` | Yes | — | The ID of the team to search channels in. Supports expressions. |
| Search Term | `string` | Yes | — | The term to search for in channel names. Supports expressions. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of results to return. Accepts 1–100. _(shown when Return All is `false`)_ |

#### Channel: Statistics

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |

#### Message: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Post ID | `string` | Yes | — | The ID of the post to delete. Supports expressions. |

#### Message: Post

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel to post the message in. Supports expressions. |
| Message | `string` | No | — | The message text to post. Supports expressions like {{ $json.text }}. |
| Attachments | `json` | No | `[]` | Rich message attachments as a JSON array. Each attachment can have: fallback, color, pretext, text, author_name, author_link, author_icon, title, title_link, fields (array of {title, value, short}), image_url, thumb_url, footer, footer_icon, actions. |
| Other Options | `collection` | No | `{}` | Additional options for the post. |
| — Parent Post ID (Thread) | `string` | No | — | If set, the message will be a threaded reply to this parent post. Supports expressions. |
| Send Binary Data | `boolean` | No | `false` | Whether to upload a binary file along with the message. |
| Binary Property | `string` | No | `data` | Name of the binary property on the input item to upload as a file attachment. Names are case-sensitive — see the upstream node's Binary Data panel for the exact names to use. _(shown when Send Binary Data is `true`)_ |

#### Message: Post Ephemeral

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| User ID | `string` | Yes | — | The ID of the user to send the ephemeral message to. Supports expressions. |
| Channel ID | `string` | Yes | — | The ID of the channel to send the ephemeral message in. Supports expressions. |
| Message | `string` | No | — | The ephemeral message text. Supports expressions. |

#### Reaction: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| User ID | `string` | Yes | — | The ID of the user adding the reaction. Supports expressions. |
| Post ID | `string` | Yes | — | The ID of the post to react to. Supports expressions. |
| Emoji Name | `string` | Yes | — | The emoji name without colons (e.g. "thumbsup"). Supports expressions. |

#### Reaction: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| User ID | `string` | Yes | — | The ID of the user whose reaction to remove. Supports expressions. |
| Post ID | `string` | Yes | — | The ID of the post. Supports expressions. |
| Emoji Name | `string` | Yes | — | The emoji name to remove (without colons). Supports expressions. |

#### Reaction: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Post ID | `string` | Yes | — | The ID of the post to get reactions for. Supports expressions. |
| Return All | `boolean` | No | `true` | Whether to return all reactions or limit the results. |
| Limit | `number` | No | `100` | Max number of reactions to return. Accepts 1–100. _(shown when Return All is `false`)_ |

#### User: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Username | `string` | Yes | — | The username for the new user. Supports expressions. |
| Auth Service | `options` | No | `email` | The authentication provider for the new user. |
| | | | | Options: `email`, `gitlab`, `google`, `ldap`, `office365`, `saml` |
| Email | `string` | No | — | The email address for the new user (required when auth service is email). Supports expressions. _(shown when Auth Service is `email`)_ |
| Password | `string` | No | — | The password for the new user (required when auth service is email). _(shown when Auth Service is `email`)_ |
| Auth Data | `string` | No | — | The external auth data for the user (required when auth service is not email). _(hidden when Auth Service is `email`)_ |
| Additional Fields | `collection` | No | `{}` | Optional profile fields for the new user. |
| — First Name | `string` | No | — | The user's given name. |
| — Last Name | `string` | No | — | The user's family name. |
| — Locale | `string` | No | — | The user's interface locale, e.g. `en`. |
| — Nickname | `string` | No | — | The user's nickname. |

#### User: Deactivate

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| User ID | `string` | Yes | — | The ID of the user to deactivate. Supports expressions. |

#### User: Get By Email

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Email | `string` | Yes | — | The email address to look up. Supports expressions like {{ $json.email }}. |

#### User: Get By ID

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| User IDs | `string` | Yes | — | Comma-separated list of user IDs to look up. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional filters for the lookup. |
| — Since | `string` | No | — | Only return users modified after this ISO datetime. |

#### User: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `true` | Whether to return all users or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of users to return. Accepts 1–100. _(shown when Return All is `false`)_ |
| Additional Fields | `collection` | No | `{}` | Optional scoping and ordering for the listing. |
| — In Team | `string` | No | — | Filter users by team ID. |
| — Not In Team | `string` | No | — | Exclude users in this team. |
| — In Channel | `string` | No | — | Filter users by channel ID. |
| — Not In Channel | `string` | No | — | Exclude users in this channel. |
| — Sort | `options` | No | `username` | Sort field. When sort is set, either "In Team" or "In Channel" must also be set. |
| | | | | Options: `createdAt` (Created At), `lastActivityAt` (Last Activity At), `status`, `username` |

#### User: Invite

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Team ID | `string` | Yes | — | The ID of the team to invite users to. Supports expressions. |
| Emails | `string` | Yes | — | Comma-separated list of email addresses to invite. Supports expressions. |

#### All Operations

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

## Output Data

The Mattermost 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.

Operations that return a single object — every channel operation except Members and Search, both message posts, message delete, reaction create and delete, user create, deactivate, get by email and invite — produce **one output item per input item**.

Operations that return a list **fan out**: one output item per element, each a copy of the input item's JSON with one record's fields merged on. Those are:

| Operation | One item per |
|-----------|--------------|
| `channel` / `members` | Channel member (a full user object when Resolve Data is on, otherwise a membership record) |
| `channel` / `search` | Matching channel |
| `reaction` / `getAll` | Reaction on the post |
| `user` / `getById` | User found |
| `user` / `getAll` | User in the listing |

No Split Out node is needed after those five. `Limit` caps how many items come out; `Return All` pages through everything the server has.

**File uploads.** With Send Binary Data on, the named binary property is uploaded to Mattermost and attached to the post in the same execution — there is no separate upload node.

## Usage Examples

- Post a message to a Mattermost channel
- Upload a file to a Mattermost channel with a message
- Create a new Mattermost channel
- Get all members of a channel
- Add a reaction to a post
- Invite users to a team by email
- Search for channels in a team

## Example Configuration

Create a public channel:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "channel",
    "operation": "create",
    "teamId": "team123",
    "displayName": "General Discussion",
    "channel": "general-discussion",
    "type": "public"
  }
}
```

Post a message with a file upload, as a threaded reply:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "message",
    "operation": "post",
    "channelId": "channel456",
    "message": "Here's the report you requested",
    "sendBinaryData": true,
    "binaryPropertyName": "attachment",
    "otherOptions": {
      "root_id": "{{ $json.parentPostId }}"
    }
  }
}
```

Create a user with email authentication:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "user",
    "operation": "create",
    "username": "john.doe",
    "authService": "email",
    "email": "john.doe@company.com",
    "password": "securepassword123",
    "additionalFields": {
      "first_name": "John",
      "last_name": "Doe",
      "nickname": "johndoe"
    }
  }
}
```

Create a user backed by LDAP instead:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "user",
    "operation": "create",
    "username": "jane.smith",
    "authService": "ldap",
    "authData": "jane.smith@ldap"
  }
}
```

Add a reaction to a post:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "reaction",
    "operation": "create",
    "userId": "user789",
    "postId": "post123",
    "emojiName": "thumbsup"
  }
}
```

Get channel members, capped at 50 and resolved to full user objects:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "channel",
    "operation": "members",
    "teamId": "team123",
    "channelId": "channel456",
    "resolveData": true,
    "returnAll": false,
    "limit": 50
  }
}
```

List every user in a team, sorted by username:

```json
{
  "type": "mattermost",
  "parameters": {
    "resource": "user",
    "operation": "getAll",
    "returnAll": true,
    "additionalFields": {
      "inTeam": "team123",
      "sort": "username"
    }
  }
}
```

### 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

Post messages (with file uploads), manage channels, reactions, and users on a Mattermost server.

### Key Relationships

- `authService: "email"` requires `email` and `password` parameters
- `authService` other than "email" requires `authData` parameter
- `sendBinaryData: true` requires `binaryPropertyName` parameter
- `returnAll: false` enables the `limit` parameter
- Collection parameters use flat object structure without `_default` wrapper

### Key Notes

- **Channel Name is the URL handle, Display Name is the label.** Channel Name must be unique and URL-safe; Display Name is what people see.
- **Sort needs a scope.** In User: Get Many, setting Sort also requires In Team or In Channel in the same Additional Fields collection.
- **Delete is a soft delete** for both channels and posts, and Channel: Restore brings a soft-deleted channel back.