機器人 API

你可以做什麼

機器人 API 讓你自己的網站或工具讀取 Discord 伺服器的即時資料。它只能讀取。你建置的任何東西都無法變更伺服器或影響成員。以下是一些人們一個下午就能做好的點子。

• 排行榜小工具在你的社群網站上展示等級前 10 名的倖存者。
• 抽獎倒數計時把正在進行的抽獎、獎品和結束時間放在你的首頁。
• 客服單數量顯示有多少客服單處於開啟狀態以及團隊的回覆速度，可用於管理員儀表板，或「我們大約 10 分鐘內回覆」的橫幅。
• 狀態徽章顯示你的遊戲伺服器是否在線以及有多少玩家。
• 商店商品清單在你自己的網站上列出贊助商店的商品和價格，並直接連結到結帳頁面。

逐步操作：建立你的權杖

權杖是一長串祕密密碼，讓一個網站或工具可以讀取你的伺服器。你在控制面板中建立它。

1. 01

   開啟機器人 API 頁面

   登入 dayzhub.net，開啟控制面板，選擇你的伺服器，在側邊選單的「管理」區塊點擊機器人 API。只有擁有「管理伺服器」權限的人才看得到。團隊存取成員看不到。

2. 02

   幫它取個名字

   輸入一個簡短的名稱，說明它的用途，例如「網站排行榜」。每個網站或工具使用一個權杖。

3. 03

   選擇它可以讀取的內容

   勾選你需要的資料，例如抽獎或等級排行榜。勾選越少越安全。之後隨時可以再建立另一個權杖。

4. 04

   允許的網站（僅在需要時）

   保持空白，除非訪客瀏覽器中的網頁要直接呼叫 API。那種情況下請準確填寫你的網站位址，例如 https://yoursite.com，結尾不含路徑。

5. 05

   點擊「建立權杖」並複製

   會出現一個顯示你的權杖的方框，權杖以 dhba_ 開頭。點擊「複製」，並立即貼到安全的地方。它只顯示一次。如果遺失，請建立一個新的。

6. 06

   請保密

   把權杖當作密碼對待。不要在 Discord 中發布，不要放進公開的 GitHub 專案，也不要貼到訪客看得到的網頁裡。請把它保存在你自己的伺服器或密碼管理員中。

你的第一個請求

我們來檢查你的權杖是否有效。你需要兩樣東西：剛複製的權杖，以及你的伺服器 ID（在 Discord 設定中開啟開發者模式，然後右鍵點擊你的伺服器並選擇「複製伺服器 ID」）。下面的第一個呼叫只需要權杖。

在每個範例中，把 dhba_YOUR_TOKEN 替換為你真實的權杖。每個範例都在名為 Authorization 的標頭中傳送權杖。把它放在網址裡是行不通的。

Windows PowerShell (use curl.exe with the .exe, plain curl means something else in PowerShell)

curl.exe -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

curl (macOS, Linux and most hosting)

curl -H "Authorization: Bearer dhba_YOUR_TOKEN" https://dayzhub.net/api/v1/bot/me

JavaScript on your own server (Node 18 or newer). Keep the token in an environment variable.

const res = await fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/giveaways?status=active", {
  headers: { Authorization: "Bearer " + process.env.DAYZHUB_BOT_API_TOKEN }
});
const { ok, data } = await res.json();
console.log(data);

JavaScript in a visitor's browser (needs the Allowed website setting on the token, and shows the token to everyone, so use a token with the fewest boxes ticked)

fetch("https://dayzhub.net/api/v1/bot/guilds/YOUR_SERVER_ID/leaderboard/levels?limit=10", {
  headers: { Authorization: "Bearer dhba_YOUR_TOKEN" }
}).then(r => r.json()).then(j => console.log(j.data));

回傳的內容

每個回應都是 JSON。成功的回應包含 "ok": true 和你的資料。清單帶有 "page" 部分：當 "hasMore" 為 true 時，把 "nextCursor" 的值作為 ?cursor= 傳回即可取得下一頁。日期使用 UTC。

GET /me: who the token belongs to

{
  "ok": true,
  "data": {
    "guildId": "123456789012345678",
    "name": "Website leaderboard",
    "prefix": "dhba_aB3dE",
    "scopes": ["leveling:read", "giveaways:read"],
    "allowedOrigin": null,
    "rateLimitPerMin": 60,
    "createdAt": "2026-10-01T12:00:00.000Z",
    "plan": "premium1",
    "limits": { "tokens": 2, "perMinute": 60 },
    "tokensUsed": 1
  }
}

GET /guilds/ID/leaderboard/levels?limit=2

{
  "ok": true,
  "data": [
    { "rank": 1, "member": { "id": "111111111111111111", "anonymous": false }, "xp": 18450, "level": 27 },
    { "rank": 2, "member": { "id": null, "anonymous": true }, "xp": 17020, "level": 26 }
  ],
  "page": { "limit": 2, "hasMore": true, "nextCursor": "eyJpZCI6IjY..." }
}

GET /guilds/ID/giveaways?status=active

{
  "ok": true,
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60718",
    "prize": "Premium VIP for 30 days",
    "status": "active",
    "type": "reaction",
    "winnerCount": 1,
    "entryCount": 86,
    "endsAt": "2026-10-08T18:00:00.000Z",
    "requirements": { "role": false, "verified": true, "minInvites": 0 },
    "host": { "id": "111111111111111111", "anonymous": false },
    "winners": []
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/tickets/summary

{
  "ok": true,
  "data": {
    "open": 4,
    "closed": 212,
    "total": 216,
    "last30Days": { "created": 38, "closed": 41, "averageRating": 4.7, "ratingCount": 29, "averageFirstResponseMinutes": 9.5 },
    "byCategory": [ { "category": "Support", "open": 3, "closed": 150 } ]
  }
}

GET /guilds/ID/shop/products

{
  "ok": true,
  "shop": { "name": "Survivor HQ Shop", "description": "Support the server", "slug": "survivor-hq", "url": "https://dayzhub.net/shop/survivor-hq" },
  "data": [{
    "id": "6650f0c2a1b2c3d4e5f60999", "name": "VIP Role", "slug": "vip-role", "description": "Priority queue and a gold name",
    "price": 9.99, "compareAtPrice": null, "currency": "EUR", "type": "subscription", "interval": "monthly",
    "thumbnailUrl": null, "featured": true, "inStock": true, "url": "https://dayzhub.net/shop/survivor-hq/vip-role"
  }],
  "page": { "limit": 25, "hasMore": false, "nextCursor": null }
}

GET /guilds/ID/server-status

{
  "ok": true,
  "data": {
    "listed": true,
    "servers": [{ "name": "Survivor HQ", "slug": "survivor-hq", "url": "https://dayzhub.net/s/survivor-hq", "online": true, "players": 42, "maxPlayers": 60, "address": "game.yourserver.gg:2302", "lastChangeAt": "2026-10-01T09:30:00.000Z" }]
  }
}

When something is wrong, for example a mixed-up server ID (HTTP 403)

{ "ok": false, "error": "guild_mismatch", "code": "guild_mismatch", "message": "This token belongs to another server", "requestId": "3f2b8c1e-5a7d-4e0b-9c64-1d2e3f4a5b6c" }

完整的端點清單和每個欄位都在機器可讀的描述中：/api/v1/bot/openapi.json。 每個回應都帶有 X-Request-Id 標頭，錯誤回應中會以 requestId 重複它。聯絡支援時請提供它。

限制、方案和隱私

• 唯讀沒有任何會變更內容的按鈕。只回應 GET 請求。
• 方案你的伺服器需要付費方案或有效的免費試用。抽獎資料需要 Premium 2。商店清單需要真正的付費權限，因為免費試用不包含贊助商店。
• 你可以擁有多少個權杖Premium 1 包含 2 個有效權杖，Premium 2 包含 5 個，Premium 3 包含 10 個。免費試用或受贊助的伺服器視為 Premium 1。撤銷不再使用的權杖即可騰出名額。如果方案降級，你已有的權杖仍可繼續使用，只是在降到上限以下之前不能建立新權杖。
• 速度限制每個權杖每分鐘可發出的請求數：Premium 1 為 60，Premium 2 為 120，Premium 3 為 300；同一個網路位址每分鐘 300。超出後會回傳 429，並帶有告訴你需等待多少秒的 Retry-After 標頭。
• 友善地輪詢回應中包含 ETag。把它放在 If-None-Match 標頭中傳回，如果沒有變更，你會收到一個很小的 304 回應，而不是完整資料。每 30 到 60 秒請求一次就足夠了，大多數小工具可以更不頻繁。
• 絕不分享的內容客服單的紀錄和訊息、申請及其回答、付款和訂單、電子郵件地址、名稱和頭像，以及參與抽獎的人。你只會得到數量，外加數字形式的 Discord ID，且僅限該功能本來就在 Discord 中公開展示人員的地方，例如抽獎主辦人或等級排行榜。
• 選擇退出的成員任何使用過 /privacy optout 的人一律顯示為匿名（id 為 null）。他們的排名和數據仍會計入，因此總數是對得上的。

疑難排解

撤銷和更換權杖

如果權杖被誤分享、被公開發布，或者知道它的人已離開你的團隊，請立即這樣做。

1. 01

   先建立新權杖

   在機器人 API 頁面建立一個設定相同的替代權杖，並複製它。

2. 02

   切換你的網站或工具

   把新權杖放到所有使用舊權杖的地方，並檢查一切仍然正常。

3. 03

   撤銷舊權杖

   在你的權杖清單中，點擊舊權杖的「撤銷」並確認。它會立即失效，仍在使用它的任何東西都會收到 401。建立和撤銷操作會記錄在你伺服器的稽核日誌中，但權杖本身絕不會被記錄。

常見問題