接入文件

掛件嵌入

把客服掛件嵌入您的網站，只需一段代碼。

獲取嵌入代碼

登錄商戶後台 → 渠道設定 → 嵌入代碼，複製您專屬的嵌入代碼：

<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 傳入會員資訊，客服系統會把該瀏覽器的會話歸到這位會員名下——坐席能直接看到會員身份，多設備訪問也會合併為同一訪客。

調用方式

在您的頁面判斷用戶已登錄後調用：

$aicrs.identify({
  externalId: 'U10086',      // 必填，您系統中的用戶唯一標識
  name: '李小姐',             // 可選，顯示名
  phone: '138****00 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：冪等接口可安全重試；非冪等操作請先查詢確認再重試。

CRM開放介面

客戶與商機數據的讀寫走開放 API（/api/open/v1，Bearer ak_ 密鑰，商户後台"數據與系統 → API"生成）。

客戶

去重規則與後台一致：external_id > 手機號 > 郵箱，命中即歸並到既有客戶而不是重複建档。

限頻：每把 Key 60 秒 120 次，超出返回 429。

客戶事件推送

客戶生命周期事件走既有 Webhook 通道（商户後台「數據與系統 → Webhook」訂閱），簽名與重試機制與消息事件一致（X-AICRS-Signature HMAC-SHA256、指數退避重試）。

載荷格式：{"event":"customer.created","data":{...客戶對象...},"ts":1690000000}。收到後返回 2xx 即確認；非 2xx 或超時會按退避策略重試。