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

> Node: HelpScout (`helpscout`) · Action (binary) · v1
> Category: Productivity · Credentials: HelpScout OAuth2 (`helpScoutOAuth2Api`)
> Updated: 2026-08-16

# HelpScout

> Manage HelpScout conversations, customers, mailboxes, and threads

## Overview

HelpScout integration for the Mailbox API v2. Supports CRUD operations on conversations (create, delete, get, getAll), customers (create, get, getAll, properties, update), mailboxes (get, getAll), and threads (create with file attachments, getAll). Thread creation supports binary attachments that are base64-encoded and sent to the HelpScout API. Uses OAuth2 client credentials authentication.

**Category:** Productivity  
**Tool Name:** `helpscout`  
**Version:** 1

**Appearance:** Icon: `si-helpscout` | Color: `#1292EE`

## Node Type

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

## Input / Output

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

## Credentials

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

### Resources

| Resource | Value |
|----------|-------|
| Conversation | `conversation` |
| Customer | `customer` |
| Mailbox | `mailbox` |
| Thread | `thread` |

### Operations

**Conversation** (`conversation`)

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a new conversation |
| Delete | `delete` | Delete a conversation |
| Get | `get` | Get a conversation |
| Get Many | `getAll` | Get many conversations |

**Customer** (`customer`)

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a new customer |
| Get | `get` | Get a customer |
| Get Many | `getAll` | Get many customers |
| Properties | `properties` | Get customer property definitions |
| Update | `update` | Update a customer |

**Mailbox** (`mailbox`)

| Operation | Value | Description |
|-----------|-------|-------------|
| Get | `get` | Get a mailbox |
| Get Many | `getAll` | Get many mailboxes |

**Thread** (`thread`)

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a new thread |
| Get Many | `getAll` | Get many threads |

### Parameters

`Customer: Properties` takes no parameters of its own — see All Operations.

String, number, JSON and collection fields are resolved per input item, so they accept `{{ $json.field }}` expressions.

#### Conversation: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mailbox ID (`mailboxId`) | `string` | Yes | — | ID of the mailbox where the conversation is being created. Use the Mailbox: Get Many operation to find mailbox IDs. |
| Status | `options` | Yes | `active` | Conversation status. |
| | | | | Options: `active`, `closed`, `pending` |
| Subject | `string` | Yes | — | Conversation subject line. |
| Type (`type`) | `options` | Yes | `email` | Conversation type. |
| | | | | Options: `chat`, `email`, `phone` |
| Resolve Data (`resolveData`) | `boolean` | No | `true` | Whether to fetch the full conversation after creation. If false, only the ID and URI are returned. |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Optional fields to set on the new conversation. One of Customer Email or Customer ID must be set here, or the item fails. |
| — Assign To | `number` | No | `0` | User ID to assign the conversation to. |
| — Auto Reply | `boolean` | No | `false` | Whether to send an auto-reply if there is at least one customer thread. |
| — Closed At | `string` | No | — | ISO 8601 datetime when the conversation was closed (for imports). |
| — Created At | `string` | No | — | ISO 8601 datetime when the conversation was created. |
| — Customer Email | `string` | No | — | Customer email address. Either this or Customer ID is required. |
| — Customer ID | `number` | No | `0` | Customer ID. Either this or Customer Email is required. |
| — Imported | `boolean` | No | `false` | Whether to suppress outgoing emails and notifications. |
| — Tags | `string` | No | — | Comma-separated list of tag names to add to the conversation. |
| — User ID | `number` | No | `0` | ID of the user creating the conversation. |
| Threads | `json` | No | `[]` | JSON array of thread objects. Each thread: { "type": "chat\|customer\|note\|phone\|reply", "text": "message body", "bcc": [], "cc": [], "draft": false }. |

#### Conversation: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Conversation ID (`conversationId`) | `string` | Yes | — | The ID of the conversation. |

#### Conversation: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Conversation ID (`conversationId`) | `string` | Yes | — | The ID of the conversation. |

#### Conversation: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All (`returnAll`) | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit (`limit`) | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |
| Options (`options`) | `collection` | No | `{}` | Filters and sorting for the conversation listing. |
| — Assign To | `number` | No | `0` | Filter by assignee user ID. |
| — Embed | `options` | No | — | Embed thread data in the response. |
| | | | | Options: `threads` |
| — Folder ID | `string` | No | — | Filter by folder ID. |
| — Mailbox ID | `string` | No | — | Filter by mailbox ID. |
| — Modified Since | `string` | No | — | ISO 8601 datetime. Returns only conversations modified after this date. |
| — Number | `number` | No | `0` | Look up by conversation number. |
| — Query | `string` | No | — | Advanced search query string. |
| — Sort Field | `options` | No | — | Field the results are sorted on. |
| | | | | Options: `createdAt`, `customerEmail`, `customerName`, `mailboxid`, `modifiedAt`, `number`, `score`, `status`, `subject` |
| — Sort Order | `options` | No | `desc` | Sort direction. |
| | | | | Options: `asc`, `desc` |
| — Status | `options` | No | `active` | Filter conversations by status. |
| | | | | Options: `active`, `all`, `closed`, `open`, `pending`, `spam` |
| — Tags | `string` | No | — | Comma-separated tag names to filter by. |

#### Customer: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Resolve Data (`resolveData`) | `boolean` | No | `true` | Whether to fetch the full customer record after creation. |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Customer fields to set. At least one field across this collection and the JSON fields below must be set, or the item fails. |
| — Age | `number` | No | `1` | Customer age. |
| — First Name | `string` | No | — | First name (1-40 characters). |
| — Gender | `options` | No | — | Customer gender. |
| | | | | Options: `female`, `male`, `unknown` |
| — Job Title | `string` | No | — | Job title (max 60 characters). |
| — Last Name | `string` | No | — | Customer last name. |
| — Location | `string` | No | — | Customer location. |
| — Notes | `string` | No | — | Background notes about the customer. |
| — Organization | `string` | No | — | Company or organization the customer belongs to. |
| — Photo URL | `string` | No | — | URL of the customer's photo. |
| Address | `json` | No | `{}` | JSON object: { "line1": "", "line2": "", "city": "", "state": "", "country": "US", "postalCode": "" }. |
| Emails | `json` | No | `[]` | JSON array: [{ "type": "work\|home\|other", "value": "email@example.com" }]. |
| Phones | `json` | No | `[]` | JSON array: [{ "type": "work\|home\|fax\|pager\|other", "value": "+1234567890" }]. |
| Chat Handles | `json` | No | `[]` | JSON array: [{ "type": "aim\|gtalk\|icq\|msn\|other\|qq\|skype\|xmpp\|yahoo", "value": "handle" }]. |
| Social Profiles | `json` | No | `[]` | JSON array: [{ "type": "facebook\|twitter\|linkedin\|...", "value": "url_or_handle" }]. |
| Websites | `json` | No | `[]` | JSON array: [{ "value": "https://example.com" }]. |

#### Customer: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Customer ID | `string` | Yes | — | The ID of the customer. |

#### Customer: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All (`returnAll`) | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit (`limit`) | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |
| Options (`options`) | `collection` | No | `{}` | Filters and sorting for the customer listing. |
| — First Name | `string` | No | — | Filter by first name. |
| — Last Name | `string` | No | — | Filter by last name. |
| — Mailbox ID | `string` | No | — | Filter by mailbox ID. |
| — Modified Since | `string` | No | — | ISO 8601 datetime filter. |
| — Sort Field | `options` | No | `score` | Field the results are sorted on. |
| | | | | Options: `score`, `firstName`, `lastName`, `modifiedAt` |
| — Sort Order | `options` | No | `desc` | Sort direction. |
| | | | | Options: `asc`, `desc` |
| — Query | `string` | No | — | Advanced search query. |

#### Customer: Update

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Customer ID | `string` | Yes | — | The ID of the customer. |
| Update Fields | `collection` | No | `{}` | Fields to change on the customer — set at least one, otherwise the item fails. |
| — Age | `number` | No | `1` | Customer age. |
| — First Name | `string` | No | — | Customer first name. |
| — Gender | `options` | No | — | Customer gender. |
| | | | | Options: `female`, `male`, `unknown` |
| — Job Title | `string` | No | — | Customer job title. |
| — Last Name | `string` | No | — | Customer last name. |
| — Location | `string` | No | — | Customer location. |
| — Notes | `string` | No | — | Background notes about the customer. |
| — Organization | `string` | No | — | Company or organization the customer belongs to. |
| — Photo URL | `string` | No | — | URL of the customer's photo. |

#### Mailbox: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Mailbox ID (`mailboxId`) | `string` | Yes | — | The ID of the mailbox. |

#### Mailbox: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All (`returnAll`) | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit (`limit`) | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |

#### Thread: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Conversation ID (`conversationId`) | `string` | Yes | — | The ID of the conversation to add the thread to. |
| Type (`type`) | `options` | Yes | `note` | The type of thread to create. |
| | | | | Options: `chat`, `customer`, `note`, `phone`, `reply` |
| Text | `string` | Yes | — | The message body text (HTML supported). |
| Additional Fields (`additionalFields`) | `collection` | No | `{}` | Optional fields to set on the new thread. One of Customer Email or Customer ID must be set here, or the item fails. |
| — Created At | `string` | No | — | ISO 8601 datetime for thread creation time. |
| — Customer Email | `string` | No | — | Customer email. Either this or Customer ID is required. |
| — Customer ID | `number` | No | `0` | Customer ID. Either this or Customer Email is required. |
| — Draft | `boolean` | No | `false` | Whether to create as a draft (note type only). |
| — Imported | `boolean` | No | `false` | Whether to suppress outgoing emails and notifications. |
| Manual Attachments | `json` | No | `[]` | JSON array of manual attachments: [{ "fileName": "file.pdf", "mimeType": "application/pdf", "data": "base64string" }]. |
| Binary Attachment Properties | `string` | No | — | Comma-separated binary property names to attach (e.g. "data,attachment_0"). Each binary property will be base64-encoded and sent as an attachment. |

#### Thread: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Conversation ID (`conversationId`) | `string` | Yes | — | The ID of the conversation to get threads for. |
| Return All (`returnAll`) | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit (`limit`) | `number` | No | `50` | Max number of results to return. _(shown when Return All is `false`)_ |

#### All Operations

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

## Output Data

Exactly **one output item per input item** — this node never fans out, not even on the Get Many operations. Binary data on the input item is forwarded unchanged; attachments you send with a thread are uploaded to HelpScout and are not returned as binary.

How the response reaches the item depends on its shape:

- **Listings are nested, not merged.** When HelpScout returns an array, the records are written to `results` on the output item and their number to `resultCount`. The rest of the item JSON passes through untouched. An empty listing still produces one item, with `results: []` and `resultCount: 0`.
- **Single records are merged at the top level.** When HelpScout returns one object, its fields are spread onto the item JSON, so response fields can overwrite incoming fields of the same name.
- **Operations with no response body set `success: true`** on the item, leaving the rest of the item JSON in place.

| Operation | What lands on the output item |
|-----------|-------------------------------|
| `Conversation: Create` | The full conversation record merged at the top level when Resolve Data is on; with it off, only `id` and `uri` |
| `Conversation: Delete` | `success: true` |
| `Conversation: Get` | The conversation record merged at the top level |
| `Conversation: Get Many` | `results` (conversations) and `resultCount` |
| `Customer: Create` | The full customer record merged at the top level when Resolve Data is on; with it off, only `id` and `uri` |
| `Customer: Get` | The customer record merged at the top level |
| `Customer: Get Many` | `results` (customers) and `resultCount` |
| `Customer: Properties` | `results` (property definitions) and `resultCount` |
| `Customer: Update` | `success: true` |
| `Mailbox: Get` | The mailbox record merged at the top level |
| `Mailbox: Get Many` | `results` (mailboxes) and `resultCount` |
| `Thread: Create` | `success: true` |
| `Thread: Get Many` | `results` (threads) and `resultCount` |

Reference the result downstream by expression — `{{ $json.resultCount }}` for a listing, `{{ $json.id }}` for a create with Resolve Data off. Because listings arrive as one item holding an array, use a Split Out node on `results` when you need one workflow item per record.

## Usage Examples

- Create a new conversation in HelpScout
- List all customers
- Add a thread with file attachment to a conversation
- Get conversation details by ID
- Update customer information

## Example Configuration

Create a new conversation:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "conversation",
    "operation": "create",
    "mailboxId": "12345",
    "subject": "Customer Support Request",
    "type": "email",
    "status": "active",
    "resolveData": true,
    "additionalFields": {
      "customerEmail": "customer@example.com",
      "tags": "urgent,billing",
      "assignTo": 67890
    },
    "threads": [
      {
        "type": "customer",
        "text": "I need help with my billing inquiry.",
        "draft": false
      }
    ]
  }
}
```

Get all conversations with filters:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "conversation",
    "operation": "getAll",
    "returnAll": false,
    "limit": 50,
    "options": {
      "status": "active",
      "mailbox": "12345",
      "sortField": "createdAt",
      "sortOrder": "desc",
      "query": "billing"
    }
  }
}
```

Create a new customer:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "create",
    "resolveData": true,
    "additionalFields": {
      "firstName": "John",
      "lastName": "Doe",
      "organization": "Acme Corp",
      "jobTitle": "Manager"
    },
    "emails": [
      {
        "type": "work",
        "value": "john.doe@acme.com"
      }
    ],
    "phones": [
      {
        "type": "work",
        "value": "+1-555-123-4567"
      }
    ],
    "address": {
      "line1": "123 Business St",
      "city": "Business City",
      "state": "BC",
      "country": "US",
      "postalCode": "12345"
    }
  }
}
```

Update a customer:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "update",
    "customerId": "98765",
    "updateFields": {
      "jobTitle": "Senior Manager",
      "organization": "Acme Corporation",
      "location": "New York, NY"
    }
  }
}
```

Create a thread with attachments:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "thread",
    "operation": "create",
    "conversationId": "54321",
    "type": "reply",
    "text": "Thank you for contacting us. Please find the requested document attached.",
    "additionalFields": {
      "draft": false,
      "customerEmail": "customer@example.com"
    },
    "attachmentsManual": [
      {
        "fileName": "invoice.pdf",
        "mimeType": "application/pdf",
        "data": "JVBERi0xLjQKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
      }
    ]
  }
}
```

Get all customers with a search query:

```json
{
  "type": "helpscout",
  "parameters": {
    "resource": "customer",
    "operation": "getAll",
    "returnAll": false,
    "limit": 25,
    "options": {
      "query": "john",
      "sortField": "score",
      "sortOrder": "desc",
      "modifiedSince": "2024-01-01T00:00:00Z"
    }
  }
}
```

### 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 HelpScout conversations, customers, mailboxes, and threads with file attachment support via the Mailbox API v2.