REST API v1 · 開發者

BotGG 開發者 API:把你的 Discord 伺服器連到任何服務

BotGG REST API 讓你自己的網站、遊戲伺服器或後端,都能讀取並修改 Discord 伺服器中的 BotGG 資料,例如發放銀行獎金、從遊戲同步經驗值、獎勵邀請,或在網站上顯示排行榜。只要在控制台建立金鑰,送出一個 HTTPS 請求就完成了。

  • 基礎網址:https://console.botgg.app/api/v1
  • 透過 HTTPS 傳輸 JSON,使用 Authorization: Bearer API 金鑰,並依資源設定權限範圍
  • 每個端點都有機器可讀的 OpenAPI 3.1 描述
  • 免費方案:2 把金鑰,每把金鑰每分鐘 60 次請求
開發者文件
本頁目錄

概覽

成員在 Discord 中透過 BotGG 做的事,例如餘額、等級、邀請等,你自己的程式也能存取。BotGG 的每個部分都是一種資源,各有專屬的端點與權限範圍;API 參考文件列出了全部內容。

  • 基礎網址:https://console.botgg.app/api/v1。僅支援 HTTPS。
  • 請求與回應皆為 JSON(Content-Type: application/json)。
  • ID 為 Discord snowflake(17 至 20 位數字),傳送與回傳時一律使用字串。
  • 每把金鑰只屬於一個伺服器,也只能用於該伺服器,詳見驗證。
  • 僅限伺服器對伺服器:來自瀏覽器的請求會被拒絕,所以金鑰不會出現在前端程式碼中。

快速開始

  1. 開啟控制台,選擇你的伺服器,再前往側邊欄的 API(你需要擁有「管理伺服器」權限)。
  2. 建立金鑰:為它取個名稱(例如「網站」),選擇權限範圍與選用的到期時間。請立即複製金鑰,它只會顯示一次。
  3. 把它當作機密資訊存放在你的伺服器上,例如放在 BOTGG_API_KEY 環境變數中。
  4. 送出你的第一個請求,這裡以讀取成員的銀行餘額為例(權限範圍 bank:read)。
curl
curl -s https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321 \
  -H "Authorization: Bearer $BOTGG_API_KEY"
Response · 200
{
  "userId": "876543210987654321",
  "balance": 1250,
  "currency": { "name": "Coin", "plural": "Coins", "emoji": "🪙" }
}

每種資源都需要在伺服器上啟用對應功能,否則其端點會回應 409 FEATURE_DISABLED(銀行則是 BANK_DISABLED)。所有錯誤碼都列在錯誤頁面。

依資源分類的 API 參考文件

每種資源各有一個參考頁面,由執行 API 的同一份註冊表自動產生,內容包含參數、請求與回應欄位、權限範圍、錯誤碼,以及可直接執行的 curl、JavaScript 與 Python 範例:

所有端點

所有路徑都相對於 https://console.botgg.app/api/v1。{guildId} 是你的伺服器 ID,{userId} 是成員的 Discord ID。標示為 Sensitive 的端點,需要能對成員進行操作或會揭露管理資料的權限範圍。

所有 REST API v1 端點
端點範圍說明
GET/guilds/{guildId}guild:readGet the server
GET/guilds/{guildId}/rolesguild:readList roles
GET/guilds/{guildId}/channelsguild:readList channels
GET/guilds/{guildId}/members/{userId}guild:readGet a member
GET/guilds/{guildId}/bank/members/{userId}bank:readGet a member’s balance
GET/guilds/{guildId}/bank/members/{userId}/transactionsbank:readList a member’s transactions
POST/guilds/{guildId}/bank/members/{userId}/transactionsbank:writeAdd to or remove from a member’s balance
GET/guilds/{guildId}/bank/leaderboardbank:readTop balances
GET/guilds/{guildId}/levels/members/{userId}levels:readGet a member’s level
GET/guilds/{guildId}/levels/leaderboardlevels:readXP leaderboard
POST/guilds/{guildId}/levels/members/{userId}/xp-changeslevels:writeAdd, remove or set a member’s XP
GET/guilds/{guildId}/levels/xp-changes/{changeId}levels:writeGet the status of an XP change
GET/guilds/{guildId}/invites/members/{userId}invites:readGet a member’s invites
GET/guilds/{guildId}/invites/leaderboardinvites:readInvites leaderboard
POST/guilds/{guildId}/invites/members/{userId}/bonusinvites:writeAdd or remove bonus invites
GET/guilds/{guildId}/ticketstickets:readList tickets
GET/guilds/{guildId}/tickets/{ticketNo}tickets:readGet a ticket
GET/guilds/{guildId}/tickets/{ticketNo}/transcripttickets:readGet a closed ticket’s transcript
POST/guilds/{guildId}/tickets/{ticketNo}/closetickets:writeClose a ticket
GET/guilds/{guildId}/applications/formsapplications:readList application forms
GET/guilds/{guildId}/applications/submissionsapplications:readList applications
GET/guilds/{guildId}/applications/submissions/{number}applications:readGet an application
POST/guilds/{guildId}/applications/submissions/{number}/decisionapplications:writeAccept or deny an application
GET/guilds/{guildId}/appealsappeals:readList ban appeals
GET/guilds/{guildId}/appeals/{number}appeals:readGet a ban appeal
POST/guilds/{guildId}/appeals/{number}/approveappeals:write 敏感Approve a ban appeal (unban)
POST/guilds/{guildId}/appeals/{number}/rejectappeals:write 敏感Reject a ban appeal
GET/guilds/{guildId}/moderation/casesmoderation:read 敏感List moderation cases
GET/guilds/{guildId}/moderation/cases/{number}moderation:read 敏感Get a moderation case
POST/guilds/{guildId}/moderation/users/{userId}/warnmoderation:write 敏感Warn a member
POST/guilds/{guildId}/moderation/users/{userId}/timeoutmoderation:write 敏感Time out a member
POST/guilds/{guildId}/moderation/users/{userId}/untimeoutmoderation:write 敏感Remove a member’s timeout
POST/guilds/{guildId}/moderation/users/{userId}/kickmoderation:write 敏感Kick a member
POST/guilds/{guildId}/moderation/users/{userId}/banmoderation:write 敏感Ban a user
POST/guilds/{guildId}/moderation/users/{userId}/unbanmoderation:write 敏感Unban a user
GET/guilds/{guildId}/moderation/actions/{actionId}moderation:write 敏感Get the result of a moderation action
GET/guilds/{guildId}/shop/storesshop:readList stores
GET/guilds/{guildId}/shop/itemsshop:readList items
GET/guilds/{guildId}/shop/items/{itemId}shop:readGet an item
PATCH/guilds/{guildId}/shop/items/{itemId}shop:write 敏感Restock or turn an item on/off
GET/guilds/{guildId}/shop/members/{userId}/inventoryshop:readA member’s inventory
GET/guilds/{guildId}/shop/purchasesshop:readList purchases
GET/guilds/{guildId}/shop/purchases/{purchaseId}shop:readGet a purchase
POST/guilds/{guildId}/shop/members/{userId}/purchasesshop:write 敏感Buy an item for a member
POST/guilds/{guildId}/shop/members/{userId}/grantsshop:write 敏感Give an item to a member for free
POST/guilds/{guildId}/shop/purchases/{purchaseId}/refundshop:write 敏感Refund a purchase
GET/guilds/{guildId}/giveawaysgiveaways:readList giveaways
POST/guilds/{guildId}/giveawaysgiveaways:writeStart a giveaway
GET/guilds/{guildId}/giveaways/{giveawayId}giveaways:readGet a giveaway
GET/guilds/{guildId}/giveaways/{giveawayId}/entriesgiveaways:readList a giveaway’s entrants
POST/guilds/{guildId}/giveaways/{giveawayId}/endgiveaways:writeEnd a giveaway now
POST/guilds/{guildId}/giveaways/{giveawayId}/rerollgiveaways:writeReroll winners
GET/guilds/{guildId}/flowsflows:readList flows
GET/guilds/{guildId}/flows/runs/{executionId}flows:readGet a flow run
POST/guilds/{guildId}/flows/{workflowId}/runsflows:run 敏感Run a flow

同樣的描述也提供 OpenAPI 3.1 文件,可匯入 Postman、Insomnia 或用戶端產生器。它即時提供(不需要金鑰),網址是 https://console.botgg.app/api/v1/openapi.json。

API 的運作方式

  • 驗證與 API 金鑰:金鑰格式、權限範圍、到期、撤銷與安全實務。
  • 錯誤:錯誤格式,以及每個錯誤碼與其 HTTP 狀態。
  • 速率限制:各方案每把金鑰每分鐘的請求數,以及 X-RateLimit-* 標頭。
  • 冪等重試:用 Idempotency-Key 標頭讓重送的寫入操作更安全。
  • Webhook:BotGG 傳送到你伺服器的簽章事件,並附驗證程式碼。
  • AI 助理與 MCP:在 AI 工具中使用這套 API。
  • 網站小工具:只想在網站上展示你的伺服器嗎?每個小工具也有不需金鑰的 JSON 位址(/api/public/widget/<id>.json,開放 CORS,快取 60 秒),可以放心在瀏覽器中呼叫。

完整範例

一個完整的餘額異動範例:每次異動使用一組冪等金鑰,遇到 429/503 時等待,並處理 INSUFFICIENT_FUNDS。請在你的伺服器上執行,不要在瀏覽器中執行。

Node.js · bank.mjs
// Node.js 22+ (built-in fetch). Run it on your server — never in a browser or game client.
const API = 'https://console.botgg.app/api/v1';
const KEY = process.env.BOTGG_API_KEY; // a key with the bank:write scope, kept in a secret
const GUILD_ID = '123456789012345678';

export async function changeBalance(userId, type, amount, reason) {
  // One Idempotency-Key per logical change: every retry below reuses it, so the change happens once.
  const idempotencyKey = crypto.randomUUID();

  for (let attempt = 1; attempt <= 3; attempt++) {
    const res = await fetch(`${API}/guilds/${GUILD_ID}/bank/members/${userId}/transactions`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey,
      },
      body: JSON.stringify({ type, amount, reason }),
    });
    const data = await res.json();

    if (res.ok) return data; // 201 — or the original response, replayed

    if (res.status === 429 || res.status === 503) {
      const seconds = Number(res.headers.get('Retry-After')) || attempt * 2;
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
      continue;
    }
    if (data.error === 'INSUFFICIENT_FUNDS') {
      throw new Error(`Not enough balance: the member has ${data.balance}`);
    }
    throw new Error(`${res.status} ${data.error}: ${data.message}`);
  }
  throw new Error('BotGG API is busy, try again later');
}

const tx = await changeBalance('876543210987654321', 'add', 100, 'Tournament prize');
console.log(`New balance: ${tx.balance}`);
Python · bank.py
# Python 3 + requests. Run it on your server — never ship the key to clients.
import os, time, uuid
import requests

API = "https://console.botgg.app/api/v1"
KEY = os.environ["BOTGG_API_KEY"]  # a key with the bank:write scope
GUILD_ID = "123456789012345678"

def change_balance(user_id, type_, amount, reason=None):
    idempotency_key = str(uuid.uuid4())  # one per logical change, reused on every retry
    for attempt in range(1, 4):
        res = requests.post(
            f"{API}/guilds/{GUILD_ID}/bank/members/{user_id}/transactions",
            headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": idempotency_key},
            json={"type": type_, "amount": amount, "reason": reason},
            timeout=10,
        )
        data = res.json()
        if res.ok:
            return data  # 201 — or the original response, replayed
        if res.status_code in (429, 503):
            time.sleep(int(res.headers.get("Retry-After", attempt * 2)))
            continue
        raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
    raise RuntimeError("BotGG API is busy, try again later")

print(change_balance("876543210987654321", "add", 100, "Tournament prize")["balance"])

常見問題

BotGG API 免費嗎?

免費。每個伺服器都可以免費建立 2 把 API 金鑰,每把金鑰每分鐘 60 次請求。Pro 則提升到 10 把金鑰與每分鐘 600 次請求。

我可以在瀏覽器的 JavaScript 中呼叫 API 嗎?

不行。這套 API 只接受伺服器對伺服器的請求,任何帶有 Origin 標頭的請求都會被拒絕。請從你的後端呼叫,再把結果交給網頁,這樣金鑰才能保持機密。

如何從我的遊戲或網站發放貨幣給成員?

建立具備 bank:write 權限範圍的金鑰,再送出 POST /guilds/{guildId}/bank/members/{userId}/transactions,內容為 {"type":"add","amount":100}。加上 Idempotency-Key 標頭,重試時就不會重複發放。

有 OpenAPI 規格嗎?

有。這套 API 提供由端點註冊表產生的 OpenAPI 3.1 文件,即時網址為 https://console.botgg.app/api/v1/openapi.json,每個文件頁面也提供下載。你可以把它匯入 Postman、Insomnia 或程式碼產生器。

如果我的 API 金鑰外洩了怎麼辦?

請立刻在控制台撤銷它,金鑰會馬上失效,然後再建立新的金鑰。使用金鑰進行的每筆銀行異動,都會連同金鑰名稱記錄在銀行帳本中,方便你檢視它做了什麼。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。