API 參考

3 個 endpoint 搞定整個 Widget 對話流

Widget 跟後端只用 3 個 HTTP API 互動：拉設定（config）、心跳（ping）、發訊息（message）。下面是完整 spec，每個 endpoint 都附 cURL 可立即測試。

Base URL

所有 endpoint 都掛在 https://aibot.chungtair.com...

認證方式

Token-based：每個 Bot 有獨立的 widget_token...

Endpoint 列表

GET/api/widget/config

拉取 Bot 的客製化設定（主色、按鈕位置、Bot 名稱、頭像、歡迎語、placeholder、是否啟用）。Widget 載入時自動呼叫一次。

Request

Query string：
token (string, required) — 32 字小寫 hex widget token

Response

200 OK：

{
  "success": true,
  "config": {
    "primary_color": "#00d4ff",
    "position": "br",
    "bot_name": "AI 智能客服",
    "avatar_url": "",
    "welcome": "你好，有什麼可以幫你的嗎？",
    "placeholder": "請輸入訊息...",
    "enabled": true
  }
}

Errors

404 token 不存在 / 格式錯

cURL

curl 'https://aibot.chungtair.com/api/widget/config?token=YOUR_TOKEN_HERE'

POST/api/widget/ping

Widget 載入完成的心跳。後端據此寫入 widget_last_seen_at（時間）與 widget_last_domain（從 Origin header 解析）。一個網頁載入只觸發 1 次。

Request

Headers： Content-Type: application/json
Body：

{ "token": "YOUR_TOKEN" }

Response

200 OK：

{ "success": true }

Errors

404 invalid token・429 同 IP 每分鐘 > 30 ping

cURL

curl -X POST 'https://aibot.chungtair.com/api/widget/ping' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_TOKEN"}'

POST/api/widget/message

訪客送出訊息給 AI。後端跑 RAG → 回 AI 答覆（與可能的補充訊息）。對話會寫入 Redis 供後台客服查看。

Request

Headers： Content-Type: application/json
Body：

{
  "token":   "YOUR_TOKEN",
  "message": "你好",                  // 1-300 字
  "history": [...],                  // 最近 10 則對話
  "chat_id": "web_xxxxxxxx"          // 可選，前綴 web_ + 8-32 字 hex
}

Response

200 OK（成功）：

{
  "success": true,
  "reply": "您好！...",
  "extra_replies": [{ "text": "..." }, ...]
}

200 OK（客服暫停）：

{ "success": false, "reply": "客服暫停服務中" }

Errors

400 message 空 / 非字串 / > 300 字・404 invalid token・429 同 IP 每分鐘 > 20 訊息・500 AI 那層出錯

cURL

curl -X POST 'https://aibot.chungtair.com/api/widget/message' \
  -H 'Content-Type: application/json' \
  -d '{"token":"YOUR_TOKEN","message":"你好","history":[],"chat_id":"web_abcd1234"}'