# Convoy AI 客服 · 接入教程（从零开始，保姆级）

> 这份文档假设你**完全不懂编程**也能看懂。跟着做，你就能让自己店铺的买家自动享受到 Convoy AI 客服。
> 如果你是技术人员，只想看接口规格，直接跳到 **第六部分：API 技术手册**。

---

# 第一部分：先搞懂这是什么

## 1.1 一句话说明

你在网上卖 Convoy 手电，买家天天问“这个灯多少流明？”“用什么电池？”“能配什么驱动？”“光斑有蓝点正常吗？”——**Convoy AI 客服就是一个自动回答这些问题的机器人**，它的脑子是 Convoy 官方的完整产品资料库，答得比人还准、还全，而且会用买家的语言（中/英/俄/日/韩/泰等 12 种）回答。

你要做的，只是把它“接到”你的店铺上。

## 1.2 它是怎么工作的？（图解）

买家的消息不会自己飞到 AI 那里。**好消息：这层“连接”由 Convoy 官方服务器替你托管**，你不用自己买服务器、不用写程序。整个流程是这样：

```
  买家            聊天平台            Convoy 官方托管连接器        Convoy AI
   │        (Telegram/WhatsApp…)       （我们的服务器）          （官方知识库）
   │  “S2+用什么电池？”                      │                       │
   │ ───────────>                           │                       │
   │                  平台把消息推给我们        │                       │
   │                ────────────────────────>│                       │
   │                                         │  拿你的密钥去问 AI      │
   │                                         │ ─────────────────────>│ 查官方资料
   │                                         │  “S2+ 用 18650 电池”   │
   │                                         │ <─────────────────────│
   │                  我们把回答发回平台        │                       │
   │ <───────────────────────────────────────│                       │
```

- **Convoy 官方托管连接器（我们提供并 7×24 运行）**：负责连接 Telegram / WhatsApp，收消息、问 AI、发回复。
- **你要做的只有两件事**：① 注册拿密钥；② 在控制台「渠道接入」里连上你的机器人。**全程不用买服务器、不用写代码。**
- 只有接入淘宝/Shopee 等电商平台开放接口（见 5.4）才需要少量开发，那一步可交给技术人员。

## 1.3 关于价格和售后（重要）

- AI **只回答产品知识**（参数、适配、电池、故障、对比），**不报价、不承诺库存**——因为每个店定价、库存不一样，这些由你自己掌握，AI 遇到价格问题会引导买家“以本店商品页为准 / 联系客服”。
- **退货、退款、保修这些话术由你自己填**（在控制台填一次，AI 就会照你说的回答买家）。

## 1.4 名词大白话

| 名词 | 大白话解释 |
|---|---|
| **API / 接口** | 一个“问答窗口”的网址。把问题按格式发过去，它把答案返回来。 |
| **API Key（密钥，ck_ 开头）** | 你的专属门禁卡，调用接口时必须带上。保密，别给外人、别放到网页前端。 |
| **邀请码（INVITE- 开头）** | 注册用的入场券，找 Convoy 运营要。防止陌生人乱注册。 |
| **控制台（console）** | 你自己的后台网页：填店铺资料、售后话术、**一键接入 Telegram/WhatsApp**、看密钥和统计。 |
| **托管连接器** | 我们服务器上替你连聊天平台、收发消息的程序，你不用管它。 |
| **Bot Token / Access Token** | 聊天平台给你的“机器人授权码”，填到控制台就能让我们托管你的机器人。 |
| **session_id（会话ID）** | 每个买家的编号，同一个买家一直用同一个号，AI 才记得住上下文。 |
| **channel（渠道）** | 你在哪个平台卖：telegram / whatsapp / shopee / taobao… |

---

# 第二部分：开始前，你要准备什么

**接入 Telegram / WhatsApp（官方托管）几乎零门槛**，只要：

| 准备项 | 说明 | 没有怎么办 |
|---|---|---|
| ✅ **一个邀请码** | 找 Convoy 运营领取（形如 `INVITE-XXXXXX`） | 联系运营 |
| ✅ **一个聊天平台账号** | Telegram 账号，或 WhatsApp 商务号（Meta 账号） | 免费注册 |
| ✅ 电脑/手机浏览器 | 打开控制台点点点即可，**不需要服务器** | —— |

> 💡 接 Telegram / WhatsApp **不用买服务器、不用装任何软件、不用懂编程**，照着第五部分 5.1 / 5.2 做，10 分钟就能让机器人自动回复。
>
> 🔧 只有接**独立站/淘宝/Shopee** 等（5.3、5.4）才涉及服务器或开发，那部分可以交给技术人员，或等官方托管连接器陆续上线。

---

# 第三部分：三步开通账号（网页点点点，不用写代码）

## 第 1 步：打开控制台注册

1. 浏览器打开 👉 **https://api.zeefox.cn/console**
2. 点 **「注册新店铺」** 页签。
3. 填写：
   - **邀请码**：粘贴运营给你的 `INVITE-XXXXXX`
   - **登录账号**：邮箱或用户名（以后用它登录，记住它）
   - **设置密码**：至少 6 位，再输一次确认
   - **店铺名称**：你的店铺名
   - **主营平台**：下拉选你主要在哪个平台卖
   - **联系方式**：选填
4. 点 **「注册并进入控制台」**，会自动登录。以后打开控制台用**账号 + 密码**登录即可。
   - ✅ 成功标志：自动进入了后台界面，左边能看到“店铺信息 / 售后政策 / 接入密钥 / 调用统计”几个菜单。
   - 系统会自动给你生成一串 **API Key（`ck_` 开头）**，在左侧 **「接入密钥」** 里能看到，**复制保存好**（这就是门禁卡）。

> 如果提示“邀请码无效/已达次数”，找运营重新要一个。

## 第 2 步：填写店铺信息和售后话术

1. 左侧点 **「店铺信息」**，填店铺名、平台、店铺链接、客服联系方式、发货说明等，点 **「保存店铺信息」**。
2. 左侧点 **「售后政策」**，把你的退货/退款/换货/保修政策一条条填进去，比如：
   - 退货政策：`支持7天无理由退货，商品需不影响二次销售`
   - 保修政策：`本店提供1年店铺保修`
   - 转人工：`工作时间 9:00-21:00，可加微信 xxx 转人工`
3. 点 **「保存售后政策」**。
   - ✅ 以后买家问“能退吗？保修多久？”，AI 就会**用你填的原话**回答。
   - 没填的项目，AI 不会乱编，会让买家联系人工客服。

## 第 3 步：你的 API Key（程序调用时才用）

- 日常登录控制台用**账号 + 密码**即可，不需要记 API Key。
- API Key（`ck_` 开头）是**给程序调用问答接口**用的凭证，在左侧 **「接入密钥」** 里能看到、复制。
- ⚠️ **API Key 只放在你的服务器/程序里，不要发到群里、不要写进网页或 App 前端。**

---

# 第四部分：5 分钟测试，先看到 AI 回复（不用接店铺）

在真正接店铺前，先确认你的密钥能用、AI 会回复。

## 方法一：用在线接口工具（推荐小白，不装任何东西）

1. 打开在线接口测试网站，例如 **https://www.apipost.cn** 或 **https://hoppscotch.io**（免费，网页直接用）。
2. 新建一个 **POST** 请求，网址填：
   ```
   https://api.zeefox.cn/api/chat
   ```
3. 在 **请求头（Headers）** 里加一条：
   - 名字：`X-Api-Key`，值：粘贴你的 `ck_` 密钥
   - 再加一条：`Content-Type`，值：`application/json`
4. 在 **请求体（Body）** 选 JSON，粘贴：
   ```json
   {
     "channel": "generic",
     "session_id": "test_001",
     "text": "S2+ 用什么电池？"
   }
   ```
5. 点 **发送**。
   - ✅ 成功标志：下面返回一段 JSON，里面 `"reply"` 就是 AI 的回答（大意是“Convoy S2+ 使用 18650 电池…”）。
   - 试试把 `text` 换成 `"M21H 多少钱"`，你会发现 AI **不报价**，只引导看店铺页——这是对的。
   - 换成英文 `"How bright is L8?"`，AI 会用英文回答。

## 方法二：用一行命令（电脑有终端的话）

把下面命令里的 `ck_你的密钥` 换成你的真实密钥，复制到终端（Mac 的“终端”/Windows 的 PowerShell）回车：

```bash
curl -X POST https://api.zeefox.cn/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ck_你的密钥" \
  -d '{"channel":"generic","session_id":"test_001","text":"S2+ 用什么电池？"}'
```

✅ 看到返回里有 `"reply": "……"` 就说明全通了。

---

# 第五部分：正式接入你的店铺

**Telegram 和 WhatsApp 都是官方托管，控制台点几下就连上，不用买服务器、不用写代码。** 建议先从 Telegram 开始（最简单）。

## 5.1 Telegram 机器人 —— 官方托管，无需服务器（推荐）

接 Telegram **不用买服务器、不用跑程序、不用写代码**，由 Convoy 官方服务器替你托管：

1. 在 Telegram 搜索 **@BotFather**（官方账号），发 `/newbot`，按提示给机器人起名字，拿到一串 **Bot Token**（形如 `123456:ABC-DEF…`）。
2. 打开控制台 👉 **https://api.zeefox.cn/console**，左侧点 **「渠道接入」**，找到 **Telegram**。
3. 把 Bot Token 粘贴进去，点 **「立即连接」**。状态变成“已连接 @你的机器人名”就成功了。

✅ 之后买家给你的 Telegram 机器人发消息，**全部由 Convoy AI 自动回复**——产品问答、多语言、多轮记忆、图片故障诊断、你填的售后话术，都自动生效。想停用随时点「断开连接」。

## 5.2 WhatsApp —— 官方托管，无需服务器

WhatsApp 用的是 Meta 官方 **WhatsApp Cloud API**（免费；个人号不能用 API，需要一个 Meta 商务账号）。同样由我们托管，你只需：

1. 打开 **developers.facebook.com**，创建一个 App（类型选 **Business**），在产品里添加 **WhatsApp**。
2. 在「WhatsApp → API 设置（API Setup）」里找到两个值：
   - **Phone Number ID**（手机号 ID，纯数字）
   - **Temporary Access Token**（临时令牌；正式用建议生成一个长期/永久 Token）
3. 打开控制台 **「渠道接入」→ WhatsApp**，把这两项填进去，点 **「连接」**。
4. 页面会显示一个 **Callback URL（回调地址）** 和 **Verify Token（校验令牌）**。回到 Meta「WhatsApp → Configuration（配置）→ Webhook」：
   - Callback URL 填页面给的地址；Verify Token 填页面给的令牌；点 **Verify and save（验证并保存）**。
   - 然后在 Webhook 字段里**订阅 `messages`** 这一项。

✅ 验证通过后，买家给你的 WhatsApp 商务号发消息，就由 Convoy AI 自动回复（文字 + 图片诊断 + 多语言 + 你的售后话术）。

> 注意：WhatsApp 规定**买家发消息后 24 小时内**可自由回复；超过 24 小时需用审核过的模板消息（AI 客服场景一般都在 24 小时窗口内）。
>
> 不会配置 Meta？也可以用第三方 WhatsApp 客服系统（如 WATI、360dialog），它们支持 webhook，可参考 5.3 让技术对接。

## 5.3 独立站 / WooCommerce / 自有网站 —— API 对接（需技术）

如果你有自己的网站，让技术在“收到买家消息”时调用问答接口即可，核心就一个 HTTP 请求（详见第六部分）：

- 买家消息 → 你的网站 `POST https://api.zeefox.cn/api/chat`（带密钥）→ 把返回的 `reply` 发给买家。
- 也可下载现成中转脚本 👉 **[webhook_relay.py](/examples/webhook_relay.py)**，填上密钥运行（默认 8080 端口），平台 webhook 指到它即可；部署到云函数（腾讯云/阿里云函数）也行。

## 5.4 Shopee / 淘宝 / 拼多多 / 抖店 / 闲鱼 —— 开放平台对接（需技术）

这些电商平台有官方开放平台，收发消息要走平台接口（需卖家资质、创建应用，部分要审核）：

| 平台 | 接法（交给技术） |
|---|---|
| **Shopee 虾皮** | Shopee Open Platform 注册开发者应用 → 卖家授权店铺 → Chat API 收发消息，中间调 `/api/chat`。 |
| **淘宝/天猫** | 千牛/淘宝开放平台 IM 消息订阅 + 发消息接口。 |
| **拼多多/抖店/闲鱼** | 官方客服开放能力有限，多用客服 SaaS（聚水潭、智齿、快麦等）或 RPA 中转；只要支持 webhook/机器人，就能调 `/api/chat`。 |

> 给技术的一句话：**收到平台消息 → `POST https://api.zeefox.cn/api/chat`（头带 `X-Api-Key`，body 带 `channel/session_id/text`）→ 把返回的 `reply` 发回去**，1～2 小时可完成。官方托管连接器也在陆续开放中，届时可零代码接入。

## 5.5 不想写代码？

- **Telegram / WhatsApp**：直接用 5.1 / 5.2 的**官方托管**，控制台填授权即可，这是最省事的方式。
- 其他平台可找会编程的人/外包，把本文档发给他，核心就是“调一个接口转发消息”，工作量很小。
- 也可以用 **n8n / Make** 这类拖拽式自动化工具：平台消息触发 → HTTP 请求节点调 `/api/chat` → 回复发回，无需写代码。

> 🔧 **高级/自托管（一般不需要）**：如果你出于数据等原因想在自己服务器跑机器人，可下载示例 [telegram_bot.py](/examples/telegram_bot.py)（Telegram）或 [webhook_relay.py](/examples/webhook_relay.py)（通用），填入密钥运行。普通卖家无需这一步。

---

# 第六部分：API 技术手册（给开发人员）

## 6.1 接口总览

- 基址：`https://api.zeefox.cn`
- 全部 HTTP + JSON，UTF-8。
- 跨域已开启（CORS `*`）。

| 方法 | 路径 | 鉴权 | 用途 |
|---|---|---|---|
| POST | `/api/register` | 无（需邀请码） | 注册，返回 api_key 和 console_token |
| POST | `/api/chat` | `X-Api-Key: ck_…` | **问答（核心）** |
| POST | `/api/console/login` | 无（body 带 api_key） | 用 api_key 换 console_token |
| GET | `/api/console/me` | `X-Console-Token: cs_…` | 读取本账号信息 |
| POST | `/api/console/save` | `X-Console-Token: cs_…` | 保存店铺/售后配置 |
| GET | `/api/console/usage` | `X-Console-Token: cs_…` | 本账号调用统计 |
| POST | `/api/console/connector/telegram` | `X-Console-Token: cs_…` | 一键接入/断开/查询 Telegram 托管 |
| POST | `/api/console/connector/whatsapp` | `X-Console-Token: cs_…` | 一键接入/断开/查询 WhatsApp 托管 |

> **渠道接入推荐用控制台网页**（「渠道接入」页填表即可）。以下 connector 端点供自动化/技术使用，body 带 `{"action":"connect"|"disconnect"|"status", ...}`：
> - Telegram connect：`{"action":"connect","bot_token":"123:ABC…"}`
> - WhatsApp connect：`{"action":"connect","phone_number_id":"123","access_token":"EAA…"}`，返回里含 `webhook_url` 和 `verify_token`，需填到 Meta 后台。

## 6.2 注册

```bash
curl -X POST https://api.zeefox.cn/api/register \
  -H "Content-Type: application/json" \
  -d '{"invite":"INVITE-XXXXXX","account":"you@example.com","password":"你的密码","name":"你的店铺名","channel":"shopee"}'
```
返回（自动登录，含 console_token；api_key 在控制台「接入密钥」查看）：
```json
{"ok":true,"account_id":"acct_xxx","console_token":"cs_xxx","mode":"retail","account":{"name":"你的店铺名","api_key":"ck_xxx"}}
```
登录接口 `POST /api/console/login`：body 为 `{"account":"you@example.com","password":"密码"}`，返回 `console_token`。
> 邀请码错误/用尽返回 **403**。

## 6.3 问答接口 `POST /api/chat`

请求头：
```
Content-Type: application/json
X-Api-Key: ck_你的密钥
```

请求体：

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `channel` | string | 是 | `shopee`/`taobao`/`pdd`/`douyin`/`xianyu`/`wordpress`/`woocommerce`/`whatsapp`/`telegram`/`generic` |
| `session_id` | string | 是 | 买家唯一且稳定的 id；同一买家保持一致才有多轮记忆 |
| `text` | string | 二选一 | 买家文字 |
| `image_url` | string | 二选一 | 买家图片的公网 URL（光斑/手电照片做故障诊断）；可与 text 同传 |

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

- `reply`：发给买家的文本（Markdown；不渲染 Markdown 的渠道自行转纯文本，链接保留明文 URL）。
- `intent`：意图，便于你统计：`specs`/`parts_lookup`/`compatibility`/`battery_usage`/`comparison`/`after_sales`/`diagnosis_*`/`pricing` 等。
- 零售接入 `tier` 恒为 `customer`、`mode` 恒为 `retail`。

## 6.4 店铺/售后配置 `POST /api/console/save`

请求头加 `X-Console-Token: cs_xxx`，body 可含以下字段（只传要改的）：

| 字段 | 含义 |
|---|---|
| `shop_name` / `platform` / `shop_url` / `contact` | 店铺名 / 平台 / 链接 / 联系方式 |
| `timezone` / `language` | 时区 / 默认语言 |
| `shipping_note` | 发货、运费说明 |
| `return_policy` / `refund_policy` / `exchange_policy` / `warranty_policy` | 退货/退款/换货/保修话术 |
| `human_handoff` | 转人工说明 |
| `extra_note` | 其他想让 AI 遵守的备注 |

## 6.5 各语言调用示例

**Python**
```python
import requests
def ask(buyer_id, text, channel="generic", image_url=None):
    body = {"channel": channel, "session_id": str(buyer_id), "text": text}
    if image_url: body["image_url"] = image_url
    r = requests.post("https://api.zeefox.cn/api/chat",
        headers={"X-Api-Key": "ck_xxx", "Content-Type": "application/json"},
        json=body, timeout=90)
    return r.json()["reply"]
```

**Node.js**
```javascript
async function ask(buyerId, text, channel="generic"){
  const r = await fetch("https://api.zeefox.cn/api/chat", {
    method:"POST",
    headers:{"X-Api-Key":"ck_xxx","Content-Type":"application/json"},
    body: JSON.stringify({channel, session_id:String(buyerId), text})});
  return (await r.json()).reply;
}
```

**PHP**
```php
function ask($buyerId,$text,$channel="generic"){
  $ch=curl_init("https://api.zeefox.cn/api/chat");
  curl_setopt_array($ch,[CURLOPT_POST=>1,
    CURLOPT_HTTPHEADER=>["Content-Type: application/json","X-Api-Key: ck_xxx"],
    CURLOPT_POSTFIELDS=>json_encode(["channel"=>$channel,"session_id"=>$buyerId,"text"=>$text]),
    CURLOPT_RETURNTRANSFER=>1,CURLOPT_TIMEOUT=>90]);
  return json_decode(curl_exec($ch),true)["reply"]??"";
}
```

## 6.6 错误码

| HTTP | 含义 | 处理 |
|---|---|---|
| 200 | 成功 | 取 `reply` 发回买家 |
| 401 | 密钥缺失/错误 | 检查 `X-Api-Key` |
| 403 | 邀请码无效（注册时） | 找运营要有效邀请码 |
| 400 | 渠道名/JSON 格式错 | 对照 6.3 检查 |
| 422 | text 和 image_url 都为空 | 至少传一个 |
| 500/超时 | AI 服务异常 | 重试 1 次；仍失败转人工 |

**健壮性建议**：超时设 90 秒（图片诊断稍慢）；接口失败时自动回复“正在为您转接人工”，别把技术错误抛给买家；`session_id` 用平台买家 id；密钥放服务端环境变量。

---

# 第七部分：常见问题 FAQ

**Q：AI 会报价格吗？**
不会。零售模式下 AI 只答产品知识，价格/库存引导买家看你的商品页或联系客服，避免不同店铺定价冲突。

**Q：买家问退货退款，AI 怎么答？**
严格按你在控制台「售后政策」里填的内容回答；没填的就引导联系人工，绝不乱编。

**Q：支持哪些语言？**
自动检测买家语言并用该语言回复（中/英/俄/日/韩/泰/德/法/西/葡/意/马来等），型号和数字保持原文，无需你设置。

**Q：能识别图片吗？**
能。买家发光斑/手电照片，传 `image_url`（必须是公网能打开的图片网址），AI 会做故障诊断（如蓝点、暗斑、偏色），结论会注明“仅供参考，以人工/售后检测为准”。

**Q：同一个买家多轮对话，AI 记得住吗？**
记得，只要你对同一买家始终用同一个 `session_id`（建议直接用平台买家 id）。换 id 等于新会话。

**Q：怎么修改登录密码 / 忘记密码？**
登录卖家控制台，左侧「账号安全」可修改密码（需原密码）；忘记密码联系 Convoy 运营，运营可在后台为你重置。运营后台管理员也可在「管理员账号」页修改自己的密码。

**Q：数据存在哪、会丢吗？**
账号、配置等数据存在数据库中，每天自动备份；邀请码、密钥均加密/散列存储，密码不可见。

**Q：密钥泄露了怎么办？**
联系 Convoy 运营，可作废重发。平时密钥只放服务器，别放前端。

**Q：调用收费吗？**
计费/额度政策咨询 Convoy 运营；控制台「调用统计」可看你自己的调用量。

**Q：测试返回 401？**
密钥没带对或填错了。确认请求头是 `X-Api-Key`，值是完整的 `ck_` 密钥，没有多余空格。

**Q：返回 403 邀请码错误？**
邀请码打错、已停用或被用完了，找运营要新的。

**还有问题？** 联系 Convoy 运营，把你的报错（最好截图或返回的 JSON）发过来即可。

---

*Convoy AI 客服开放平台 · 知识库由 Convoy 官方维护更新 · 问答接口 `POST https://api.zeefox.cn/api/chat`*