API Reference

Three Endpoints Power the Full Widget Flow

The widget talks to the backend through just three HTTP APIs: fetch config, heartbeat ping, send message. Full spec below, with ready-to-run cURL examples for each endpoint.

Base URL

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

認證方式

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

Endpoint 列表

GET/api/widget/config

Fetches the bot's customization (primary color, button position, bot name, avatar, welcome message, placeholder, enabled flag). Called once when the widget loads.

Request

Query string:
token (string, required) — 32 lowercase hex widget token

Response

200 OK:

{
  "success": true,
  "config": {
    "primary_color": "#00d4ff",
    "position": "br",
    "bot_name": "AI Assistant",
    "avatar_url": "",
    "welcome": "Hi, how can I help?",
    "placeholder": "Type a message...",
    "enabled": true
  }
}

Errors

404 token does not exist / wrong format

cURL

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

POST/api/widget/ping

Widget load heartbeat. The backend writes widget_last_seen_at (timestamp) and widget_last_domain (parsed from Origin header). Fires once per page load.

Request

Headers: Content-Type: application/json
Body:

{ "token": "YOUR_TOKEN" }

Response

200 OK:

{ "success": true }

Errors

404 invalid token・429 > 30 pings per minute from the same IP

cURL

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

POST/api/widget/message

Visitor sends a message to the AI. The backend runs RAG → returns the AI reply (and possible extra replies). Conversations are written to Redis for live-agent viewing in the dashboard.

Request

Headers: Content-Type: application/json
Body:

{
  "token":   "YOUR_TOKEN",
  "message": "Hello",                // 1-300 chars
  "history": [...],                  // last 10 messages
  "chat_id": "web_xxxxxxxx"          // optional, prefix web_ + 8-32 hex
}

Response

200 OK (success):

{
  "success": true,
  "reply": "Hello! ...",
  "extra_replies": [{ "text": "..." }, ...]
}

200 OK (service paused):

{ "success": false, "reply": "Service paused" }

Errors

400 empty / non-string / > 300 chars・404 invalid token・429 > 20 messages per minute from the same IP・500 AI layer error

cURL

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