名称： helpscout
描述： 获取并回复 Helpscout 对话
元数据：
{
"openclaw":
{
"requires": { "env": ["API_KEY", "APP_SECRET", "INBOX_IDS"] },
},
}

Helpscout 技能

描述

本技能用于与 Helpscout 交互，从指定收件箱获取对话并发送回复。它旨在直接从 OpenClaw 简化客户支持操作。

功能

• 从多个 Helpscout 收件箱获取对话
• 向对话发送回复（客户可见或内部备注）
• 按状态、文件夹、负责人、客户、标签等条件筛选
• 按多种字段对对话排序
• 在响应中直接嵌入对话线程数据
• 使用 API 密钥和应用密钥安全认证
• 优雅处理无效凭证或网络问题等潜在错误

设置说明

使用本技能前，需配置 Helpscout 凭证并指定要获取对话的收件箱 ID。

1. 获取 Helpscout API 密钥和应用密钥

1. 登录您的 Helpscout 账户。
2. 进入 管理 > 应用。
3. 创建或打开您的应用以获取以下信息：
   - API 密钥
   - 应用密钥

2. 收集收件箱 ID

1. 使用 Helpscout 的 API 文档 获取您要从中获取对话的收件箱 ID。

3. 在 OpenClaw 中保存凭证

使用以下命令保存您的 Helpscout 凭证：

cat ~/.openclaw/openclaw.json | jq '.skills.entries.helpscout = {
  enabled: true,
  env: {
    API_KEY: "您的API密钥",
    APP_SECRET: "您的应用密钥",
    INBOX_IDS: ["收件箱ID-1", "收件箱ID-2"]
  }
}' | openclaw gateway config.apply

4. 验证配置

为确保凭证设置正确，请检查您的配置：

openclaw gateway config.get

请确认 helpscout 对象显示正确（避免分享 API_KEY 或 APP_SECRET）。

使用方法

基础用法

从配置的收件箱获取所有活跃对话：

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

// 获取所有活跃对话（默认）
const results = await fetchAllInboxes();

高级筛选

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

// 从特定收件箱获取已关闭的对话
const conversations = await fetchConversations(321755, {
  status: 'closed',
  sortField: 'modifiedAt',
  sortOrder: 'desc',
  page: 1
});

// 获取分配给特定用户的对话
const assigned = await fetchConversations(321755, {
  assignedTo: 782728,
  status: 'active'
});

// 获取带有特定标签的对话
const tagged = await fetchConversations(321755, {
  tag: 'urgent',
  status: 'active'
});

// 获取嵌入对话线程的对话
const withThreads = await fetchConversations(321755, {
  embed: 'threads',
  status: 'active'
});

// 高级搜索查询
const searched = await fetchConversations(321755, {
  query: '(customerEmail:user@example.com)',
  status: 'all'
});

发送回复

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

// 发送客户可见的回复（将发送邮件）
await sendReply(3227506031, {
  text: '您好，\n\n感谢您的留言！\n\n此致，',
  inboxId: 321755  // 必需，用于自动获取客户 ID
});

// 发送不向客户发送邮件的回复（导入）
await sendReply(3227506031, {
  text: '草稿回复 - 尚未发送给客户',
  customerId: 856475517,  // 或提供 inboxId 以自动获取
  imported: true
});

// 发送回复并关闭对话
await sendReply(3227506031, {
  text: '全部完成！如有需要，请随时告知。',
  inboxId: 321755,
  status: 'closed'
});

// 创建内部备注
const { createNote } = require('./index.js');
await createNote(3227506031, '内部备注：客户来电，问题已解决。');

sendReply 参数

createNote

可用选项 (fetchConversations)

安全最佳实践

• 切勿将凭证硬编码到代码库中。
• 使用 OpenClaw 的 config.apply 系统安全地管理敏感信息。
• 避免与他人分享配置输出中的敏感部分（API_KEY 和 APP_SECRET）。

贡献指南

• 确保遵守 Helpscout 的 API 使用政策。
• 为任何新增功能添加文档。