机器人 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。创建和撤销操作会记录在你服务器的审计日志中，但令牌本身绝不会被记录。

常见问题