A Practical Guide to Running LibreChat with Ace Data Cloud

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

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

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

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

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

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

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

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

二、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 请以部署页显示的内容为准：

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 配置不会触发自动发送。

五、事件流要保存游标

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

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，不应用任意电话号码做冷启动触达。

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，应该查询：

GET /api/sends/{Idempotency-Key}

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

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

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

可从低风险开始

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

建议人工确认

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

应强制人工确认

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

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

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

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 使用指南
• AceDataCloud WhatsApp Account Proxy 服务页
• AceDataCloud 原始主题文章：把个人 WhatsApp 变成 AI 客服，需要解决哪些问题？