Giveaways

The giveaway system makes it easy to host and manage Discord giveaways. It supports advanced features like role requirements, entry restrictions, customizable embeds, and automatic winner selection.

Core Settings (Config)

Add these to your config to control permissions and behavior:

Giveaways:
  AllowRoles: ["ROLE_ID", "ROLE_ID"]     # Who can run /giveaway
  GiveawayStatusCheck: 7500              # How often to check end-times (ms)
  DirectMessageWinners: true             # DM winners on win

  Embed:
    ActiveGiveaway:
      EmbedColor: "#1769FF"
      EmbedImage: "https://i.imgur.com/yw6UcuW.jpg"
      EmbedFooterIcon: "https://i.imgur.com/13VlA3w.png"
      EmbedThumbnail: "https://i.imgur.com/ewT6bOT.png"
      ShowTitle: true
      ShowThumbnail: true
      ShowHostedBy: true
      ShowEndsIn: true
      ShowEntries: true
      ShowWhitelistRoles: true
      ShowBlacklistRoles: true
      ShowMinimumServerJoinDate: true
      ShowMinimumAccountAge: true
      ShowMinimumMessages: true
      ShowImage: true
      ShowFooter: true
      Button:
        JoinButton:
          ButtonStyle: "Primary"
          ButtonEmoji: "🎉"
          ButtonText: "Enter"
        CheckPercent:
          ButtonStyle: "Secondary"
          ButtonEmoji: "📈"
          ButtonText: "Odds"
        ShowEntries:
          ButtonStyle: "Secondary"
          ButtonEmoji: "👥"
          ButtonText: "Entries"
        ShowEntrantsList:
          ButtonStyle: "Secondary"
          ButtonEmoji: "👥"
          ButtonText: "Show Entrants"
          Embed:
            Title: "🎉 Giveaway Entrants - {prize}"
            Description:
              - "{entrantsList}"
            Footer:
              Text: "Total Entrants: {totalEntrants} • Page {currentPage}/{totalPages}"
              Icon: "{footerIcon}"
            Color: "#1769FF"
            Thumbnail: "https://i.imgur.com/ewT6bOT.png"

    EndedGiveaway:
      EmbedColor: "#1769FF"
      EmbedImage: "https://i.imgur.com/7TQDDAy.png"
      EmbedFooterIcon: "https://i.imgur.com/13VlA3w.png"
      EmbedThumbnail: "https://i.imgur.com/ewT6bOT.png"
      ShowTitle: true
      ShowThumbnail: true
      ShowImage: true
      ShowWinnersField: true
      ShowEntriesField: true
      ShowFooter: true

What these do

• AllowRoles → Only these roles can use /giveaway (all subcommands). Replace "ROLE_ID" with real IDs.

• GiveawayStatusCheck → Interval (ms) the bot uses to see if a giveaway ended.

  • Default: 7500 (7.5s)

  • Small servers: 5000–10000 (5–10s)

  • Large servers: 10000–15000 (10–15s)

• DirectMessageWinners → true is recommended so winners get a DM.

---

Active Giveaway Embed Options

All Show* flags are true/false and control what the running giveaway shows:

• Title, Thumbnail, Hosted By, Ends In (countdown), Entries

• Whitelist/Blacklist roles

• Minimum Server Join Date / Account Age / Messages

• Image, Footer

Buttons & Styles

• Primary (Blue), Secondary (Gray), Success (Green), Danger (Red)

• Built-ins:

  • Enter (JoinButton)

  • Odds (CheckPercent)

  • Entries (ShowEntries)

  • Show Entrants (ShowEntrantsList, opens a paginated embed)

---

Ended Giveaway Embed

After a giveaway ends, the EndedGiveaway embed appears. You can toggle:

• Title, Thumbnail, Image, Winners field, Entries field, Footer

---

Entrants List Placeholders

Inside the entrants list embed you can use:

• {prize} – prize name

• {entrantsList} – formatted list of entrants

• {totalEntrants} – total count

• {currentPage} / {totalPages} – pagination info

---

Commands

/giveaway create

Create a giveaway with all your options in one go.

Required options

• channel – The channel to post the giveaway in

• time – Duration (see formats below)

• winners – Number of winners

• prize – The prize name

• hostedby – Who is hosting (type @Username)

Optional restrictions

• min_server_join_date – Example: January 1 2024

• min_account_age – Example: January 1 2023

• min_invites – Integer (minimum invites to enter)

• min_messages – Integer (minimum messages to enter)

• whitelist_roles – Mention roles allowed to enter (e.g., @VIP @Boosters)

• blacklist_roles – Mention roles disallowed (e.g., @Muted)

• notify – One of:

  • Nobody → notify_nobody

  • Whitelist Roles → notify_whitelist_roles

  • Everyone → notify_everyone

• extra_entries – Give bonus entries to roles (format: @role:entries @role2:entries)

  • Example: @VIP:5 @Booster:3

Examples

• Simple daily Nitro:

  /giveaway create
    channel: #giveaways
    time: 1d
    winners: 1
    prize: Discord Nitro
    hostedby: @Staff

• With restrictions and extras:

  /giveaway create
    channel: #events
    time: 2h
    winners: 3
    prize: $25 Gift Card
    hostedby: @Admin
    min_server_join_date: January 1 2024
    min_account_age: January 1 2023
    min_messages: 100
    whitelist_roles: @Members @Boosters
    blacklist_roles: @Muted
    notify: notify_whitelist_roles
    extra_entries: @VIP:5 @Booster:3

💡 Tips:

• Date format must be like January 1 2025 (month name, day, year).

• Mentions in strings should be typed as you would in Discord (e.g., @Role, @User).

---

/giveaway end

End a running giveaway by its Giveaway ID (found in the footer of the embed).

/giveaway end giveaway_id: GW-12345

/giveaway reroll

Pick new winner(s) for a finished giveaway. Optionally specify particular users to reroll.

/giveaway reroll
  giveaway_id: GW-12345
  users: @UserOne @UserTwo   (optional)

---

⏲Duration Formats

Use these in the time field:

• m = minutes → 30m, 45m

• h = hours → 2h, 12h

• d = days → 1d, 7d

• w = weeks → 1w, 2w

• y = years → 1y