# Convoy AI 客服 · 开放接口对接文档

> **面向**：在 Shopee / 淘宝 / 拼多多 / 抖店 / 闲鱼 / 独立站 / WhatsApp / Telegram 等平台销售 Convoy 手电的**卖家、代理商及技术对接方**。
>
> **一句话**：把你店铺收到的买家消息，通过一个 HTTP 接口发给 Convoy AI；AI 基于 **Convoy 官方产品知识库**自动回答参数、适配、电池、故障等问题，你把回复发回买家即可。产品资料由官方维护，你无需整理。

- **接口基址**：`https://api.zeefox.cn`
- **数据格式**：HTTP + JSON（UTF-8）
- **问答接口**：`POST /api/chat`
- **卖家控制台**：`https://api.zeefox.cn/console`

---

## 1. 它能回答什么

接入方为零售电商卖家。接口作为你店铺的 AI 客服，**零售模式（默认）行为如下**：

| 能力 | 买家问题示例 | 零售模式下的回答 |
|---|---|---|
| 参数 / 规格 | “L8 多少流明？”“S2+ 用什么电池？”“防水吗？” | ✓ 正常回答官方规格（流明/射程/电池/防水/尺寸等） |
| 配件 / 适配 | “有 22mm buck 驱动吗？”“这透镜适配 H1 吗？” | ✓ 正常回答配件与官方适配关系 |
| 对比 / 推荐 | “M21H 和 S21E 哪个好？” | ✓ 正常做产品知识对比 |
| 故障诊断 | 买家发来光斑 / 手电照片 | ✓ 识别常见故障并给处理建议（标注 AI 仅供参考） |
| **价格** | “多少钱？”“有优惠吗？” | ✗ **不报价**——引导“价格以本店铺商品页为准 / 联系客服”（各店自己定价） |
| **库存 / 运费** | “有货吗？”“几天到？” | ✗ **不承诺**——引导以店铺商品页 / 客服为准 |
| **退货 / 退款 / 保修** | “能退吗？”“保修多久？” | ✓ **严格使用你自己配置的售后政策**回答；未配置则引导联系店铺客服 |

> 多语言自动跟随买家（中/英/俄/日/韩/泰/德/法/西/葡/意/马来）。型号、规格数字、链接保持原文。

---

## 2. 接入总览

```
买家在你的店铺提问
        │
        ▼
你的服务器 / 中间件  ──① 收到平台消息
        │  ② POST /api/register  凭邀请码注册，拿到 api_key（一次性）
        │  ③ 在控制台填写店铺信息与售后政策（一次性）
        │  ④ 每条买家消息  POST /api/chat （请求头 X-Api-Key）
        ▼
   Convoy AI 接口  ── 产品知识答疑（价格/库存/售后按你的策略处理）
        │  ⑤ 返回 { reply, intent, mode, ... }
        ▼
你的服务器  ── 调用平台“发消息”API，把 reply 发回买家
```

你只需写“收消息”和“发消息”两段胶水代码，产品知识与 AI 推理由接口负责。

---

## 3. 注册（凭邀请码）

注册需 **Convoy 运营提供的邀请码**（防止恶意注册）。注册成功返回两个凭证：

| 凭证 | 形如 | 用途 |
|---|---|---|
| `api_key` | `ck_xxxx` | 你的服务器调用 `/api/chat` 问答（放在 `X-Api-Key` 头） |
| `console_token` | `cs_xxxx` | 登录卖家控制台、读写店铺配置（放在 `X-Console-Token` 头） |

```bash
curl -X POST https://api.zeefox.cn/api/register \
  -H "Content-Type: application/json" \
  -d '{
    "invite": "INVITE-XXXXXX",
    "name": "你的店铺名",
    "channel": "shopee",
    "contact": "你的联系方式"
  }'
```

响应：

```json
{
  "ok": true,
  "account_id": "acct_xxxx",
  "api_key": "ck_xxxxxxxxxxxx",
  "console_token": "cs_xxxxxxxxxxxx",
  "mode": "retail"
}
```

> 无邀请码 / 邀请码无效 / 超过使用次数会返回 **403**。凭证只返回一次，请妥善保存在服务器端，**不要写进网页或 App 前端**。也可以直接在网页控制台 `https://api.zeefox.cn/console` 注册登录。

---

## 4. 问答接口

### `POST /api/chat`

**请求头**

```
Content-Type: application/json
X-Api-Key: ck_你的api_key
```

**请求体（JSON）**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channel` | string | 是 | 渠道标识，见第 7 节，如 `shopee` / `taobao` / `generic` |
| `session_id` | string | 是 | 买家/会话唯一 id。**同一买家保持一致**，AI 才有多轮上下文 |
| `text` | string | 二选一 | 买家文字消息 |
| `image_url` | string | 二选一 | 买家图片的**公网可访问 URL**（光斑/手电照片，用于故障诊断）；可与 text 同传 |

**响应 200（JSON）**

| 字段 | 说明 |
|---|---|
| `reply` | **发给买家的回复文本**（Markdown，语言已跟随买家；IM 不渲染 Markdown 时可自行转纯文本） |
| `intent` | 命中意图：`specs` / `parts_lookup` / `compatibility` / `battery_usage` / `comparison` / `after_sales` / `diagnosis_*` / `pricing` 等，便于统计 |
| `tier` | 零售接入恒为 `customer` |
| `mode` | 零售接入恒为 `retail` |
| `model_used` | 实际使用的模型 |

**请求示例**

```bash
curl -X POST https://api.zeefox.cn/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ck_xxxx" \
  -d '{
    "channel": "shopee",
    "session_id": "buyer_10086",
    "text": "What battery does the Convoy S2+ use?"
  }'
```

**响应示例**

```json
{
  "reply": "Convoy S2+ 使用 18650 规格电池……",
  "intent": "battery_usage",
  "tier": "customer",
  "mode": "retail",
  "model_used": "auto"
}
```

**图片诊断**

```json
{
  "channel": "whatsapp",
  "session_id": "wa_8888",
  "text": "光斑中心有个蓝点，正常吗？",
  "image_url": "https://你的cdn/beam.jpg"
}
```

> 图片必须是接口服务器能下载到的公网 URL（平台图片先转存到你自己的 OSS/CDN）。

---

## 5. 各语言调用示例

**Python**

```python
import requests

def ask_convoy(buyer_id, text, channel="generic", image_url=None):
    payload = {"channel": channel, "session_id": str(buyer_id), "text": text}
    if image_url:
        payload["image_url"] = image_url
    r = requests.post(
        "https://api.zeefox.cn/api/chat",
        headers={"X-Api-Key": "ck_xxxx", "Content-Type": "application/json"},
        json=payload, timeout=90,
    )
    r.raise_for_status()
    return r.json()["reply"]

print(ask_convoy("buyer_1", "S2+ 用什么电池？", channel="taobao"))
```

**Node.js**

```javascript
async function askConvoy(buyerId, text, channel = "generic", imageUrl = null) {
  const body = { channel, session_id: String(buyerId), text };
  if (imageUrl) body.image_url = imageUrl;
  const r = await fetch("https://api.zeefox.cn/api/chat", {
    method: "POST",
    headers: { "X-Api-Key": "ck_xxxx", "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });
  if (!r.ok) throw new Error("Convoy AI error " + r.status);
  return (await r.json()).reply;
}
```

**PHP**

```php
function ask_convoy($buyerId, $text, $channel="generic", $imageUrl=null) {
  $body = ["channel"=>$channel, "session_id"=>$buyerId, "text"=>$text];
  if ($imageUrl) $body["image_url"] = $imageUrl;
  $ch = curl_init("https://api.zeefox.cn/api/chat");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ["Content-Type: application/json", "X-Api-Key: ck_xxxx"],
    CURLOPT_POSTFIELDS => json_encode($body),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 90,
  ]);
  $resp = curl_exec($ch); curl_close($ch);
  return json_decode($resp, true)["reply"] ?? "";
}
```

---

## 6. 店铺信息与售后政策配置

退货/退款/换货/保修等问题，AI **严格按你填写的政策**回答。推荐网页配置：登录 `https://api.zeefox.cn/console`，在“店铺信息 / 售后政策”页填写。

也可用 `console_token` 通过 API 配置（`POST /api/console/save`）：

```bash
curl -X POST https://api.zeefox.cn/api/console/save \
  -H "Content-Type: application/json" \
  -H "X-Console-Token: cs_xxxx" \
  -d '{
    "shop_name": "你的店铺名",
    "platform": "shopee",
    "shop_url": "https://你的店铺链接",
    "contact": "客服微信/邮箱",
    "shipping_note": "下单后48小时内发货……",
    "return_policy": "支持7天无理由退货，商品需不影响二次销售",
    "refund_policy": "签收后7天内、商品完好可申请退款",
    "exchange_policy": "质量问题15天内换新",
    "warranty_policy": "本店提供1年店铺保修",
    "human_handoff": "工作时间 9:00-21:00 可转人工（微信 xxx）"
  }'
```

可配置字段：

| 字段 | 含义 |
|---|---|
| `shop_name` | 店铺名称 |
| `platform` / `shop_url` / `contact` | 平台 / 店铺链接 / 联系方式 |
| `timezone` / `language` | 服务时区 / 默认语言 |
| `shipping_note` | 发货、运费说明（买家问物流时使用） |
| `return_policy` | 退货政策 |
| `refund_policy` | 退款政策 |
| `exchange_policy` | 换货政策 |
| `warranty_policy` | 保修政策 |
| `human_handoff` | 转人工客服说明 |
| `extra_note` | 其他想让 AI 遵守的备注 |

> **未填写的售后项，AI 不会编造，会引导买家联系你的人工客服。**

---

## 7. 渠道 `channel` 取值

| 值 | 平台 | | 值 | 平台 |
|---|---|---|---|---|
| `shopee` | 虾皮 Shopee | | `xianyu` | 闲鱼 |
| `taobao` | 淘宝 / 天猫 | | `wordpress` / `woocommerce` | 独立站 |
| `pdd` | 拼多多 | | `whatsapp` | WhatsApp |
| `douyin` | 抖店 | | `telegram` | Telegram |
| | | | `generic` | 任意/自定义 |

> `channel` 主要用于统计与话术适配，不影响知识库内容；不确定时用 `generic`。

---

## 8. 各平台如何对接

通用两步：**① 把平台消息桥接到 `/api/chat`；② 把 `reply` 通过平台发消息接口发回。**

| 平台 | 收消息（平台→你） | 发消息（你→买家） | 前置条件 |
|---|---|---|---|
| **Shopee** | Shopee Open Platform，卖家授权后通过 Chat API 收消息 | Chat API push | 卖家账号 + App |
| **淘宝/天猫** | 千牛 / 淘宝开放平台 IM 消息订阅 | 千牛发消息 API | 店铺 + 开放平台 App |
| **拼多多** | 多多客服开放能力，或客服 SaaS（聚水潭/智齿等）webhook | 对应发消息接口 | 店铺 |
| **抖店** | 飞鸽客服开放平台消息回调 | 飞鸽发消息 API | 抖店资质 + App |
| **闲鱼** | 官方开放能力有限，常走客服 SaaS / RPA | 同上 | 视开放情况 |
| **WooCommerce/独立站** | 自有聊天插件（Tidio/Crisp/自研）webhook | 插件回复 API | 自有站点，最自由 |
| **WhatsApp** | Meta Business Cloud API webhook | Graph API 回发 | Meta 商务号；24h 会话窗内自由发 |
| **Telegram** | Bot API `getUpdates` 或 webhook | Bot API `sendMessage` | @BotFather 建 bot，零审核 |

**桥接伪代码（任意平台通用）**

```python
def on_platform_message(buyer_id, text, image_url=None):
    reply = ask_convoy(buyer_id, text or "[图片]",
                       channel="shopee", image_url=image_url)
    platform_send_message(buyer_id, reply)   # 调平台发消息 API
```

---

## 9. 多轮会话

- `session_id` 是会话记忆的 key：**同一买家跨消息用同一个值**，AI 才能理解“它 / 这个 / 刚才那款”等指代。
- 不同买家必须用不同 `session_id`（建议直接用平台买家 id）。
- 上下文由接口保留，你无需传历史；想重置就换一个新的 `session_id`。

---

## 10. 多语言

无需传语言参数，接口自动检测买家语言并用该语言回复。产品型号、LED 名、规格数字、URL 保持原文。价格统一不报（零售模式），本地货币与定价由你的店铺自行展示。

---

## 11. 错误码与健壮性

| HTTP | 含义 | 建议处理 |
|---|---|---|
| `200` | 成功 | 取 `reply` 发回买家 |
| `401` | 密钥缺失/无效 | 检查 `X-Api-Key`；勿在前端调用 |
| `403` | 邀请码无效（注册时） | 联系运营获取有效邀请码 |
| `400` | 渠道名错误 / JSON 格式错 | 对照第 7 节、检查请求体 |
| `422` | `text` 和 `image_url` 都为空 | 至少传一个 |
| `500` / 超时 | AI 服务异常 | 重试 1 次；仍失败转人工，勿把技术错误抛给买家 |

**最佳实践**

- 超时设 **90 秒**（图片诊断可能稍慢），普通文本通常数秒。
- 做**降级**：接口异常时自动回复“正在为您转接人工客服”，不要卡住买家。
- `reply` 是 Markdown：微信/WhatsApp 等不渲染的渠道，建议把 `**粗体**`、表格等转纯文本，链接保留明文 URL。
- 可记录 `intent` 做问答统计；没把握的问题建议转人工。
- `api_key` 放服务器端环境变量，不要写进前端。

---

## 12. 数据与边界

- 零售接入是**纯产品知识客服**：回答参数/适配/使用/对比/故障，**不报价、不承诺库存**（卖家自己定价、管库存），售后严格用卖家自填政策。
- 接口**不返回**官网价、批发价、内部成本——价格由你的店铺决定。
- 适配结论基于官网明示；官网未声明的兼容关系不臆测。
- 故障诊断为 AI 辅助参考，最终售后以人工 / 官方检测为准。

---

## 13. 联调

- 运营提供：邀请码（注册用）。
- 自助流程：注册 → 控制台填政策 → 用本文 cURL 打通 → 再接平台 webhook。
- 控制台：`https://api.zeefox.cn/console` ｜ 文档：`https://api.zeefox.cn/docs`
- 对接问题联系 Convoy 运营。

---

*Convoy AI 客服开放平台 · 知识库由 Convoy 官方维护更新。*