REST API v1 · 開發者
BotGG 開發者 API:把你的 Discord 伺服器連到任何服務
BotGG REST API 讓你自己的網站、遊戲伺服器或後端,都能讀取並修改 Discord 伺服器中的 BotGG 資料,例如發放銀行獎金、從遊戲同步經驗值、獎勵邀請,或在網站上顯示排行榜。只要在控制台建立金鑰,送出一個 HTTPS 請求就完成了。
- 基礎網址:
https://console.botgg.app/api/v1 - 透過 HTTPS 傳輸 JSON,使用
Authorization: BearerAPI 金鑰,並依資源設定權限範圍 - 每個端點都有機器可讀的 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 位數字),傳送與回傳時一律使用字串。
- 每把金鑰只屬於一個伺服器,也只能用於該伺服器,詳見驗證。
- 僅限伺服器對伺服器:來自瀏覽器的請求會被拒絕,所以金鑰不會出現在前端程式碼中。
快速開始
- 開啟控制台,選擇你的伺服器,再前往側邊欄的 API(你需要擁有「管理伺服器」權限)。
- 建立金鑰:為它取個名稱(例如「網站」),選擇權限範圍與選用的到期時間。請立即複製金鑰,它只會顯示一次。
- 把它當作機密資訊存放在你的伺服器上,例如放在
BOTGG_API_KEY環境變數中。 - 送出你的第一個請求,這裡以讀取成員的銀行餘額為例(權限範圍
bank:read)。
curl -s https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321 \
-H "Authorization: Bearer $BOTGG_API_KEY"{
"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 的端點,需要能對成員進行操作或會揭露管理資料的權限範圍。
同樣的描述也提供 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 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 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"])