接入文档

挂件嵌入

把客服挂件嵌入您的网站，只需一段代码。

获取嵌入代码

登录商户后台 → 渠道设置 → 嵌入代码，复制您专属的嵌入代码：

<script>
  window.$aicrs = window.$aicrs || { q: [] };
</script>
<script async src="https://您的客服域名/widget/loader.js" data-wk="您的widget_key"></script>

把这段代码粘贴到您网站每个页面的 </body> 之前即可。挂件会在页面右下角显示聊天气泡，访客点击即可开始咨询。

域名白名单

为防止挂件被盗用，挂件只在您登记的域名下生效。在商户后台 → 渠道设置 → 域名白名单 添加您的网站域名（支持多个）。未登记的域名加载挂件时会静默失败，不影响您的页面。

widget_key 重置

如怀疑 key 泄露，可在渠道设置中重置。重置后旧 key 立即失效，需要同步更新您网站上的嵌入代码。

常见问题

• 挂件不显示？ 检查当前域名是否在白名单内、widget_key 是否与后台一致、账号是否处于服务期内。
• 影响网站速度吗？ 加载器小于 1KB 且异步加载，不阻塞您的页面渲染。

identify 会员对接

访客在您网站登录后，调用 identify 传入会员信息，客服系统会把该浏览器的会话归到这位会员名下——坐席能直接看到会员身份，多设备访问也会合并为同一访客。

调用方式

在您的页面判断用户已登录后调用：

$aicrs.identify({
  externalId: 'U10086',      // 必填，您系统中的用户唯一标识
  name: '李女士',             // 可选，显示名
  phone: '138****0000',      // 可选
  email: 'user@example.com', // 可选
  hash: '服务端计算的HMAC签名',  // 必填，防伪造
  custom: { vip: 'gold' }     // 可选，附加字段，坐席侧可见
})

签名算法

hash 必须在您的服务端计算（widget_secret 不能出现在前端代码里）：

hash = HMAC-SHA256(widget_secret, externalId) 的十六进制小写

widget_secret 在商户后台 → 渠道设置 → 嵌入代码 查看，与 widget_key 一起重置。

Node.js 示例：

const crypto = require('crypto')
const hash = crypto.createHmac('sha256', WIDGET_SECRET).update(externalId).digest('hex')

校验结果

签名校验通过的访客在坐席侧显示"已验证"标识；校验失败时 identify 调用被忽略并保持匿名身份，不会报错打断您的页面。

Webhook 事件推送

系统在关键业务事件发生时，向您配置的回调地址推送 JSON 消息，便于您把客服数据同步到自己的系统。

配置

商户后台 → 数据与系统 → Webhook：填写回调 URL（必须 HTTPS）与签名密钥 secret，选择订阅的事件类型。保存后可点击"发送测试事件"即时联调。

请求格式

每次推送为一个 POST 请求：

POST 您的回调URL
Content-Type: application/json
X-AICRS-Event: 事件类型
X-AICRS-Signature: HMAC-SHA256(secret, 请求体) 十六进制小写

请求体结构：

{
  "event": "message.created",
  "tenant_id": 129,
  "timestamp": 1784500000,
  "data": { "对象快照": "..." }
}

事件类型

验签与重试

收到推送后请用 secret 对原始请求体计算 HMAC-SHA256，与 X-AICRS-Signature 比对，不一致应丢弃。

您的接口返回 2xx 视为成功；失败后按 1 分钟 / 5 分钟 / 15 分钟 间隔重试共 3 次，仍失败置为失败状态，可在后台投递记录中查看失败原因并手动排查。

开放 API

开放 API 用于从您的系统读取客服数据、创建工单，按商户隔离。

认证

商户后台 → 数据与系统 生成 API Key（形如 ak_ 开头，明文仅生成时展示一次，请妥善保存；重置后旧 Key 立即失效）。

所有请求带请求头：

Authorization: Bearer ak_您的Key

限流

每个 Key 60 秒内最多 120 次请求，超出返回 429。

接口列表

示例：

curl -H "Authorization: Bearer ak_xxx" \
  "https://您的客服域名/api/open/v1/conversations?page=1"

说明

• 所有响应为 JSON，列表接口支持 page 分页参数。
• 当前版本不支持通过 API 向访客发送消息。
• 商户停用或服务到期时 API 一并暂停。

错误码对照

所有接口的错误响应统一为 JSON 结构：

{ "code": "错误码", "message": "中文提示" }

HTTP 状态码与 code 对应关系：

处理建议：

• 401/403：检查 Key 是否有效、账号服务状态。
• 429：按 Retry-After 或退避策略稍后重试。
• 5xx：幂等接口可安全重试；非幂等操作请先查询确认再重试。