跳到正文
AI-SNS.IO — CHAT SUPPORTAI-SNS.IO — CHAT SUPPORT
AI SNS CHAT 使用

用 REST API 扩展 AI SNS CHAT:从集成设计到上线清单

AI SNS CHAT 编辑部发布于 阅读约 6 分钟

什么时候该用 REST API、如何用 SSE 与签名 Webhook 对接自家系统,并附限流、安全与上线测试清单,适合跨境电商与客服团队。

你的订单系统在自己的数据库里,会员资料在自建后台,客服界面又想做成品牌专属的样子。内置渠道和集成已经能覆盖大部分需求,但总有一块需要自己写代码来接。这篇文章帮你判断什么时候该用 REST API、它由哪些部件组成、如何遵守限流与安全要求,以及怎样稳妥地测试和上线。

什么时候适合用 API,什么时候不适合

API 是最灵活的工具,但也是维护成本最高的工具。很多团队其实只需要在后台点几下,就不必写一行代码。

适合用 API 的场景:

  • 你想在自己的 App、会员中心或内部系统里嵌入对话界面,而不是使用现成的聊天组件。
  • 你需要把回复以流式方式显示在自己的前端上。
  • 你要在对话发生的同时,把事件推送到自家的工单、ERP 或数据仓库。
  • 你有一个后端流程,需要主动调用智能体来生成回答。

不必用 API 的场景:

  • 只是想把智能体放到网站、WhatsApp、LINE、WeChat、Messenger 等渠道。这些在“渠道”页面里按步骤连接即可。
  • 只是想查订单、查日历或收集线索。内置的操作(Actions)和只读查询工具已经覆盖了不少常见系统。
  • 只是想在转人工时通知客服。转人工提醒本身就能发到 Slack、Teams、LINE WORKS、WhatsApp、邮件或 Webhook。
内置方案
自定义 API
网站聊天、WhatsApp、LINE、WeChat 等渠道上线
在自家 App 或会员中心里做专属对话界面
Shopify、Stripe、Slack 等内置操作
对接自建订单系统或内部后台
转人工提醒发到 Slack、邮件
把对话事件写入自家工单或数据仓库
几分钟内在后台配置完成
需要开发、测试与持续维护
内置方案还是自定义 API?示意示例

API 的基本构件

AI SNS CHAT 的公开 API 是 JSON 格式的 REST 接口,核心部件有三个。

API 密钥

密钥在“工作区设置 → API keys”中创建。密钥只会显示一次,请当场保存到你的密钥管理工具里。密钥可以随时撤销,并且需要 Hobby 或更高方案。

流式回复(SSE)

请求时加上 stream=1,回复会以 SSE(Server-Sent Events)方式逐段返回。对前端来说,用户不必等整段答案生成完,体验更接近真人打字。

带签名的 Webhook

对话事件可以通过 Webhook 推送到你的服务器,每次请求都带有 HMAC 签名,并且后台有投递记录(delivery log),方便排查哪次推送失败了。

  1. 01你的前端或后端
  2. 02AI SNS CHAT API
  3. 03智能体生成回复
  4. 04签名 Webhook 回到你的系统
自定义集成的整体流程示意示例

具体的接口路径、参数与返回格式,请以 API 参考文档为准,本文不重复列举。

遵守已公布的限流

文档中公布的限流如下:

类型限制
认证每个 IP 每 5 分钟 20 次
公开聊天每个 IP 每分钟 30 次
轮询每分钟 120 次

这些限制是按 IP 计算的,因此有几个实际要点:

  • 如果所有用户请求都经过你自家的一台服务器转发,那么这些请求在对方看来来自同一个 IP,很容易触顶。设计时要考虑这一点。
  • 能用 Webhook 就不要频繁轮询。Webhook 是推送,轮询是不停地问。
  • 遇到被限流的响应,要做指数退避重试,不要立刻重发。
  • 认证请求次数较少,因此不要每次调用都重新认证,应复用凭据。

举个假设的例子:如果你的服务器代理了所有访客的公开聊天请求,而同一时间有 50 位访客在对话,每人每分钟发一条消息,那么仅这一个出口 IP 就已经超出每分钟 30 次的限制。这种情况下,应让访客的浏览器直接发起请求,或在上线前与我们确认合适的架构。

行之有效的设计模式

模式一:自家界面 + 流式回复

前端调用 API 并读取 SSE,把文字逐段渲染出来。网络中断时,保留已显示的内容并给出“重试”按钮,而不是整段清空。

模式二:事件驱动同步

用 Webhook 接收对话事件,把需要的信息写入你的 CRM 或工单系统。接收端先快速返回成功状态,再异步处理,避免因处理太慢导致重复投递。

模式三:幂等处理

Webhook 可能因网络原因被重复送达。在你的系统里用事件的唯一标识去重,同一事件处理两次也不会产生两张工单。

模式四:降级预案

当 API 暂时不可用时,前端应显示友好提示,并给出人工客服入口,例如留下邮箱或转到 WhatsApp。不要让客户面对空白页面。

上线前的安全清单

  1. 密钥只放服务器端。 不要把 API 密钥写进网页源码或手机 App 里,任何人都能看到。
  2. 验证每一个 Webhook 的签名。 用共享密钥重新计算 HMAC,与请求中的签名比对,不一致就拒绝。
  3. 使用 HTTPS。 接收 Webhook 的地址必须是加密连接。
  4. 最小权限与轮换。 为不同环境使用不同密钥,人员离职或怀疑泄露时立即撤销并重新生成。
  5. 日志脱敏。 不要在日志里记录密钥和客户的敏感信息。
  6. 查看投递记录。 定期检查 Webhook 的 delivery log,发现持续失败的端点及时修复。
  7. 保护好智能体本身。 在智能体的安全设置里开启提示注入与滥用过滤,并留意每台设备的频率限制。

测试与逐步上线

  1. 先在 Playground 里确认回答质量。 接口只是通道,回答好不好取决于智能体的知识库与设定。
  2. 用测试密钥和测试工作区联调。 不要直接用正式环境开发。
  3. 做压力与限流演练。 模拟高峰流量,确认退避重试生效。
  4. 灰度发布。 先对一小部分用户或一个市场(比如先开新加坡站)开放,观察对话日志与评分,再扩大。
  5. 准备回滚。 智能体有还原点,每个智能体最多保留 40 个,改坏了可以退回;你自己的代码也要有可回退的版本。
  6. 上线后持续看数据。 在“用量”页查看各智能体的积分消耗,在聊天记录中查看用户的点赞或点踩。

在 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 适合你要做自家界面或自定义系统对接的情况。

#REST API#客服集成#Webhook#跨境电商#AI客服

用 AI SNS CHAT 付诸实践

创建基于您自有内容训练的 AI 智能体,并连接到网站、LINE、WhatsApp 等渠道。免费开始,无需信用卡。