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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.drakodevelopment.net/economy-and-engagement/giveaways.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.