---
name: channels
description: "社交渠道管理。接入/管理 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo 等社交渠道，绑定用户账号，发送通知。使用场景：接入渠道(connect channel)、绑定(bind)、社交(social)、Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo、通知(notify)、推送(push)、消息(message)。"
---

# Optima Channels - 社交渠道管理

管理社交渠道接入、用户绑定和消息推送。支持 Telegram、WhatsApp、Discord、Slack、飞书、LINE、Zalo。

## 社交渠道环境注意事项

当消息来自社交渠道（metadata.source === "channel_bridge"）时：

1. **无浏览器环境** — 用户在 Telegram/WhatsApp 等社交 App 中，无法自动打开浏览器。所有需要浏览器的操作（如 OAuth 登录），必须把 URL 发给用户让他们手动打开。

2. **登录流程** — 当用户需要登录（如操作商品、订单等需要认证的功能）：
   - 运行 `commerce auth login`
   - 命令会输出一个授权 URL 和验证码
   - **把 URL 和验证码发给用户**，告诉他们在手机浏览器中打开
   - 命令会自动等待用户完成授权
   - 不要说"浏览器已自动打开"——社交渠道里没有浏览器

3. **回复简洁** — 社交渠道消息应比 Web Chat 更简洁。避免长段落，用要点列表。

## 典型场景

当用户说：
- "登录" → 运行 `commerce auth login`，把输出中的 URL 和验证码发给用户
- "帮我接入 Telegram" → 引导创建 bot → `channels accounts add telegram --account-id store --token <token>`
- "查看我的渠道" → `channels accounts list`
- "关掉 Telegram" → `channels accounts disable telegram store`
- "重新开启 Telegram" → `channels accounts enable telegram store`
- "删除 Telegram 渠道" → `channels accounts remove telegram store`
- "查看我的绑定" → `channels bind list`
- "解绑 Telegram" → `channels bind remove --platform telegram --account-id store --platform-uid 123456`
- "给用户发通知" → `channels send --user-id <id> --text "消息内容"`
- "广播消息" → `channels broadcast --text "消息" --user-ids id1,id2`
- "查看渠道状态" → `channels status`

### 场景决策表

| 用户需求 | 推荐命令 | 关键注意点 |
|---------|---------|-----------|
| 接入新渠道 | `channels accounts add <platform>` | 不同平台需要不同参数，见下方 |
| 查看渠道列表 | `channels accounts list` | 显示所有账号及状态 |
| 启用/禁用渠道 | `channels accounts enable/disable` | 不删除配置，只是暂停 |
| 删除渠道 | `channels accounts remove` | 永久删除，需重新配置 |
| 查看绑定 | `channels bind list` | 显示当前用户绑定的社交账号 |
| 解绑 | `channels bind remove` | 需要指定 platform、account-id、platform-uid |
| 发送通知 | `channels send` | 发到用户所有已绑定渠道 |
| 广播 | `channels broadcast` | 发给多个用户 |

## 场景1：接入 Telegram

**流程**: 创建 Bot → 获取 Token → 添加到 Optima

```bash
# 1. 引导用户：
# "请在 Telegram 找 @BotFather，发送 /newbot，按提示创建 bot，然后把 token 发给我"

# 2. 用户提供 token 后，添加渠道
channels accounts add telegram --account-id store --token "123456:AAHxxxxxxxxxx"

# 3. 验证
channels status
```

## 场景2：接入 Discord

```bash
# 1. 引导用户：
# "请在 Discord Developer Portal (discord.com/developers) 创建 Application → Bot，
#  开启 MESSAGE CONTENT Intent，复制 Bot Token"

# 2. 添加渠道
channels accounts add discord --account-id store --token "MTA3xxx..."

# 3. 验证
channels status
```

## 场景3：接入 Slack

```bash
# 1. 引导用户：
# "请在 api.slack.com 创建 App，启用 Socket Mode，获取 Bot Token 和 App Token"

# 2. 添加渠道
channels accounts add slack --account-id store \
  --bot-token "xoxb-..." \
  --app-token "xapp-..." \
  --signing-secret "..."

# 3. 验证
channels status
```

## 场景4：接入飞书

```bash
# 1. 引导用户：
# "请在飞书开发者后台创建应用，获取 App ID 和 App Secret"

# 2. 添加渠道
channels accounts add feishu --account-id store \
  --app-id "cli_xxx" \
  --app-secret "xxx"

# 3. 验证
channels status
```

## 场景5：接入 LINE

```bash
# 1. 引导用户：
# "请在 LINE Developers Console 创建 Messaging API channel，获取 Channel Access Token 和 Channel Secret"

# 2. 添加渠道
channels accounts add line --account-id store \
  --channel-access-token "xxx" \
  --channel-secret "xxx"

# 3. 配置 Webhook URL（需在 LINE Developer Console 手动设置）：
# https://channels-api.optima.onl/webhook/line/store

# 4. 验证
channels status
```

## 场景6：社交账号自动绑定

**无需 CLI 操作**。商家只需给 bot 发送任意消息，bot 会：

1. 自动回复一条授权链接（形如 `https://auth.optima.onl/api/v1/oauth/device?user_code=XXX-YYY`）
2. 商家点开链接在手机浏览器登录并授权
3. bot 发送 "✅ 授权成功" 消息，之后商家可以直接问任何业务问题

链接 10 分钟内有效。超过 14 天未活跃，bot 会要求重新授权。

**开发者运维**：如需强制解绑某条绑定，用 `channels bind remove`（现有命令不变）。

## 场景7：发送通知

```bash
# 发送给单个用户（发到所有已绑定渠道）
channels send --user-id "uuid-xxx" --text "您的订单 #1234 已发货"

# 指定渠道发送
channels send --user-id "uuid-xxx" --text "消息" --platform telegram

# 广播给多个用户
channels broadcast --text "新品上架！限时8折" --user-ids "uuid-1,uuid-2,uuid-3"
```

## 各平台必需参数

| 平台 | 必需参数 | 获取方式 |
|------|---------|---------|
| Telegram | `--token` | @BotFather 创建 bot |
| Discord | `--token` | Developer Portal → Bot |
| Slack | `--bot-token` `--app-token` `--signing-secret` | api.slack.com → App |
| LINE | `--channel-access-token` `--channel-secret` | LINE Developers Console |
| 飞书 | `--app-id` `--app-secret` | 飞书开发者后台 |
| WhatsApp | `--session-dir`（可选） | baileys QR 扫码认证 |
| Zalo | `--token` | Zalo Developer Console |

## 命令参考

```bash
# 状态
channels status

# 账号管理
channels accounts list
channels accounts add <platform> --account-id <id> [平台参数]
channels accounts remove <platform> <accountId>
channels accounts enable <platform> <accountId>
channels accounts disable <platform> <accountId>

# 绑定管理
channels bind list [--user-id <id>]
channels bind remove --platform <p> --account-id <a> --platform-uid <uid>

# 消息
channels send --user-id <id> --text "消息"
channels broadcast --text "消息" --user-ids "id1,id2"
```
