什么时候该用 REST API、如何用 SSE 与签名 Webhook 对接自家系统,并附限流、安全与上线测试清单,适合跨境电商与客服团队。
你的订单系统在自己的数据库里,会员资料在自建后台,客服界面又想做成品牌专属的样子。内置渠道和集成已经能覆盖大部分需求,但总有一块需要自己写代码来接。这篇文章帮你判断什么时候该用 REST API、它由哪些部件组成、如何遵守限流与安全要求,以及怎样稳妥地测试和上线。
什么时候适合用 API,什么时候不适合
API 是最灵活的工具,但也是维护成本最高的工具。很多团队其实只需要在后台点几下,就不必写一行代码。
适合用 API 的场景:
- 你想在自己的 App、会员中心或内部系统里嵌入对话界面,而不是使用现成的聊天组件。
- 你需要把回复以流式方式显示在自己的前端上。
- 你要在对话发生的同时,把事件推送到自家的工单、ERP 或数据仓库。
- 你有一个后端流程,需要主动调用智能体来生成回答。
不必用 API 的场景:
- 只是想把智能体放到网站、WhatsApp、LINE、WeChat、Messenger 等渠道。这些在“渠道”页面里按步骤连接即可。
- 只是想查订单、查日历或收集线索。内置的操作(Actions)和只读查询工具已经覆盖了不少常见系统。
- 只是想在转人工时通知客服。转人工提醒本身就能发到 Slack、Teams、LINE WORKS、WhatsApp、邮件或 Webhook。
API 的基本构件
AI SNS CHAT 的公开 API 是 JSON 格式的 REST 接口,核心部件有三个。
API 密钥
密钥在“工作区设置 → API keys”中创建。密钥只会显示一次,请当场保存到你的密钥管理工具里。密钥可以随时撤销,并且需要 Hobby 或更高方案。
流式回复(SSE)
请求时加上 stream=1,回复会以 SSE(Server-Sent Events)方式逐段返回。对前端来说,用户不必等整段答案生成完,体验更接近真人打字。
带签名的 Webhook
对话事件可以通过 Webhook 推送到你的服务器,每次请求都带有 HMAC 签名,并且后台有投递记录(delivery log),方便排查哪次推送失败了。
- 01你的前端或后端
- 02AI SNS CHAT API
- 03智能体生成回复
- 04签名 Webhook 回到你的系统
具体的接口路径、参数与返回格式,请以 API 参考文档为准,本文不重复列举。
遵守已公布的限流
文档中公布的限流如下:
| 类型 | 限制 |
|---|---|
| 认证 | 每个 IP 每 5 分钟 20 次 |
| 公开聊天 | 每个 IP 每分钟 30 次 |
| 轮询 | 每分钟 120 次 |
这些限制是按 IP 计算的,因此有几个实际要点:
- 如果所有用户请求都经过你自家的一台服务器转发,那么这些请求在对方看来来自同一个 IP,很容易触顶。设计时要考虑这一点。
- 能用 Webhook 就不要频繁轮询。Webhook 是推送,轮询是不停地问。
- 遇到被限流的响应,要做指数退避重试,不要立刻重发。
- 认证请求次数较少,因此不要每次调用都重新认证,应复用凭据。
举个假设的例子:如果你的服务器代理了所有访客的公开聊天请求,而同一时间有 50 位访客在对话,每人每分钟发一条消息,那么仅这一个出口 IP 就已经超出每分钟 30 次的限制。这种情况下,应让访客的浏览器直接发起请求,或在上线前与我们确认合适的架构。
行之有效的设计模式
模式一:自家界面 + 流式回复
前端调用 API 并读取 SSE,把文字逐段渲染出来。网络中断时,保留已显示的内容并给出“重试”按钮,而不是整段清空。
模式二:事件驱动同步
用 Webhook 接收对话事件,把需要的信息写入你的 CRM 或工单系统。接收端先快速返回成功状态,再异步处理,避免因处理太慢导致重复投递。
模式三:幂等处理
Webhook 可能因网络原因被重复送达。在你的系统里用事件的唯一标识去重,同一事件处理两次也不会产生两张工单。
模式四:降级预案
当 API 暂时不可用时,前端应显示友好提示,并给出人工客服入口,例如留下邮箱或转到 WhatsApp。不要让客户面对空白页面。
上线前的安全清单
- 密钥只放服务器端。 不要把 API 密钥写进网页源码或手机 App 里,任何人都能看到。
- 验证每一个 Webhook 的签名。 用共享密钥重新计算 HMAC,与请求中的签名比对,不一致就拒绝。
- 使用 HTTPS。 接收 Webhook 的地址必须是加密连接。
- 最小权限与轮换。 为不同环境使用不同密钥,人员离职或怀疑泄露时立即撤销并重新生成。
- 日志脱敏。 不要在日志里记录密钥和客户的敏感信息。
- 查看投递记录。 定期检查 Webhook 的 delivery log,发现持续失败的端点及时修复。
- 保护好智能体本身。 在智能体的安全设置里开启提示注入与滥用过滤,并留意每台设备的频率限制。
测试与逐步上线
- 先在 Playground 里确认回答质量。 接口只是通道,回答好不好取决于智能体的知识库与设定。
- 用测试密钥和测试工作区联调。 不要直接用正式环境开发。
- 做压力与限流演练。 模拟高峰流量,确认退避重试生效。
- 灰度发布。 先对一小部分用户或一个市场(比如先开新加坡站)开放,观察对话日志与评分,再扩大。
- 准备回滚。 智能体有还原点,每个智能体最多保留 40 个,改坏了可以退回;你自己的代码也要有可回退的版本。
- 上线后持续看数据。 在“用量”页查看各智能体的积分消耗,在聊天记录中查看用户的点赞或点踩。
在 AI SNS CHAT 中怎么做
下面是一条从零开始的实际路径。
第一步:确认方案。 API 密钥需要 Hobby 或更高方案。免费方案无法创建密钥。
第二步:先把智能体调好。 在“数据源”里添加文件、文字片段、网站或问答,再到 Playground 里试问几个典型问题。如果你的客户主要说中文和英文,也可以用欢迎语的自动翻译功能,让组件按访客语言显示。
第三步:创建密钥。 进入“工作区设置 → API keys”,创建密钥并立刻存入密钥管理工具,页面不会再次显示。
第四步:接上流式回复。 在请求中使用 stream=1,前端按 SSE 读取。
第五步:配置 Webhook。 设置接收地址,在你的服务器上校验 HMAC 签名,并用投递记录排查失败的推送。
第六步:需要品牌域名时。 在“智能体 → 设置 → 自定义域名”里添加子域名 CNAME,系统会通过 DNS 查询验证,对嵌入脚本、iframe 和智能体链接都生效,同样需要 Hobby 或更高方案。
第七步:别忘了内置渠道。 如果只是要上 WhatsApp、LINE、WeChat 或网站聊天,直接在“渠道”页面连接,不需要 API。各渠道的连接方式可以参考 /connections。方案与积分详情见 /pricing,功能总览见 /features,安全相关说明见 /security。想先试用,可以到 /signup 注册。
补充说明:1 条回复消耗 1 个积分,通过 API 产生的回复同样计入用量,规划预算时请把自家界面的流量算进去。
结语
API 的价值在于把智能体接进你独有的系统和界面,但它不是起点。先用内置渠道和集成把能解决的问题解决掉,再对真正需要定制的部分使用 API,并守住限流、签名验证和密钥保管这三条底线。这样既能快速上线,也能长期稳定地维护。
常见问题
使用 REST API 需要哪个方案?
API 密钥需要 Hobby 或更高方案。密钥在“工作区设置 → API keys”创建,只显示一次,可随时撤销。具体价格以 /pricing 页面为准。
可以把回复流式显示在我自己的界面里吗?
可以。请求时加上 stream=1,回复会以 SSE 方式逐段返回,你的前端按流读取并渲染即可。
怎么确认 Webhook 真的来自 AI SNS CHAT?
Webhook 带有 HMAC 签名。你在服务器端用共享密钥重新计算并与请求中的签名比对,不一致就拒绝。后台还有投递记录,可以核对每次推送的状态。
限流是多少?
已公布的限制为:认证每个 IP 每 5 分钟 20 次,公开聊天每个 IP 每分钟 30 次,轮询每分钟 120 次。建议用 Webhook 取代频繁轮询,并对被限流的请求做退避重试。
要把智能体放到 WhatsApp 或 Messenger,一定要用 API 吗?
不需要。WhatsApp、Messenger、LINE、WeChat、Telegram 等都在“渠道”页面里直接连接。API 适合你要做自家界面或自定义系统对接的情况。


