REST API v1 · 開發者 · API 參考

抽獎 API 參考

BotGG REST API v1 的所有 6 個 抽獎 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。

開發者文件
本頁目錄

端點

路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。

抽獎 端點
端點範圍說明
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

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

List giveaways

GET/guilds/{guildId}/giveaways

範圍: giveaways:read

status: active, scheduled, ended, cancelled or open (= scheduled + active). Running ones by end time, others newest first.

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
status查詢字串string否其中之一 scheduled, active, ended, cancelled, open
page查詢字串integer否1–10,000 · 預設值 1
limit查詢字串integer否1–100 · 預設值 25

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].statusstring是其中之一 scheduled, active, ended, cancelled
items[].prizestring是
items[].descriptionstring | null是
items[].channelIdstring是
items[].messageUrlstring | null是null until the bot posted it
items[].winnersCountinteger是
items[].startsAtstring是
items[].endsAtstring是
items[].endedAtstring | null是
items[].entrantsinteger是
items[].entriesinteger是Tickets incl. bonus entries
items[].winnerIdsarray of string是
items[].hostIdstring是
items[].requirementsobject是
items[].pingRoleIdstring | null是
items[].dmWinnersboolean是
items[].createdAtstring是
totalinteger是
pageinteger是
nextPageinteger | null是
回應 · 200
{
  "items": [
    {
      "id": 98765,
      "status": "scheduled",
      "prize": "Nitro",
      "description": "example",
      "channelId": "234567890123456789",
      "messageUrl": "https://example.com",
      "winnersCount": 10,
      "startsAt": "2026-10-07T12:00:00.000Z",
      "endsAt": "2026-10-07T12:00:00.000Z",
      "endedAt": "2026-10-07T12:00:00.000Z",
      "entrants": 42,
      "entries": 10,
      "winnerIds": [
        "234567890123456789"
      ],
      "hostId": "234567890123456789",
      "requirements": {},
      "pingRoleId": "234567890123456789",
      "dmWinners": true,
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "total": 10,
  "page": 10,
  "nextPage": 10
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways?page=1&limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways?page=1&limit=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "page": 1,
        "limit": 25,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

Start a giveaway

POST/guilds/{guildId}/giveaways

範圍: giveaways:writeIdempotency-Key

Saved as scheduled; the bot posts it in the channel within ~10 s (or at startsAt). Same rules as the console editor. Look and DM setting default to the server’s Giveaways settings.

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
channelIdstring是Discord ID(字串)
prizestring是1–200 個字元
descriptionstring | null否最多 1,000 個字元
winnersinteger否Default 1
1–50
startsAtstring | null否ISO 8601; omitted / null = start now
ISO 8601 日期時間(UTC)
endsAtstring否ISO 8601; or send durationSeconds
ISO 8601 日期時間(UTC)
durationSecondsinteger否From the start; or send endsAt
60–5,184,000
requirementsobject否Entry cost, rules (AND/OR requirement tree), boost (bonus entries), recheck; the v1 fields (roles, ages, level, bonusRoles) still work
requirements.roleIdsarray of string否最多 20 個項目 · 預設值 []
requirements.roleModestring否其中之一 any, all · 預設值 "any"
requirements.blockedRoleIdsarray of string否最多 20 個項目 · 預設值 []
requirements.minAccountAgeDaysinteger否0–3,650 · 預設值 0
requirements.minMemberDaysinteger否0–3,650 · 預設值 0
requirements.minLevelinteger否0–1,000 · 預設值 0
requirements.entryCostinteger否0–1,000,000,000 · 預設值 0
requirements.bonusRolesarray of object否最多 10 個項目 · 預設值 []
requirements.bonusRoles[].roleIdstring是Discord ID(字串)
requirements.bonusRoles[].entriesinteger是2–10
requirements.rulesobject | null否預設值 null
requirements.rules.opstring否其中之一 and, or · 預設值 "and"
requirements.rules.itemsarray of object | object | object | object | object | object | object | object | object | object否最多 10 個項目 · 預設值 []
requirements.boostobject | null否預設值 null
requirements.boost.stackstring否其中之一 sum, best · 預設值 "sum"
requirements.boost.capinteger否1–100 · 預設值 10
requirements.boost.rulesarray of object | object | object否最多 10 個項目 · 預設值 []
requirements.recheckboolean否預設值 true
embedobject否Default: the server’s Giveaways look
embed.colorstring否預設值 "#D94CFF"
embed.endedColorstring否預設值 "#4E5058"
embed.emojistring否1–64 個字元 · 預設值 "🎉"
embed.imageUrlstring | null否最多 500 個字元 · 預設值 null
embed.thumbnailUrlstring | null否最多 500 個字元 · 預設值 null
pingRoleIdstring | null否Discord ID(字串)
dmWinnersboolean否Default: the server setting
hostIdstring | null否Shown as the host; default: the API key’s creator
Discord ID(字串)

回應

回應欄位 · 201
欄位類型必填說明
idinteger是
statusstring是其中之一 scheduled, active, ended, cancelled
prizestring是
descriptionstring | null是
channelIdstring是
messageUrlstring | null是null until the bot posted it
winnersCountinteger是
startsAtstring是
endsAtstring是
endedAtstring | null是
entrantsinteger是
entriesinteger是Tickets incl. bonus entries
winnerIdsarray of string是
hostIdstring是
requirementsobject是
pingRoleIdstring | null是
dmWinnersboolean是
createdAtstring是
回應 · 201
{
  "id": 98765,
  "status": "scheduled",
  "prize": "Nitro",
  "description": "example",
  "channelId": "234567890123456789",
  "messageUrl": "https://example.com",
  "winnersCount": 10,
  "startsAt": "2026-10-07T12:00:00.000Z",
  "endsAt": "2026-10-07T12:00:00.000Z",
  "endedAt": "2026-10-07T12:00:00.000Z",
  "entrants": 42,
  "entries": 10,
  "winnerIds": [
    "234567890123456789"
  ],
  "hostId": "234567890123456789",
  "requirements": {},
  "pingRoleId": "234567890123456789",
  "dmWinners": true,
  "createdAt": "2026-10-07T12:00:00.000Z"
}

範例

curl
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"channelId":"234567890123456789","prize":"Nitro","description":"example","winners":1,"startsAt":"2026-10-07T12:00:00.000Z","endsAt":"2026-10-07T12:00:00.000Z","durationSeconds":3600,"requirements":{"roleIds":[],"roleMode":"any","blockedRoleIds":[],"minAccountAgeDays":0,"minMemberDays":0,"minLevel":0,"entryCost":0,"bonusRoles":[],"rules":{"op":"and","items":[]},"boost":{"stack":"sum","cap":10,"rules":[]},"recheck":true},"embed":{"color":"#D94CFF","endedColor":"#4E5058","emoji":"🎉","imageUrl":"https://example.com","thumbnailUrl":"https://example.com"},"pingRoleId":"234567890123456789","dmWinners":true,"hostId":"234567890123456789"}'
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    channelId: '234567890123456789',
    prize: 'Nitro',
    description: 'example',
    winners: 1,
    startsAt: '2026-10-07T12:00:00.000Z',
    endsAt: '2026-10-07T12:00:00.000Z',
    durationSeconds: 3600,
    requirements: {
      roleIds: [],
      roleMode: 'any',
      blockedRoleIds: [],
      minAccountAgeDays: 0,
      minMemberDays: 0,
      minLevel: 0,
      entryCost: 0,
      bonusRoles: [],
      rules: {
        op: 'and',
        items: [],
      },
      boost: {
        stack: 'sum',
        cap: 10,
        rules: [],
      },
      recheck: true,
    },
    embed: {
      color: '#D94CFF',
      endedColor: '#4E5058',
      emoji: '🎉',
      imageUrl: 'https://example.com',
      thumbnailUrl: 'https://example.com',
    },
    pingRoleId: '234567890123456789',
    dmWinners: true,
    hostId: '234567890123456789',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "channelId": "234567890123456789",
        "prize": "Nitro",
        "description": "example",
        "winners": 1,
        "startsAt": "2026-10-07T12:00:00.000Z",
        "endsAt": "2026-10-07T12:00:00.000Z",
        "durationSeconds": 3600,
        "requirements": {
            "roleIds": [],
            "roleMode": "any",
            "blockedRoleIds": [],
            "minAccountAgeDays": 0,
            "minMemberDays": 0,
            "minLevel": 0,
            "entryCost": 0,
            "bonusRoles": [],
            "rules": {
                "op": "and",
                "items": [],
            },
            "boost": {
                "stack": "sum",
                "cap": 10,
                "rules": [],
            },
            "recheck": True,
        },
        "embed": {
            "color": "#D94CFF",
            "endedColor": "#4E5058",
            "emoji": "🎉",
            "imageUrl": "https://example.com",
            "thumbnailUrl": "https://example.com",
        },
        "pingRoleId": "234567890123456789",
        "dmWinners": True,
        "hostId": "234567890123456789",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

Get a giveaway

GET/guilds/{guildId}/giveaways/{giveawayId}

範圍: giveaways:read

With entry counts, winners per draw and the latest queued actions (to follow an end / reroll).

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
giveawayId路徑string是

回應

回應欄位 · 200
欄位類型必填說明
idinteger是
statusstring是其中之一 scheduled, active, ended, cancelled
prizestring是
descriptionstring | null是
channelIdstring是
messageUrlstring | null是null until the bot posted it
winnersCountinteger是
startsAtstring是
endsAtstring是
endedAtstring | null是
entrantsinteger是
entriesinteger是Tickets incl. bonus entries
winnerIdsarray of string是
hostIdstring是
requirementsobject是
pingRoleIdstring | null是
dmWinnersboolean是
createdAtstring是
winnersarray of object是
winners[].userIdstring是
winners[].drawinteger是0 = the end draw, 1.. = rerolls
winners[].drawnAtstring是
actionsarray of object是The latest queued actions (end / reroll / …), newest first
actions[].idinteger是
actions[].actionstring是
actions[].statusstring是其中之一 pending, processing, done, failed
actions[].errorstring | null是
actions[].createdAtstring是
actions[].processedAtstring | null是
回應 · 200
{
  "id": 98765,
  "status": "scheduled",
  "prize": "Nitro",
  "description": "example",
  "channelId": "234567890123456789",
  "messageUrl": "https://example.com",
  "winnersCount": 10,
  "startsAt": "2026-10-07T12:00:00.000Z",
  "endsAt": "2026-10-07T12:00:00.000Z",
  "endedAt": "2026-10-07T12:00:00.000Z",
  "entrants": 42,
  "entries": 10,
  "winnerIds": [
    "234567890123456789"
  ],
  "hostId": "234567890123456789",
  "requirements": {},
  "pingRoleId": "234567890123456789",
  "dmWinners": true,
  "createdAt": "2026-10-07T12:00:00.000Z",
  "winners": [
    {
      "userId": "876543210987654321",
      "draw": 10,
      "drawnAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "actions": [
    {
      "id": 98765,
      "action": "example",
      "status": "pending",
      "error": "example",
      "createdAt": "2026-10-07T12:00:00.000Z",
      "processedAt": "2026-10-07T12:00:00.000Z"
    }
  ]
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

List a giveaway’s entrants

GET/guilds/{guildId}/giveaways/{giveawayId}/entries

範圍: giveaways:read

Ordered by user id. Pass after=<nextCursor> for the next page. weight = tickets (bonus roles), paid = entry cost paid.

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
giveawayId路徑string是
limit查詢字串integer否1–100 · 預設值 50
after查詢字串string否Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].userIdstring是
items[].weightinteger是
items[].paidinteger是
items[].enteredAtstring是
nextCursorstring | null是
回應 · 200
{
  "items": [
    {
      "userId": "876543210987654321",
      "weight": 10,
      "paid": 10,
      "enteredAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "nextCursor": "98700"
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/entries?limit=50" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/entries?limit=50', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/entries",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "limit": 50,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

End a giveaway now

POST/guilds/{guildId}/giveaways/{giveawayId}/end

範圍: giveaways:writeIdempotency-Key

Queued for the bot, which draws the winners and announces them within ~5 s (202). Follow it with GET …/giveaways/{giveawayId}.

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
giveawayId路徑string是
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

回應

回應欄位 · 202
欄位類型必填說明
giveawayIdinteger是
actionobject是
action.idinteger是
action.actionstring是
action.statusstring是其中之一 pending, processing, done, failed
action.errorstring | null是
action.createdAtstring是
action.processedAtstring | null是
回應 · 202
{
  "giveawayId": 98765,
  "action": {
    "id": 98765,
    "action": "example",
    "status": "pending",
    "error": "example",
    "createdAt": "2026-10-07T12:00:00.000Z",
    "processedAt": "2026-10-07T12:00:00.000Z"
  }
}

範例

curl
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/end" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/end', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/end",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

Reroll winners

POST/guilds/{guildId}/giveaways/{giveawayId}/reroll

範圍: giveaways:writeIdempotency-Key

For an ended giveaway: the bot draws count new winners (never someone who already won) within ~5 s (202).

需要在伺服器上啟用此功能: 抽獎

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
giveawayId路徑string是
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
countinteger否Default 1
1–20

回應

回應欄位 · 202
欄位類型必填說明
giveawayIdinteger是
actionobject是
action.idinteger是
action.actionstring是
action.statusstring是其中之一 pending, processing, done, failed
action.errorstring | null是
action.createdAtstring是
action.processedAtstring | null是
回應 · 202
{
  "giveawayId": 98765,
  "action": {
    "id": 98765,
    "action": "example",
    "status": "pending",
    "error": "example",
    "createdAt": "2026-10-07T12:00:00.000Z",
    "processedAt": "2026-10-07T12:00:00.000Z"
  }
}

範例

curl
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/reroll" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"count":12}'
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/reroll', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    count: 12,
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/giveaways/234567890123456789/reroll",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "count": 12,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

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

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