# Giveaways

### Core Settings (Config)

Add these to your config to control permissions and behavior:

{% code expandable="true" %}

```yaml
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
```

{% endcode %}

#### 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:

  <pre><code><strong>/giveaway create
  </strong>  channel: #giveaways
    time: 1d
    winners: 1
    prize: Discord Nitro
    hostedby: @Staff
  </code></pre>
* 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
  ```

{% hint style="success" %}
💡 **Tips:**&#x20;

* 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`).
  {% endhint %}

***

#### `/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`