---
name: helpscout
description: Fetch and reply to Helpscout conversations
metadata:
  {
    "openclaw":
      {
        "requires": { "env": ["API_KEY", "APP_SECRET", "INBOX_IDS"] },
      },
  }
---

# Helpscout Skill

## Description

This skill interacts with Helpscout to fetch conversations from specific inboxes and send replies. It is designed to streamline customer support operations directly from OpenClaw.

## Features
- Fetch conversations from multiple Helpscout inboxes
- Send replies to conversations (customer-visible or internal notes)
- Filter by status, folder, assignee, customer, tags, and more
- Sort conversations by various fields
- Embed thread data directly in the response
- Securely authenticate using an API key and App Secret
- Handle potential errors like invalid credentials or network issues gracefully

## Setup Instructions

To use this skill, you need to configure Helpscout credentials and specify the IDs of the inboxes you want to fetch conversations from.

### 1. Retrieve Helpscout API Key & App Secret
1. Go to your Helpscout account.
2. Navigate to **Manage > Apps**.
3. Create or open your app to retrieve the following details:
   - **API Key**
   - **App Secret**

### 2. Collect Inbox IDs
1. Retrieve the IDs of the inboxes you want to fetch conversations from using Helpscout's [API documentation](https://developer.helpscout.com/).

### 3. Save Credentials in OpenClaw
Use the following command to save your Helpscout credentials:

```bash
cat ~/.openclaw/openclaw.json | jq '.skills.entries.helpscout = {
  enabled: true,
  env: {
    API_KEY: "your-api-key",
    APP_SECRET: "your-app-secret",
    INBOX_IDS: ["inbox-id-1", "inbox-id-2"]
  }
}' | openclaw gateway config.apply
```

### 4. Verify Configuration
To ensure the credentials are properly set, check your configuration:

```bash
openclaw gateway config.get
```
Make sure the `helpscout` object looks correct (avoid sharing the `API_KEY` or `APP_SECRET`).

## Usage

### Basic Usage
Fetch all active conversations from configured inboxes:

```javascript
const { fetchAllInboxes } = require('./index.js');

// Fetch all active conversations (default)
const results = await fetchAllInboxes();
```

### Advanced Filtering

```javascript
const { fetchConversations } = require('./index.js');

// Fetch closed conversations from a specific inbox
const conversations = await fetchConversations(321755, {
  status: 'closed',
  sortField: 'modifiedAt',
  sortOrder: 'desc',
  page: 1
});

// Fetch conversations assigned to a specific user
const assigned = await fetchConversations(321755, {
  assignedTo: 782728,
  status: 'active'
});

// Fetch conversations with a specific tag
const tagged = await fetchConversations(321755, {
  tag: 'urgent',
  status: 'active'
});

// Fetch conversations with embedded threads
const withThreads = await fetchConversations(321755, {
  embed: 'threads',
  status: 'active'
});

// Advanced search query
const searched = await fetchConversations(321755, {
  query: '(customerEmail:user@example.com)',
  status: 'all'
});
```

### Sending Replies

```javascript
const { sendReply } = require('./index.js');

// Send a customer-visible reply (will send email)
await sendReply(3227506031, {
  text: 'Hi there,\n\nThanks for your message!\n\nBest regards,',
  inboxId: 321755  // Required to auto-fetch customer ID
});

// Send a reply without emailing the customer (imported)
await sendReply(3227506031, {
  text: 'Draft reply - not sent to customer yet',
  customerId: 856475517,  // Or provide inboxId to auto-fetch
  imported: true
});

// Send a reply and close the conversation
await sendReply(3227506031, {
  text: 'All done! Let me know if you need anything else.',
  inboxId: 321755,
  status: 'closed'
});

// Create an internal note
const { createNote } = require('./index.js');
await createNote(3227506031, 'Internal note: Customer called, issue resolved.');
```

### sendReply Options

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | string | **Required.** The reply text (HTML supported) |
| `inboxId` | number | Inbox ID - required if `customerId` not provided (auto-fetches customer) |
| `customerId` | number | Customer ID - if not provided, will be auto-fetched using `inboxId` |
| `imported` | boolean | Mark as imported (won't email customer). Default: `false` |
| `status` | string | Conversation status after reply: `active`, `pending`, `closed`. Optional. |
| `userId` | number | User ID sending the reply. Optional (defaults to authenticated user). |

### createNote

| Parameter | Type | Description |
|-----------|------|-------------|
| `text` | string | **Required.** The note text (HTML supported) |

### Available Options (fetchConversations)

| Parameter | Type | Description |
|-----------|------|-------------|
| `status` | string | Filter by status: `active`, `pending`, `closed`, `spam`, or `all` (default: `active`) |
| `folderId` | number | Filter by folder ID |
| `assignedTo` | number | Filter by user ID |
| `customerId` | number | Filter by customer ID |
| `number` | number | Filter by conversation number |
| `modifiedSince` | string | ISO8601 date to filter conversations modified after this date |
| `sortField` | string | Sort field: `createdAt`, `mailboxId`, `modifiedAt`, `number`, `score`, `status`, `subject` (default: `createdAt`) |
| `sortOrder` | string | Sort order: `asc` or `desc` (default: `desc`) |
| `tag` | string | Filter by tag name |
| `query` | string | Advanced search query in `fieldId:value` format |
| `embed` | string | Comma-separated list of resources to embed: `threads` |
| `page` | number | Page number for pagination (default: 1) |



### Security Best Practices
- Never hardcode credentials into your codebase.
- Use OpenClaw's `config.apply` system for securely managing sensitive details.
- Avoid sharing sensitive parts of your configuration output (`API_KEY` and `APP_SECRET`) with others.

## Contribution Guidelines
- Ensure compliance with Helpscout's API usage policies.
- Add documentation for any new features added.

---
Source attribution: modbender
Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/helpscout/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 skill-library-mcp contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: modbender
Original project: https://github.com/modbender/skill-library-mcp/blob/d9c8fe903b5b4e82237dbe8d0df8567783022e18/data/helpscout/SKILL.md
Attribution basis: Source repository record

Fields of work: Sales, Customer Support
Roles: Community Manager, Customer Success Manager, Support Agent
Specialties: Specialty not specified
Tools: Help Scout
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 31cf6baec99fe88a419f6ff121cd8edd4c20b6de56fbd8f4721cb4fc218bca81