SocialOps 社交中控

SocialOps 是一个统一 inbox 服务，用于聚合社交消息、IM 渠道、开发协作事件和运维 webhook。当前 MVP 已支持入站聚合、统一 thread、消息存储、筛选查询、控制台查看、内部备注、出站回复队列和按消息计费。P2 新增 provider 能力目录和统一 webhook 出站适配器。

当前状态

后端和控制台 MVP 已可用。第一批 provider 白名单：

Provider	状态	说明
`generic-webhook`	已可用	通用 JSON 事件写入。
`telegram`	已可用	原生 Bot API 入站同步和定时回复投递。
`github`	已可用	issue、PR、workflow webhook 归一化写入；暂未启用出站适配器。
`discord`	Beta	支持 webhook 入站和出站；OAuth Bot/原生消息适配器独立建设。
`slack`	Beta	支持 webhook 入站和 incoming webhook 出站；Workspace OAuth 独立建设。
`teams`	Beta	支持 webhook 入站和 Teams 兼容 webhook 出站；Graph 适配器独立建设。
`whatsapp`	规划中	官方 Cloud API 适配器尚未启用。
`line`	规划中	LINE Messaging API 适配器尚未启用。
`instagram`	规划中	Instagram Graph 消息适配器尚未启用。

provider 能力目录可通过 GET /v1/apps/socialops/providers 和 GET /console/socialops/providers 查询。出站回复会保存为 SocialOps action；暂不支持的 provider 会被标记为 failed，并保留审计错误，而不是静默丢弃。

控制台

创建 socialops 服务实例后，打开：

text

Console > SocialOps

控制台已支持：

查看 SocialOps 服务实例。
按状态、优先级、provider 和关键词筛选 thread。
查看归一化后的消息，不暴露原始 provider payload。
绑定 Telegram Bot 连接到 SocialOps chat/channel 目标。
使用 custom-api-key Connected Account 绑定 Discord、Slack、Teams 或 generic webhook 渠道。
更新 thread 状态、优先级和负责人。
创建出站回复队列，等待 provider adapter 发送。
添加内部备注，保留处理过程。

控制台管理接口使用用户 JWT，并需要 service:read 或 service:manage 权限：

http

GET   /console/socialops/instances
GET   /console/socialops/providers
GET   /console/socialops/:alias/channels
POST  /console/socialops/:alias/channels
PATCH /console/socialops/:alias/channels/:channel_id
GET   /console/socialops/:alias/inbox
GET   /console/socialops/:alias/threads/:thread_id/messages
POST  /console/socialops/:alias/threads/:thread_id/notes
POST  /console/socialops/:alias/threads/:thread_id/replies
PATCH /console/socialops/:alias/threads/:thread_id

创建 Telegram channel 绑定：

json

{
  "provider": "telegram",
  "connected_account_id": "conn_xxx",
  "channel_name": "Support Telegram",
  "external_channel_id": "-1001234567890",
  "parse_mode": "HTML"
}

创建 Slack、Discord、Teams 或 generic webhook 渠道：

json

{
  "provider": "slack",
  "connected_account_id": "conn_custom_key",
  "channel_name": "Slack Support",
  "external_channel_id": "C123",
  "webhook_url": "https://hooks.slack.com/services/T/B/X"
}

Connected Account 必须是 active 的 custom-api-key。webhook URL 只接受 HTTPS，渠道列表接口不会明文返回它。平台 OAuth 和原生 Bot 适配器不包含在这个 webhook 适配器内。

connected_account_id 必须是同一用户下 active 状态的 telegram-bot Connected Account。Channel 可通过 PATCH 启停：

json

{
  "status": "inactive"
}

创建内部备注：

json

{
  "text": "已检查 provider 控制台，并指派给 ops。"
}

备注会以 internal SocialOps 消息保存，不会发送到外部平台。

创建出站回复：

json

{
  "text": "我们正在检查这个问题。"
}

回复会以 outbound SocialOps 消息保存，并创建一条 send_reply action，状态为 pending。定时 delivery worker 会消费 pending action，发送已支持的平台，并把 action 标记为 completed 或 failed。

Knoveria 提示：当前 Knoveria staging 包只交付网页 Widget 联调 Key，并未交付 Telegram Bot Token 或 Telegram channel。因此此处的 Telegram 是平台能力说明，不代表 Knoveria 租户已经开通真实 Telegram 收发。

Endpoint

http

GET  /v1/apps/socialops/providers
POST /v1/apps/socialops/:alias/webhook/:provider
GET  /v1/apps/socialops/:alias/inbox
GET  /v1/apps/socialops/:alias/threads
GET  /v1/apps/socialops/:alias/threads/:thread_id/messages
POST /v1/apps/socialops/:alias/threads/:thread_id/replies

所需 scope：

text

socialops:write
socialops:read

写入事件

bash

curl -X POST https://api.open4x.com/v1/apps/socialops/support/webhook/generic-webhook \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "evt_1001",
    "thread_id": "incident_42",
    "title": "Incident opened",
    "text": "API latency is high",
    "user": {
      "id": "monitor"
    },
    "labels": ["ops", "urgent"]
  }'

响应：

json

{
  "status": "accepted",
  "provider": "generic-webhook",
  "thread_id": "soth_...",
  "message_id": "somsg_..."
}

查询 Inbox

bash

curl "https://api.open4x.com/v1/apps/socialops/support/inbox?status=open&priority=high&limit=50" \
  -H "X-API-Key: sk_xxx"

支持的筛选：

Query	取值
`status`	`open`、`pending`、`resolved`、`archived`
`priority`	`low`、`normal`、`high`、`urgent`
`provider`	`generic-webhook`、`telegram`、`github`、`discord`、`slack`、`teams`、`whatsapp`、`line`、`instagram`
`q`	搜索 thread subject 和 AI summary。
`page`、`limit`	标准分页，limit 最大 100。

创建回复队列

bash

curl -X POST https://api.open4x.com/v1/apps/socialops/support/threads/soth_xxx/replies \
  -H "X-API-Key: sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "我们正在检查这个问题。"
  }'

响应：

json

{
  "success": true,
  "data": {
    "message": {
      "direction": "outbound",
      "message_type": "text",
      "text": "我们正在检查这个问题。"
    },
    "action": {
      "action_type": "send_reply",
      "status": "pending"
    }
  }
}

回复投递

定时 worker 会扫描 send_reply action，支持 Telegram，以及 Discord、Slack、Teams 和 generic webhook 的统一 webhook 出站适配：

action 会先被 claim 为 processing。
worker 加载 thread、outbound message 和 active SocialOps channel。
channel 必须引用 active 的 provider connection；Telegram 使用 telegram-bot，webhook 渠道使用 custom-api-key。
worker 先扣除 SocialOps 回复投递费用。
调用 Telegram sendMessage 或 provider webhook，目标来自 thread/channel。
成功后 action 变为 completed，如果 provider 返回消息 ID，则保存到 outbound message。
如果 provider 发送失败，会退款，并把 action 标记为 failed。

如果缺少 channel、connected account、余额或 provider adapter，action 会被标记为 failed 并写入审计错误。

数据安全

Inbox 响应默认不会暴露外部平台 thread id。消息响应默认也不会返回原始 provider payload。raw payload 会保留用于审计和后续平台适配，但不应该直接展示在普通客户界面里。

计费

SocialOps 入站消息按已接受的 webhook event 计费。MVP 默认价格为每条入站消息 0.0002 USD。Telegram 或 webhook provider 回复会在定时 worker 真实发送时扣费；provider 发送失败会退款。

SocialOps 社交中控 ​

当前状态 ​

控制台 ​

Endpoint ​

写入事件 ​

查询 Inbox ​

创建回复队列 ​

回复投递 ​

数据安全 ​

计费 ​

SocialOps 社交中控

当前状态

控制台

Endpoint

写入事件

查询 Inbox

创建回复队列

回复投递

数据安全

计费