Wusper Chat API 說明文件 Wusper Chat API 说明文档 Wusper Chat API docs

打哪：Base URL 與路徑一覽

三種金鑰共用的路徑：

方法	完整 URL	說明
GET	https://chat.wusper.com/api/v1/me	查金鑰類型、擁有者、綁定房間／Bot
GET↑WS	wss://chat.wusper.com/api/v1/ws	三種金鑰即時進線（Bearer 或 ?access_token=）
GET	https://chat.wusper.com/api/version	版本與文件／套件路徑（無需 Bearer）

① 私人對話（type: private，金鑰 wc_…）

方法	完整 URL	說明
GET	https://chat.wusper.com/api/v1/private/messages?limit=50&order=newest	讀取綁定私人房間訊息（order=oldest|newest，預設 oldest）
POST	https://chat.wusper.com/api/v1/private/messages	送訊／HTML／流式 · {"body"|"html"}；加 stream:true 開流式

② 代管（type: delegate，金鑰 wc_…）

方法	完整 URL	說明
GET	https://chat.wusper.com/api/v1/friends	列出好友
GET	https://chat.wusper.com/api/v1/messages?with=<userId>&order=newest	讀取與好友的 DM（需 ACL；可 order）
POST	https://chat.wusper.com/api/v1/messages	代帳號送 DM／HTML／流式 · {"to","body"|"html"}；stream:true 開流式

③ Bot（type: bot，金鑰 wc_…；分享碼 wbot_… 不是 Bearer）

方法	完整 URL	說明
GET	https://chat.wusper.com/api/v1/bot/me	Bot 資料
GET	https://chat.wusper.com/api/v1/dm/peers	可私訊的對象
GET	https://chat.wusper.com/api/v1/dm/messages?with=<userId>&order=newest	讀取與 peer 的 DM（可 order）
POST	https://chat.wusper.com/api/v1/dm/messages	Bot 送 DM／HTML／流式 · {"to","body"|"html"}；stream:true 開流式
GET	https://chat.wusper.com/api/v1/threads	三人串列表
GET	https://chat.wusper.com/api/v1/threads/<threadId>/messages?order=newest	讀取串訊息（可 order）
POST	https://chat.wusper.com/api/v1/threads/<threadId>/messages	送串／HTML／流式 · {"body"|"html"}；stream:true 開流式

相關靜態資源：

• 本頁：https://chat.wusper.com/api-docs
• OpenAPI：https://chat.wusper.com/docs/openapi-v1.yaml
• Markdown：https://chat.wusper.com/docs/api-v1.md
• 套件 zip：https://chat.wusper.com/api-packages/wusper-chat-api-packages.zip

驗證（Auth）

三種 API 金鑰的秘密字串都以 wc_ 開頭。請求時放在 Authorization：

Authorization: Bearer wc_YOUR_SECRET
Content-Type: application/json
Accept: application/json

• 金鑰在網站 設置 → API 建立；建立／重新產生時只顯示一次。
• Bot 分享碼形如 wbot_…，只用於在 UI 把 Bot 加成好友／認領，不能當 Bearer。
• 訊息本文上限約 4000 字元（欄位 body；私人房間亦接受別名 text）。
• HTML 組件：傳送 {"html":"<button id=ok>OK</button>"}（或 format:"html"）。聊天內以隔離組件顯示；使用者點按鈕會 webhook message.interaction 回你的 API（含 message_id、element.id/label）。亦可 GET /api/v1/interactions 輪詢。HTML 上限 48KB，伺服器會消毒。預設 interact:true（點按鈕回呼）；設 interact:false（或 report_actions:false）關閉回報。
• 流式傳輸：在一般送訊 POST 加 "stream": true（缺省／false＝一次送完）。之後 POST …/messages/:id/chunks → …/complete。…/messages/stream 為別名。流式時 HTML 照常接受並顯示，但按鈕互動不適用（回傳 warning: "html_components_unavailable_while_streaming"，interact 強制 false）。

Authorization: Bearer wc_YOUR_SECRET
Content-Type: application/json
Accept: application/json

Authorization: Bearer wc_YOUR_SECRET
Content-Type: application/json
Accept: application/json

如何建立三種金鑰

1. 登入 https://chat.wusper.com → 個人中心／設置 → API。
2. 按 建立 API，選類型：
   • private 私人對話 — 綁定一個私人房間，之後所有讀寫都打該房間。
   • delegate 代管 — 以你的帳號身分讀好友、代發 DM；每個好友必須在管理頁開啟 ACL。
   • bot Bot — 獨立 Bot 身分；可用邀請／wbot_ 分享碼加人；可設 Webhook、三人串。
3. 複製顯示的 wc_… 秘密；關掉後無法再看（只能重新產生）。

用途：把一個房間當「頻道／inbox」，用程式讀寫。金鑰建立時選定房間；之後路徑固定，無需再帶 room id。

收訊

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  'https://chat.wusper.com/api/v1/private/messages?limit=50'

送訊

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"body":"hello from private API"}' \
  https://chat.wusper.com/api/v1/private/messages

送 HTML 組件（可點按鈕 → 回呼你的 Webhook）

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"html":"Confirm"}' \
  https://chat.wusper.com/api/v1/private/messages

JS SDK

import { WusperChatClient } from '@wusper/chat-sdk';
const client = new WusperChatClient({ apiKey: process.env.WUSPER_API_KEY });
console.log(await client.me());
console.log(await client.listPrivateMessages(50));
await client.sendPrivateMessage('hello from JS');

Python SDK

from wusper_chat import WusperChatClient
import os
client = WusperChatClient(os.environ["WUSPER_API_KEY"])
print(client.me())
print(client.list_private_messages(50))
client.send_private_message("hello from Python")

可選：在金鑰管理頁設定 webhook_url，房間有新訊息時伺服器會 POST（見 Webhooks）。

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  'https://chat.wusper.com/api/v1/private/messages?limit=50'

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"body":"hello from private API"}' \
  https://chat.wusper.com/api/v1/private/messages

// JS
await client.listPrivateMessages(50);
await client.sendPrivateMessage('hello');

# Python
client.list_private_messages(50)
client.send_private_message("hello")

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  'https://chat.wusper.com/api/v1/private/messages?limit=50'

curl -sS -X POST -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"body":"hello from private API"}' \
  https://chat.wusper.com/api/v1/private/messages

await client.listPrivateMessages(50);
await client.sendPrivateMessage('hello from JS');
# Python: list_private_messages / send_private_message

用途：自動化你自己的帳號（客服腳本、橋接等）。每個要操作的好友必須在 設置 → API → 管理該金鑰 開啟對應 ACL，否則讀寫會被拒。

列好友

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/friends

收／送 DM

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  "https://chat.wusper.com/api/v1/messages?with=$FRIEND_ID&limit=50"

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"to\":\"$FRIEND_ID\",\"body\":\"hello via delegate\"}" \
  https://chat.wusper.com/api/v1/messages

JS / Python

const friends = await client.listFriends();
await client.listDelegateMessages(friendId, 50);
await client.sendDelegateMessage(friendId, 'hello via delegate');

# Python
client.list_friends()
client.list_delegate_messages(friend_id, 50)
client.send_delegate_message(friend_id, "hello via delegate")

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/friends
curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  "https://chat.wusper.com/api/v1/messages?with=$FRIEND_ID"
curl -sS -X POST -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"to\":\"$FRIEND_ID\",\"body\":\"hello via delegate\"}" \
  https://chat.wusper.com/api/v1/messages

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/friends
# GET/POST https://chat.wusper.com/api/v1/messages
await client.sendDelegateMessage(friendId, 'hello');

用途：對外提供 Bot。Bearer 仍是 wc_…。分享碼 wbot_… 給別人在 App 內認領／加好友用。Peer 需擁有者邀請或分享碼認領後，才能用 DM 路徑互通。

身分與 peers

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/bot/me

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/dm/peers

Bot DM 收／送

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  "https://chat.wusper.com/api/v1/dm/messages?with=$PEER_ID&limit=50"

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d "{\"to\":\"$PEER_ID\",\"body\":\"hi from bot\"}" \
  https://chat.wusper.com/api/v1/dm/messages

三人串（owner + friend + bot）

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  https://chat.wusper.com/api/v1/threads

curl -sS -H "Authorization: Bearer $WUSPER_API_KEY" \
  "https://chat.wusper.com/api/v1/threads/$THREAD_ID/messages?limit=50"

curl -sS -X POST \
  -H "Authorization: Bearer $WUSPER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"body":"hello thread"}' \
  "https://chat.wusper.com/api/v1/threads/$THREAD_ID/messages"

JS / Python

await client.botMe();
const { peers } = await client.listDmPeers();
await client.sendDm(peers[0].id, 'hi');
const { threads } = await client.listThreads();
await client.sendThreadMessage(threads[0].id, 'hello thread');

# Python
client.bot_me(); client.list_dm_peers(); client.send_dm(peer_id, "hi")
client.list_threads(); client.send_thread_message(thread_id, "hello thread")

https://chat.wusper.com/api/v1/bot/me
https://chat.wusper.com/api/v1/dm/peers
https://chat.wusper.com/api/v1/dm/messages
https://chat.wusper.com/api/v1/threads
https://chat.wusper.com/api/v1/threads/<threadId>/messages

GET  https://chat.wusper.com/api/v1/bot/me
GET  https://chat.wusper.com/api/v1/dm/peers
GET|POST https://chat.wusper.com/api/v1/dm/messages
GET  https://chat.wusper.com/api/v1/threads
GET|POST https://chat.wusper.com/api/v1/threads/<threadId>/messages

Realtime：WebSocket 即時進線

認證

• Header：Authorization: Bearer wc_…
• 或 Query：?access_token=wc_…（瀏覽器／簡易客戶端）

範圍

金鑰	會推什麼
private	綁定私人房 message.created（尊重 @mention；不含自己送出的那把 key）
delegate	擁有者參與且 ACL 開啟的 DM（同 key 自己 API 送出的不回聲）
bot	進線 Bot DM、進線三人串（＋若綁私人房）；Bot 自己送的不回聲

另推 message.interaction 給送出 HTML 組件的那把 key。

連線 hello

{ "type": "hello", "key_id": "…", "key_type": "bot", "ts": 0 }

事件示例

{
  "type": "message.created",
  "channel": "dm",
  "key_id": "…",
  "key_type": "bot",
  "peer_user_id": "…",
  "message": { "id": "…", "body": "hi", "created_at": 0 }
}

channel：private_room｜dm｜thread。詳見 api-v1.md。

GET 訊息排序

所有讀訊息 GET 支援 order=oldest|newest（或 sort=asc|desc）。預設 oldest：最舊的 limit 筆、時間升序。newest：最新 limit 筆、時間降序。limit 預設 100、上限 200。

Webhooks

私人對話金鑰與 Bot 可設 webhook_url（設置 → API → 管理）。有新訊息時，伺服器 POST JSON 到你的 URL。低延遲進線請優先用上方 Realtime WebSocket。

請求頭

• Content-Type: application/json
• User-Agent: WusperChat-Webhook/1.0
• X-Wusper-Event — 例如 message.created
• X-Wusper-Delivery — 投遞 ID
• X-Wusper-Timestamp — Unix 秒
• X-Wusper-Signature: sha256=<hmac_hex> — 若有 webhook secret：對原始 body 做 HMAC-SHA256

驗簽（Node 示意）

import crypto from 'node:crypto';
function ok(rawBody, secret, header) {
  const expect = 'sha256=' + crypto.createHmac('sha256', secret)
    .update(rawBody, 'utf8').digest('hex');
  return header === expect;
}

失敗會重試一次；設置頁可看投遞紀錄並重放。請回 2xx。

安裝 SDK／套件

# JS / npm
npm install https://chat.wusper.com/api-packages/wusper-chat-sdk.tgz

# Python
pip install https://chat.wusper.com/api-packages/wusper_chat-0.1.0-py3-none-any.whl

# Linux .deb
curl -fsSL -O https://chat.wusper.com/api-packages/wusper-chat-sdk_0.1.0_all.deb
sudo apt install ./wusper-chat-sdk_0.1.0_all.deb

# 一包 zip（設置 → API → API package 下載）
# https://chat.wusper.com/api-packages/wusper-chat-api-packages.zip

預設客戶端 baseUrl 即為 https://chat.wusper.com。

npm install https://chat.wusper.com/api-packages/wusper-chat-sdk.tgz
pip install https://chat.wusper.com/api-packages/wusper_chat-0.1.0-py3-none-any.whl
curl -fsSL -O https://chat.wusper.com/api-packages/wusper-chat-sdk_0.1.0_all.deb
sudo apt install ./wusper-chat-sdk_0.1.0_all.deb

npm install https://chat.wusper.com/api-packages/wusper-chat-sdk.tgz
pip install https://chat.wusper.com/api-packages/wusper_chat-0.1.0-py3-none-any.whl
# deb + zip also under /api-packages/

限速與其它

• 每個金鑰：每分鐘 60 次請求（滑動／視窗計數）。
• 超限回傳錯誤；請退避後重試。
• 原始 Markdown：/docs/api-v1.md · OpenAPI：/docs/openapi-v1.yaml