# A Practical Guide to Running LibreChat with Ace Data Cloud

![WhatsApp 客服接入指南](https://cdn.acedata2.cloud/gpt-image/47034f354cc1777ce23937b7ff134e3b4b7756b2c722dc5c0eea127f7c14f5a5.webp)

跨境电商、外贸服务和小团队经常会遇到同一种情况：询价、订单号、物流催促、产品图片、售后问题，全堆在聊天窗口里。

消息少的时候，人工逐条处理问题不大；一旦会话变多，麻烦就来了：上下文要反复翻，订单状态要去后台查，同一个问题不同客服的回答还可能不一样。更棘手的是，简单接一个大模型并不能解决这些问题。模型如果看不到真实会话、拿不到业务数据，或者在没有确认的情况下直接发消息，效率问题很容易变成业务风险。

这篇文章不讨论“全自动客服”，而是拆一条更稳妥的链路：用 AceDataCloud WhatsApp Account Proxy 接入已授权账号，把消息读取、知识查询、回复起草、人工确认和发送状态追踪串起来。

> 先把边界讲清楚：这项服务使用 WhatsApp 的关联设备能力，并不是 WhatsApp Business 官方 API；服务本身也不包含 AI，不会自动回复、主动联系或群发。

## 一、真正的痛点不只是“回复慢”

如果只看表面，客服系统需要解决的是响应速度。落到工程上，至少还有五件事要处理：

1. **消息入口**：Agent 如何读取账号中真实存在的会话和新消息；
2. **上下文完整度**：本地能拿到多少历史，缺失时如何补问；
3. **数据准确性**：政策类问题查知识库，订单、库存和物流查业务系统；
4. **发送安全**：哪些内容可以自动处理，哪些必须由人确认；
5. **结果一致性**：网络超时后如何避免把同一条消息发两遍。

换句话说，接入大模型只是中间一步。通信、数据、权限和状态管理缺一不可。

![客服消息过载与 AI 协助场景](https://cdn.acedata2.cloud/gpt-image/ab2637201aa1a379651f53370038bc9d7a1d6084f09e0f99e14fc4ce0235ed37.webp)

## 二、AceDataCloud 在链路里负责什么

WhatsApp Account Proxy 以独立实例部署。账号所有者通过二维码或配对码关联自己的 WhatsApp，实例会提供专属地址、Bearer Token，以及 MCP 和 REST 两种接入方式。

它适合承担通信层的工作：

- 读取已经同步到关联设备的会话、联系人和本地消息；
- 通过长轮询或 SSE 接收消息、连接状态和发送状态事件；
- 在账号权限和当前规则允许的范围内发送文本、媒体，引用回复、添加表情反应和标记已读；
- 查询发送记录，区分 `pending`、`accepted`、`unknown`、`delivered` 和 `read`；
- 通过幂等键避免不确定状态下的重复发送。

它不会替代 CRM、订单、物流、知识库或图片识别模型。比较合理的分工是：Proxy 负责收发和状态，业务系统提供实时数据，模型负责理解与起草，人工处理高风险决策。

## 三、先部署，再由账号本人完成关联

基本流程可以压缩成三步：

1. 在 AceDataCloud 控制台创建 **WhatsApp Account Proxy** 应用，启用订阅并部署实例；
2. 实例就绪后，由账号本人在 WhatsApp 的“设置 → 关联设备 → 关联设备”中扫描二维码，也可以使用配对码；
3. 状态变为已连接后，复制实例提供的 MCP 地址和 Bearer Token，接入自己的 Agent 或后端服务。

服务页面：<https://platform.acedata.cloud/console/services/whatsapp-bot>

使用文档：<https://platform.acedata.cloud/documents/development_whatsapp_bot>

Bearer Token 应只放在请求头里，不要拼到 URL，也不要写进前端代码和日志。除了 `/health` 与 `/readyz`，REST、MCP、扫码和配对接口都需要鉴权。

## 四、用 REST 跑通最小读取链路

实例地址和 Token 请以部署页显示的内容为准：

```bash
BASE='https://whatsapp-bot-<instance-id>.app.acedata.cloud'
TOKEN='<access-token>'

# 查看连接状态
curl "$BASE/api/auth/status" \
  -H "Authorization: Bearer $TOKEN"

# 读取最近会话
curl "$BASE/api/chats?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# 读取某个会话的最近消息
curl "$BASE/api/chats/123%40s.whatsapp.net/messages?limit=20" \
  -H "Authorization: Bearer $TOKEN"
```

建议在业务逻辑开始前调用 `/api/capabilities`。这个接口返回当前实例实际支持的操作和保留限制，比在代码里写死能力更稳妥。

如果使用 MCP，则把部署页给出的 MCP 地址配置到支持 Streamable HTTP 和自定义请求头的客户端中，并添加相同的 Bearer Token。仅完成 MCP 配置不会触发自动发送。

## 五、事件流要保存游标

实时处理可以使用两种方式：

```text
GET /api/events?after=<previous_next_cursor>&wait_ms=25000
GET /api/events/stream?after=<cursor>
```

前者是最长 25 秒的长轮询，后者是 SSE。事件中的 `seq` 单调递增，服务返回的 `next_cursor` 应写入持久化存储。

当返回 `gap=true` 时，说明一部分旧事件已经被清理。此时不要直接假设消息连续，而应重新读取当前聊天状态，再从 `oldest_cursor` 继续。消息事件、发送状态和连接状态也是分别上报的，业务端需要分别处理。

## 六、发送接口必须配合幂等键

发送前，应让账号所有者确认收件人和具体内容。目标应使用会话或联系人接口返回的 JID，不应用任意电话号码做冷启动触达。

```bash
curl -X POST "$BASE/api/messages" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: support-order-20261023-0001" \
  -H 'Content-Type: application/json' \
  -d '{
    "target": "123@s.whatsapp.net",
    "action": "text",
    "text": "已收到你的订单号，我们正在查询处理状态。"
  }'
```

`Idempotency-Key` 的长度要求是 8～128 个字符。同一笔业务发送应始终复用同一个键。

这里有一个容易误判的状态：`accepted` 只表示本地连接接受了发送，不等于对方已经收到。若状态为 `unknown`，应该查询：

```text
GET /api/sends/{Idempotency-Key}
```

同时检查消息事件。不要换一个新键再次提交同样的消息，否则可能出现重复回复。代理不会自动重试结果不确定的操作。

## 七、客服流程应按风险分层

比较稳妥的做法，不是一步到位自动化，而是先给回复分类。

### 可从低风险开始

- 确认已收到消息；
- 提醒补充订单号或型号；
- 提供公开的工作时间；
- 发送已经审核过的帮助文档。

### 建议人工确认

- 产品推荐与售后处理步骤；
- 预计完成时间；
- 多语言回复；
- 需要结合图片、语音或文件判断的问题。

### 应强制人工确认

- 报价、折扣和退款金额；
- 合同或责任表述；
- 编辑、撤回消息；
- 修改群组或成员。

可以把流程设计成：新消息进入 → 拉取最近上下文 → 识别意图和风险 → 查询知识库或业务系统 → 生成草稿 → 人工确认 → 使用固定幂等键发送 → 跟踪状态 → 写回 CRM 或工单。

![WhatsApp 客服处理闭环](https://cdn.acedata2.cloud/gpt-image/2cfa2952935bd255ca7d24c11318cbc03b0b3bf89df3ddfe74824678bd68ea21.webp)

## 八、几个必须提前知道的限制

### 1. 历史消息并不无限

只能读取真正同步到关联设备的消息，以及代理在线期间收到的消息。服务不保证获得全部旧聊天。本地最多保留最近 5,000 条消息和 2,000 个事件。

因此，Agent 发现上下文不足时，应要求用户补充订单号、型号或问题描述，不要自行补全事实。

### 2. 媒体有大小和可用性边界

当前文本和媒体收发的单个媒体上限为 10 MiB，超出时会返回 HTTP 413。即使本地仍有媒体元数据，原始文件也可能已经无法下载。

Proxy 不是图片识别、语音转写或 PDF 解析工具。需要处理附件时，还要按媒体类型接入相应模型或解析服务。

### 3. 发送记录也有容量上限

发送记录不会自动淘汰；达到 100,000 条后，实例会拒绝新的发送并返回 HTTP 507。上线后需要把容量监控纳入运维，而不是等接口报错才处理。

### 4. 连接方式存在平台侧风险

该服务依赖关联设备能力，并非 WhatsApp Business 官方 API。协议变化、设备撤销或账号限制都可能造成中断。正式使用前，应结合账号合规、业务连续性和人工兜底方案评估。

## 九、关于价格

AceDataCloud 当前服务页展示的是周期订阅：1 天 0.14、7 天 0.98、30 天 4.2。价格可能调整，实际下单前应以服务页实时显示为准。

这里还要分清两类成本：Proxy 的部署订阅是一部分；如果业务链路中另外调用大模型、语音转写、图片理解、知识库或其他外部系统，还会产生对应服务的成本，不能把它们混在一起估算。

## 十、适合与不适合的场景

这套方式适合已有 WhatsApp 会话，希望在本人授权下做消息整理、客服草稿、人工审核和状态追踪的团队。

它不适合用来：

- 给陌生号码批量发消息；
- 做未经同意的营销群发；
- 绕过平台规则；
- 冒用他人账号；
- 宣称能读取全部历史或永久稳定在线。

## 结语

把 WhatsApp 接进 Agent，难点从来不只是“让模型看到一条消息”。真正需要设计的是上下文边界、实时事件、业务数据、人工确认、幂等发送和异常恢复。

如果准备从小范围开始，建议先落地三件事：**整理新消息、查询真实信息、生成待确认的回复草稿**。等流程稳定、风险划分清楚，再逐步增加自动化范围。这样做速度可能没那么激进，但更容易维护，也更适合真实客服场景。

## 参考资料

- [AceDataCloud WhatsApp Account Proxy 使用指南](https://platform.acedata.cloud/documents/development_whatsapp_bot)
- [AceDataCloud WhatsApp Account Proxy 服务页](https://platform.acedata.cloud/console/services/whatsapp-bot)
- [AceDataCloud 原始主题文章：把个人 WhatsApp 变成 AI 客服，需要解决哪些问题？](https://platform.acedata.cloud/blog/turn-personal-whatsapp-into-ai-customer-service)