跳转到主要内容

​
概述

Channels API 允许您将 Shannon 与外部消息平台集成。创建 Channel 以连接 Slack 工作区或 LINE 账户，Shannon 将通过其 Agent 系统自动处理传入的消息。

​
功能特性

  • Slack 集成，支持事件订阅和 Bot 消息
  • LINE 集成，基于 Webhook 的消息处理
  • HMAC 签名验证，确保入站 Webhook 安全
  • Agent 路由，通过 agent_name 配置将消息定向到指定 Agent
  • 用户隔离，每个用户的 type + name 组合唯一
  • 凭据安全 — 凭据永远不会在 API 响应中暴露

​
创建 Channel

创建新的消息 Channel。 
curl -X POST http://localhost:8080/api/v1/channels \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "type": "slack",
    "name": "My Slack Channel",
    "credentials": {
      "signing_secret": "your-slack-signing-secret",
      "bot_token": "xoxb-your-bot-token",
      "app_id": "A0123456789"
    },
    "config": {
      "agent_name": "research-agent"
    }
  }'

​
请求体

字段类型必填描述
typestring是Channel 类型："slack" 或 "line"
namestring是Channel 显示名称
credentialsobject是平台相关凭据（参见下方）
configobject否可选配置（如 agent_name）

​
响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "slack",
  "name": "My Slack Channel",
  "config": {
    "agent_name": "research-agent"
  },
  "enabled": true,
  "created_at": "2026-03-10T10:00:00Z",
  "updated_at": "2026-03-10T10:00:00Z"
}
出于安全考虑，credentials 字段永远不会在 API 响应中返回。请在您自己的系统中安全存储凭据。

​
列出 Channel

列出当前认证用户的所有 Channel。 
curl http://localhost:8080/api/v1/channels \
  -H "Authorization: Bearer <token>"

​
响应

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "type": "slack",
    "name": "My Slack Channel",
    "config": {
      "agent_name": "research-agent"
    },
    "enabled": true,
    "created_at": "2026-03-10T10:00:00Z",
    "updated_at": "2026-03-10T10:00:00Z"
  }
]

​
获取 Channel

获取指定 Channel 的详细信息。 
curl http://localhost:8080/api/v1/channels/{id} \
  -H "Authorization: Bearer <token>"

​
响应

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "slack",
  "name": "My Slack Channel",
  "config": {
    "agent_name": "research-agent"
  },
  "enabled": true,
  "created_at": "2026-03-10T10:00:00Z",
  "updated_at": "2026-03-10T10:00:00Z"
}

​
更新 Channel

更新现有 Channel。所有字段均为可选 — 仅更新提供的字段。 
curl -X PUT http://localhost:8080/api/v1/channels/{id} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Renamed Slack Channel",
    "config": {
      "agent_name": "financial-agent"
    },
    "enabled": false
  }'

​
请求体

字段类型必填描述
namestring否新的 Channel 名称
credentialsobject否新的平台凭据
configobject否新的配置
enabledboolean否启用或禁用 Channel

​
响应

返回更新后的 Channel 对象（与获取 Channel 的响应格式相同）。

​
删除 Channel

永久删除一个 Channel。 
curl -X DELETE http://localhost:8080/api/v1/channels/{id} \
  -H "Authorization: Bearer <token>"

​
响应

Response
{
  "message": "Channel deleted"
}
(HTTP 200 OK with JSON body)

​
入站 Webhook

接收来自外部平台的消息。当用户在 Slack 或 LINE 中发送消息时，平台会调用此端点。 
POST /api/v1/channels/{channel_id}/webhook
此端点不需要认证。每个平台使用自己的 HMAC 签名验证来确保请求的真实性。

​
响应

{
  "status": "dispatched"
}
Webhook 会验证入站请求、提取消息内容，并异步将其分发到 Shannon 的 Agent 系统。响应会立即返回。

​
凭据格式

​
Slack 凭据

{
  "signing_secret": "your-slack-signing-secret",
  "bot_token": "xoxb-your-bot-token",
  "app_id": "A0123456789"
}
字段描述
signing_secret在 Slack 应用的 Basic Information 页面中获取
bot_tokenBot User OAuth Token（以 xoxb- 开头）
app_id您的 Slack 应用 ID

​
LINE 凭据

{
  "channel_secret": "your-line-channel-secret",
  "channel_access_token": "your-line-channel-access-token"
}
字段描述
channel_secret在 LINE Developer Console 的 Channel 设置中获取
channel_access_token从 LINE Developer Console 获取的长期有效 Channel Access Token

​
Webhook 行为

​
Slack

  • 签名验证：使用 Channel 的 signing_secret 通过 HMAC-SHA256 验证 X-Slack-Request-Timestamp 和 X-Slack-Signature 请求头
  • 时钟偏差：超过 5 分钟的请求将被拒绝
  • URL 验证：在应用设置期间自动响应 Slack 的 url_verification challenge
  • Bot 过滤：忽略来自 Bot 的消息以防止循环
  • 支持的事件：message 和 app_mention

​
LINE

  • 签名验证：使用 Channel 的 channel_secret 通过 HMAC-SHA256（base64 编码）验证 X-Line-Signature 请求头
  • 回复行为：使用 Reply Token 立即发送 “Thinking…” 回复
  • 消息处理：处理事件载荷中的第一条文本消息

​
Agent 路由

在 Channel 的 config 中设置 agent_name 字段，将传入消息路由到指定的 Agent： 
{
  "config": {
    "agent_name": "research-agent"
  }
}
如果未设置 agent_name，消息将由 Shannon 的默认 Agent 路由处理。

​
Channel 响应对象

字段类型描述
idstring (UUID)Channel 唯一标识符
user_idstring (UUID)所属用户 ID（可选）
typestringChannel 类型："slack" 或 "line"
namestringChannel 显示名称
configobjectChannel 配置
enabledbooleanChannel 是否处于启用状态
created_atstring (ISO 8601)创建时间戳
updated_atstring (ISO 8601)最后更新时间戳

​
错误响应

状态码错误描述
400Invalid request缺少必填字段或无效的 Channel 类型
401Unauthorized缺少或无效的认证信息
403Forbidden无法访问其他用户的 Channel
404Channel not found无效的 Channel ID
409ConflictChannel 重复（相同用户 + 类型 + 名称）
500Internal server error服务器内部错误
所有错误遵循标准格式： 
{
  "error": "error message here"
}

​
后续步骤

提交任务

通过 API 直接提交任务

智能体

配置 Agent 用于 Channel 路由