Helpscout

Fetches messages from specific Helpscout inboxes

Security Scan

The skill's declared purpose and required credentials match Helpscout usage, but there are multiple implementation/instruction inconsistencies (broken exports and parameter mismatches) and an unclear provenance that warrant caution before installing and supplying credentials.

Purpose & Capability

Name/description, required env vars (API_KEY, APP_SECRET, INBOX_IDS), and network calls target the Helpscout API — these are proportionate to a Helpscout fetch/reply skill. The package declares standard HTTP libraries (node-fetch/undici) which are expected for API interaction.

Instruction Scope

SKILL.md and usage examples present APIs that do not match the implementation: examples call fetchConversations(inboxId, options) and sendReply(...) but scripts/fetchConversations.js defines fetchConversations with a single destructured object parameter and scripts/sendReply.js implements sendReply but does not export it. index.js attempts to import sendReply from the module (it will be undefined). The SKILL.md also instructs storing secrets in ~/.openclaw/openclaw.json via openclaw gateway config.apply — this is expected for this platform but means secrets will be written to disk (normal for skills, but verify you trust the skill). Overall the runtime instructions are inconsistent with the shipped code and could cause failures or unexpected behavior.

Install Mechanism

This is instruction-only (no install spec) which reduces installation risk. The package includes package.json and package-lock.json showing npm dependencies (node-fetch, undici) — standard for HTTP clients. No remote download URLs or extract steps were observed. Because code files are bundled, an install step would pull standard npm packages (traceable).

Credentials

Requested environment variables (API_KEY, APP_SECRET, INBOX_IDS) are appropriate and necessary for Helpscout API access. No unrelated credentials or config paths are requested. Note: the skill directs users to store those secrets via openclaw gateway config.apply which persists them to the OpenClaw config file; ensure you are comfortable storing credentials there.

Persistence & Privilege

always is false and the skill does not request elevated or cross-skill configuration modifications. It does instruct writing its own credentials into the OpenClaw config (expected behavior). Autonomous invocation is allowed by default (disable-model-invocation is false), which is normal — combine that with other red flags if you are concerned.

What to consider before installing

This skill appears to be a genuine Helpscout integration and asks only for Helpscout credentials (API key, App Secret) and inbox IDs, which is expected. However: (1) the SKILL.md usage examples and the shipped code are inconsistent — functions are called with the wrong argument styles, and the sendReply implementation exists but is not exported (index.js imports sendReply and will receive undefined). These look like implementation bugs, not necessarily malicious, but they mean the skill may fail or behave unexpectedly. (2) Credentials are stored via openclaw gateway config.apply (writes into your OpenClaw config file) — only proceed if you trust this skill and its owner. Recommended steps before enabling with real credentials: - Inspect and/or run the package locally in a sandbox: run npm install and npm test (tests use nock/mock); verify getToken and fetch functions work against the Helpscout API. - Fix or request fixes for the parameter mismatch and the missing export (either update fetchConversations signature or usage, and export sendReply if replying should be permitted). - Provide least-privilege credentials (create a Helpscout API key with minimal scopes) and rotate them after testing. - If you do not trust the anonymous publisher or cannot validate the code, do not add real API_KEY/APP_SECRET to your configuration.

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.

3. Save Credentials in OpenClaw

Use the following command to save your Helpscout credentials:

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:

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:

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

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

Advanced Filtering

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:[e-mail])',
  status: 'all'
});

Sending Replies

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.