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

> Node: Twist (`twist`) · Action (binary) · v1
> Category: Communication · Credentials: Twist OAuth2 API (`twistOAuth2Api`)
> Updated: 2026-08-16

# Twist

> Manage channels, comments, conversation messages, and threads in Twist.

## Overview

Twist tool integrates with the Twist API v3 to manage team communication. Supports 4 resources: channel (create/delete/get/getAll/update/archive/unarchive), comment (create/delete/get/getAll/update), message — conversation messages (create/delete/get/getAll/update), and thread (create/delete/get/getAll/update). All write operations support optional file attachments via binary store upload and direct user mentions. Uses OAuth2 Bearer token authentication with automatic token refresh.

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

**Appearance:** Icon: `lucide-MessageSquare` | Color: `#4E92DF`

## Node Type

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

## Input / Output

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

## Credentials

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

### Resources

| Resource | Value |
|----------|-------|
| Channel | `channel` |
| Comment | `comment` |
| Message (Conversation) | `message` |
| Thread | `thread` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Archive | `archive` | Archive a channel |
| Create | `create` | Create a new channel |
| Delete | `delete` | Delete a channel |
| Get | `get` | Get information about a channel |
| Get Many | `getAll` | Get many channels in a workspace |
| Unarchive | `unarchive` | Unarchive a channel |
| Update | `update` | Update a channel |
| Create | `create` | Create a comment on a thread |
| Delete | `delete` | Delete a comment |
| Get | `get` | Get information about a comment |
| Get Many | `getAll` | Get many comments on a thread |
| Update | `update` | Update a comment |
| Create | `create` | Create a message in a conversation |
| Delete | `delete` | Delete a message |
| Get | `get` | Get a message |
| Get Many | `getAll` | Get many messages in a conversation |
| Update | `update` | Update a message |
| Create | `create` | Create a new thread in a channel |
| Delete | `delete` | Delete a thread |
| Get | `get` | Get information about a thread |
| Get Many | `getAll` | Get many threads in a channel |
| Update | `update` | Update a thread |

`archive` and `unarchive` exist only on Channel. Every other operation value is offered on all four resources, with the description above matching the resource it belongs to, in Channel → Comment → Message → Thread order.

### Parameters

#### Channel: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace ID | `string` | Yes | — | The ID of the Twist workspace. Supports expressions. |
| Name | `string` | Yes | — | The name of the channel. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional channel settings. |
| — Color | `options` | No | `0` | The color of the channel. |
| | | | | Options: `0` (Grey), `1` (Blue), `2` (Turquoise), `3` (Teal Blue), `4` (Green), `5` (Red), `6` (Berry Red), `7` (Magenta), `8` (Sky Blue), `9` (Mint Green), `10` (Yellow), `11` (Salmon) |
| — Description | `string` | No | — | The description of the channel. |
| — Public | `boolean` | No | `false` | Whether the channel will be marked as public. |

#### Channel: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace ID | `string` | Yes | — | The ID of the Twist workspace. Supports expressions. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Maximum number of results to return. _(shown when Return All is `false`)_ |
| Filters | `collection` | No | `{}` | Narrows the channel list. |
| — Archived | `boolean` | No | `false` | Whether to return only archived channels. |

#### Channel: Get

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

#### Channel: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |
| Update Fields | `collection` | No | `{}` | Fields to change on the channel. |
| — Color | `options` | No | `0` | The color of the channel. |
| | | | | Options: `0` (Grey), `1` (Blue), `2` (Turquoise), `3` (Teal Blue), `4` (Green), `5` (Red), `6` (Berry Red), `7` (Magenta), `8` (Sky Blue), `9` (Mint Green), `10` (Yellow), `11` (Salmon) |
| — Description | `string` | No | — | The description of the channel. |
| — Name | `string` | No | — | The name of the channel. |
| — Public | `boolean` | No | `false` | Whether the channel will be marked as public. |

#### Channel: Delete

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

#### Channel: Archive

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

#### Channel: Unarchive

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

#### Comment: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Thread ID | `string` | Yes | — | The ID of the thread. Supports expressions. |
| Content | `string` | Yes | — | The content of the comment. Supports expressions like {{ $json.body }}. |
| Additional Fields | `collection` | No | `{}` | Optional comment settings. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. Each action object should have: type, button_text, action, and optionally url or message. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. Separate multiple properties with commas. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. Each will be prepended to content as [Name](twist-mention://userId). |
| — Recipients (User IDs) | `string` | No | — | Comma-separated user IDs to attach to the comment. |
| — Send as Integration | `boolean` | No | `false` | Whether to display the integration as the comment creator. |
| — Mark Thread Position | `boolean` | No | `true` | Whether to mark the position of the thread. |

#### Comment: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Thread ID | `string` | Yes | — | The ID of the thread. Supports expressions. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Maximum number of results to return. _(shown when Return All is `false`)_ |
| Filters | `collection` | No | `{}` | Narrows the comment list. |
| — As IDs | `boolean` | No | `false` | Whether to return only the IDs of the comments (as a flat array mapped to [{ID: id}]). |
| — Newer Than | `dateTime` | No | — | Limit comments to those newer than this datetime (converted to Unix timestamp). |
| — Older Than | `dateTime` | No | — | Limit comments to those older than this datetime (converted to Unix timestamp). |
| — Order By | `options` | No | `ASC` | Order of the comments returned. |
| | | | | Options: `ASC`, `DESC` |
| — From Object Index | `number` | No | `0` | Limit comments starting at the specified object index. |
| — To Object Index | `number` | No | `50` | Limit comments ending at the specified object index. |

#### Comment: Get

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

#### Comment: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Comment ID | `string` | Yes | — | The ID of the comment. Supports expressions. |
| Update Fields | `collection` | No | `{}` | Fields to change on the comment. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. |
| — Content | `string` | No | — | The updated content of the comment. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. |

#### Comment: Delete

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

#### Message (Conversation): Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace ID | `string` | Yes | — | The ID of the Twist workspace. Supports expressions. |
| Conversation ID | `string` | Yes | — | The ID of the conversation. Supports expressions. |
| Content | `string` | No | — | The content of the message. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional message settings. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. |

#### Message (Conversation): Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace ID | `string` | Yes | — | The ID of the Twist workspace. Supports expressions. |
| Conversation ID | `string` | Yes | — | The ID of the conversation. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Paging and sorting for the message list. |
| — Limit | `number` | No | `50` | Maximum number of messages to return. |
| — Order By | `options` | No | `ASC` | Order of the messages returned. |
| | | | | Options: `ASC`, `DESC` |
| — From Object Index | `number` | No | `0` | Limit messages starting at the specified object index. |
| — To Object Index | `number` | No | `50` | Limit messages ending at the specified object index. |

#### Message (Conversation): Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Message ID | `string` | Yes | — | The ID of the conversation message. Supports expressions. |

#### Message (Conversation): Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Message ID | `string` | Yes | — | The ID of the conversation message. Supports expressions. |
| Update Fields | `collection` | No | `{}` | Fields to change on the message. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. |
| — Content | `string` | No | — | The updated content of the message. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. |

#### Message (Conversation): Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Message ID | `string` | Yes | — | The ID of the conversation message. Supports expressions. |

#### Thread: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |
| Title | `string` | Yes | — | The title of the new thread (1 to 300 characters). Supports expressions. |
| Content | `string` | Yes | — | The content of the thread. Supports expressions. |
| Additional Fields | `collection` | No | `{}` | Optional thread settings. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. |
| — Recipients (User IDs) | `string` | No | — | Comma-separated user IDs to attach to the thread. |
| — Send as Integration | `boolean` | No | `false` | Whether to display the integration as the thread creator. |

#### Thread: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Channel ID | `string` | Yes | — | The ID of the channel. Supports expressions. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `50` | Maximum number of results to return. _(shown when Return All is `false`)_ |
| Filters | `collection` | No | `{}` | Narrows the thread list. |
| — As IDs | `boolean` | No | `false` | Whether to return only the IDs of the threads. |
| — Filter By | `options` | No | — | Filter threads by attachment or star status. |
| | | | | Options: empty (None), `attached_to_me`, `everyone`, `is_starred` |
| — Newer Than | `dateTime` | No | — | Limit threads to those newer than this datetime. |
| — Older Than | `dateTime` | No | — | Limit threads to those older than this datetime. |

#### Thread: Get

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

#### Thread: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Thread ID | `string` | Yes | — | The ID of the thread. Supports expressions. |
| Update Fields | `collection` | No | `{}` | Fields to change on the thread. |
| — Actions (JSON) | `json` | No | `[]` | Interactive action buttons as a JSON array. |
| — Attachments (Binary Property) | `string` | No | `data` | Name of the binary property containing the file to attach. |
| — Content | `string` | No | — | The updated content of the thread. |
| — Direct Mentions (User IDs) | `string` | No | — | Comma-separated user IDs to directly mention. |
| — Title | `string` | No | — | The updated title of the thread. |

#### Thread: Delete

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

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Twist Account | `credential` | No | — | Connect your Twist account via OAuth2. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

The Twist API response is merged onto the top level of the item JSON; anything already on the item passes through.

- **Single-object operations** (`create`, `get`, `update`, `delete`, `archive`, `unarchive`) produce **one output item per input item**, carrying the channel, comment, message or thread object Twist returned. `comment` → `get` unwraps Twist's `comment` envelope so the comment's own fields land directly on the item.
- **`getAll` on any resource fans out**: one output item per record returned. When the list comes back empty the node still emits a single item carrying `results: []`, so a downstream branch always fires.
- Operations that return an empty body land `success: true` on the item.

Binary attachments are consumed on the way out (uploaded to Twist), so binary properties are not carried onto the output items.

## Usage Examples

- Create a new channel in a Twist workspace
- Post a message to a Twist conversation
- Create a thread in a Twist channel
- Add a comment to a Twist thread
- List all channels in a workspace
- Archive a Twist channel
- Get all threads in a channel
- Update a comment on a thread
- Upload a file attachment with a comment
- Mention users directly in a thread post

## Example Configuration

Create a channel:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "channel",
    "operation": "create",
    "workspaceId": "12345",
    "name": "New Project Channel",
    "additionalFields": {
      "description": "Channel for discussing the new project",
      "public": true,
      "color": 2
    }
  }
}
```

List the first 20 active channels in a workspace:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "channel",
    "operation": "getAll",
    "workspaceId": "12345",
    "returnAll": false,
    "limit": 20,
    "filters": {
      "archived": false
    }
  }
}
```

Rename a channel and make it private:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "channel",
    "operation": "update",
    "channelId": "67890",
    "updateFields": {
      "name": "Updated Channel Name",
      "description": "Updated description",
      "public": false
    }
  }
}
```

Start a thread and mention two people by user ID:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "thread",
    "operation": "create",
    "channelId": "67890",
    "title": "Weekly Planning Discussion",
    "content": "Let's discuss our plans for next week",
    "additionalFields": {
      "direct_mentions": "451234,451299",
      "send_as_integration": false
    }
  }
}
```

List recent unread-style threads with a date filter:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "thread",
    "operation": "getAll",
    "channelId": "67890",
    "returnAll": false,
    "limit": 15,
    "filters": {
      "newer_than_ts": "2026-01-01T00:00:00Z",
      "filter_by": "attached_to_me"
    }
  }
}
```

Comment on a thread:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "comment",
    "operation": "create",
    "threadId": "98765",
    "content": "I agree with this approach",
    "additionalFields": {
      "direct_mentions": "451234",
      "mark_thread_position": true
    }
  }
}
```

Page through comments oldest-first:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "comment",
    "operation": "getAll",
    "threadId": "98765",
    "returnAll": false,
    "limit": 10,
    "filters": {
      "order_by": "ASC",
      "from_obj_index": 0,
      "to_obj_index": 50
    }
  }
}
```

Post a conversation message:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "message",
    "operation": "create",
    "workspaceId": "12345",
    "conversationId": "conv123",
    "content": "Quick update on the project status",
    "additionalFields": {
      "direct_mentions": "451234"
    }
  }
}
```

Read the newest messages in a conversation:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "message",
    "operation": "getAll",
    "workspaceId": "12345",
    "conversationId": "conv123",
    "additionalFields": {
      "limit": 25,
      "order_by": "DESC",
      "from_obj_index": 0,
      "to_obj_index": 100
    }
  }
}
```

Attach a file from an upstream node to a new comment:

```json
{
  "type": "twist",
  "parameters": {
    "resource": "comment",
    "operation": "create",
    "threadId": "{{ $json.threadId }}",
    "content": "Report attached.",
    "additionalFields": {
      "binaryProperties": "data"
    }
  }
}
```

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

Manage channels, comments, messages, and threads in Twist.

### Parameter Dependencies

The Twist tool has a hierarchical parameter dependency structure:

1. **resource** → **operation** (determines available operations)
2. **resource + operation** → determines required ID parameters
3. **operation type** → determines available field collections
4. **returnAll** → controls **limit** parameter visibility
5. **field collections** → contain operation-specific nested fields

Always ensure the correct ID parameters are provided based on the resource and operation combination.

### Attachments and Mentions

- Attachments are read from the input item's binary properties. Name them in **Attachments (Binary Property)**; separate several with commas, and match the exact case shown in the upstream node's Binary Data panel.
- **Direct Mentions** takes Twist *user IDs*, not @handles. Each ID is prepended to the content as a Twist mention link.