SocialOps 社交中控

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

当前状态

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

Provider	状态	说明
generic-webhook	已可用	通用 JSON 事件写入。
telegram	已支持归一化写入和定时回复投递	需要 telegram-bot Connected Account 和 active SocialOps channel 绑定。
github	已支持归一化写入	适合 issue、PR、workflow 事件。

Slack、Discord、Teams、X/Twitter、Meta、Instagram、WhatsApp 和 LINE 会通过 Connected Accounts 模块和对应平台 webhook 逐步接入。出站回复会保存为 SocialOps action；暂不支持的 provider 会被标记为 failed，并保留审计错误，而不是静默丢弃。

控制台

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

Console > SocialOps

控制台已支持：

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

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

GET   /console/socialops/instances
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 绑定：

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

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

{
  "status": "inactive"
}

创建内部备注：

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

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

创建出站回复：

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

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

Endpoint

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：

socialops:write
socialops:read

写入事件

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"]
  }'

响应：

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

查询 Inbox

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
q	搜索 thread subject 和 AI summary。
page、limit	标准分页，limit 最大 100。

创建回复队列

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": "我们正在检查这个问题。"
  }'

响应：

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

回复投递

定时 worker 会扫描 send_reply action，目前支持 Telegram 投递：

1. action 会先被 claim 为 processing。
2. worker 加载 thread、outbound message 和 active SocialOps channel。
3. channel 必须引用 active 的 telegram-bot Connected Account。
4. worker 先扣除 SocialOps 回复投递费用。
5. 调用 Telegram sendMessage，chat id 来自 thread/channel。
6. 成功后 action 变为 completed，outbound message 保存 Telegram message_id。
7. 如果 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 回复投递会在定时 worker 真实发送时扣费；provider 发送失败会退款。