Bot API

できること

Bot API を使うと、ご自身のウェブサイトやツールから Discord サーバーのリアルタイムな情報を読み取れます。読み取り専用なので、作ったものがサーバーやメンバーに影響することはありません。午後のうちに設定できるアイデアをご紹介します。

• ランキングウィジェットコミュニティのウェブサイトに、レベル上位10人のサバイバーを表示します。
• ギブアウェイのカウントダウン開催中のギブアウェイ、その賞品、終了時刻をホームページに載せられます。
• チケット数開いているチケットの数やチームの返信の速さを、スタッフ用ダッシュボードや「約10分で返信します」というバナーに表示できます。
• ステータスバッジゲームサーバーがオンラインかどうかと、参加人数を表示します。
• ショップの商品リスト寄付ショップの商品と価格をご自身のサイトに並べ、そのままチェックアウトへリンクできます。

ステップごとの手順: トークンを作成

トークンは、1つのウェブサイトやツールがサーバーを読み取れるようにする、長い秘密のパスワードです。ダッシュボードで作成します。

1. 01

   Bot API ページを開く

   dayzhub.net にログインし、ダッシュボードを開いてサーバーを選び、サイドメニューの管理にある Bot API を選びます。表示されるのはサーバー管理の権限を持つ人だけです。チームアクセスのメンバーには表示されません。

2. 02

   名前を付ける

   用途が分かる短い名前を入力します。例: 「ウェブサイトのランキング」。ウェブサイトやツールごとに1つのトークンを使ってください。

3. 03

   読み取れる内容を選ぶ

   ギブアウェイやレベルランキングなど、必要なデータのボックスにチェックを入れます。チェックは少ないほど安全です。トークンは後からいつでも追加で作れます。

4. 04

   許可するウェブサイト(必要な場合のみ)

   訪問者のブラウザー上のウェブページが API を直接呼び出す場合を除き、空のままにしてください。その場合は、サイトのアドレスを https://yoursite.com のように、末尾にパスを付けずに正確に入力します。

5. 05

   トークンを作成を押してコピー

   dhba_ で始まるトークンがボックスに表示されます。コピーを押して、すぐに安全な場所に貼り付けてください。表示されるのは一度だけです。紛失した場合は、新しく作成します。

6. 06

   秘密にしてください

   トークンはパスワードと同じように扱ってください。Discord に投稿したり、公開の GitHub プロジェクトに入れたり、訪問者が読めるウェブページに貼り付けたりしないでください。ご自身のサーバーかパスワード管理ツールに保管します。

最初のリクエスト

トークンが動作するか確認しましょう。必要なものは2つです。先ほどコピーしたトークンと、サーバー 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まで可能で、1つのインターネットアドレスからは毎分300までです。超えると、待つ秒数を示す Retry-After ヘッダー付きで 429 が返ります。
• やさしいポーリング応答には ETag が含まれます。これを If-None-Match ヘッダーで送り返すと、変更がない場合は全データの代わりに小さな 304 の応答が返ります。30~60秒ごとの確認で十分で、ほとんどのウィジェットはもっと少なくて大丈夫です。
• 共有されないものチケットのトランスクリプトとメッセージ、申請とその回答、支払いと注文、メールアドレス、名前とアバター、ギブアウェイの参加者は共有されません。取得できるのは件数と、Discord 上で人物がすでに公開されている機能(ギブアウェイの主催者やレベルランキングなど)の数字の Discord ID だけです。
• オプトアウトしたメンバー/privacy optout を使った人は、常に匿名(id が null)で表示されます。順位や数値は引き続き集計されるため、合計は合います。

トラブルシューティング

トークンの失効と入れ替え

トークンを誤って共有した、公開の場に投稿した、またはトークンを知っている人がチームを離れた場合は、すぐに行ってください。

1. 01

   先に新しいトークンを作成

   Bot API ページで同じ設定の代わりのトークンを作成し、コピーします。

2. 02

   ウェブサイトやツールを切り替える

   古いトークンを使っていた場所すべてに新しいトークンを入れ、すべて正常に動作するか確認します。

3. 03

   古いトークンを失効

   トークンの一覧で、古いトークンの失効を押して確定します。直ちに使えなくなり、まだ使っているものは 401 を受け取ります。作成と失効はサーバーの監査ログに記録されますが、トークン自体は記録されません。

よくある質問