> ## Documentation Index
> Fetch the complete documentation index at: https://docs.celestia.rest/llms.txt
> Use this file to discover all available pages before exploring further.

# Giveaways

> Create and manage interactive giveaways with advanced entry systems

## Overview

The giveaway system allows you to host interactive giveaways in your server with features like role restrictions, entry multipliers, and automatic winner selection. Members react to enter, and winners are randomly selected when the giveaway ends.

<Info>
  Giveaways support advanced features like role-restricted entries and entry multipliers for boosters or VIP members.
</Info>

***

## Commands

<AccordionGroup>
  <Accordion title="giveaway start" icon="play">
    Start a new giveaway in the current channel.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway start <duration> <winners> <prize> [role] [entry_role:entries]
      ```

      ```bash Example theme={null}
      ~giveaway start 1d 2 Discord Nitro
      ~gw start 12h 1 $50 Gift Card @VIP
      ~gwy start 2d 3 Premium Role @Booster:3
      ~gw start 1w 5 Custom Role @VIP @Booster:2 @Supporter:5
      ```
    </CodeGroup>

    **Parameters:**

    * **duration** — How long the giveaway runs (s/m/h/d/mo/y)
    * **winners** — Number of winners to select
    * **prize** — What the winners receive
    * **\[role]** — Optional: Restrict to members with this role
    * **\[role:entries]** — Optional: Give role holders multiple entries

    **Duration Format:**

    * `s` = seconds
    * `m` = minutes
    * `h` = hours
    * `d` = days
    * `mo` = months
    * `y` = years

    **Entry Multipliers:**
    Add `@Role:number` to give that role multiple entries:

    * `@Booster:3` = Boosters get 3 entries each
    * `@VIP:5` = VIP members get 5 entries each

    **Aliases:** `gway start`, `gwy start`, `gw start`\
    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="giveaway end" icon="stop">
    End an active giveaway early and select winners.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway end <message_link>
      ```

      ```bash Example theme={null}
      ~giveaway end https://discord.com/channels/123/456/789
      ~gw end https://discord.com/channels/123/456/789
      ```
    </CodeGroup>

    **Parameters:**

    * **message\_link** — Link to the giveaway message

    **What It Does:**

    * Ends the giveaway immediately
    * Selects and announces winners
    * Removes reactions
    * Cannot be reversed

    **How to Get Message Link:**
    Right-click the giveaway message → Copy Message Link

    **Aliases:** `gway end`, `gwy end`, `gw end`\
    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="giveaway cancel" icon="xmark">
    Cancel an active giveaway without selecting winners.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway cancel <message_link>
      ```

      ```bash Example theme={null}
      ~giveaway cancel https://discord.com/channels/123/456/789
      ~gw cancel https://discord.com/channels/123/456/789
      ```
    </CodeGroup>

    **Parameters:**

    * **message\_link** — Link to the giveaway message

    **What It Does:**

    * Cancels the giveaway
    * No winners selected
    * Removes reactions
    * Deletes giveaway data

    **Aliases:** `gway cancel`, `gwy cancel`, `gw cancel`\
    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="giveaway reroll" icon="shuffle">
    Select new winners for an ended giveaway.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway reroll <message_link> [count]
      ```

      ```bash Example theme={null}
      ~giveaway reroll https://discord.com/channels/123/456/789
      ~gw reroll https://discord.com/channels/123/456/789 1
      ```
    </CodeGroup>

    **Parameters:**

    * **message\_link** — Link to the ended giveaway
    * **\[count]** — Optional: How many winners to reroll (default: all)

    **What It Does:**

    * Selects new random winners
    * Keeps original participants
    * Updates giveaway message
    * Announces new winners

    **Partial Reroll:**
    Use count to reroll only some winners:

    * `reroll link 1` = Reroll 1 winner, keep others
    * `reroll link` = Reroll all winners

    **Aliases:** `gway reroll`, `gwy reroll`, `gw reroll`\
    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="giveaway edit" icon="pen">
    Edit an active giveaway's settings.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway edit <duration/winner/prize/entries> <value> <message_link>
      ```

      ```bash Example theme={null}
      ~gw edit duration 2d https://discord.com/channels/123/456/789
      ~gw edit winner 3 https://discord.com/channels/123/456/789
      ~gw edit prize New Prize Name https://discord.com/channels/123/456/789
      ~gw edit entries @VIP:5 @Booster:2 https://discord.com/channels/123/456/789
      ```
    </CodeGroup>

    **Edit Options:**

    * **duration** — Extend or shorten time
    * **winner** / **winners** — Change winner count
    * **prize** — Update prize description
    * **entries** — Set entry multipliers
    * **add-entries** — Add new entry roles
    * **remove-entries** — Remove entry roles
    * **clear-entries** — Remove all entry multipliers

    **Entry Management:**

    ```bash theme={null}
    # Set entry roles (replaces all)
    ~gw edit entries @VIP:5 @Booster:3 <link>

    # Add entry roles (keeps existing)
    ~gw edit add-entries @Supporter:2 <link>

    # Remove entry roles
    ~gw edit remove-entries @VIP @Booster <link>

    # Clear all entry multipliers
    ~gw edit clear-entries <link>
    ```

    **Aliases:** `gway edit`, `gwy edit`, `gw edit`\
    **Permissions:** Manage Server
  </Accordion>

  <Accordion title="giveaway list" icon="list">
    View all active giveaways in your server.

    <CodeGroup>
      ```bash Syntax theme={null}
      ~giveaway list
      ```

      ```bash Example theme={null}
      ~giveaway list
      ~gw list
      ```
    </CodeGroup>

    **What It Shows:**

    * All ongoing giveaways
    * Prize for each giveaway
    * Time until each ends
    * Direct links to giveaway messages

    **Aliases:** `gway list`, `gwy list`, `gw list`\
    **Permissions:** Manage Server
  </Accordion>
</AccordionGroup>

***

## How It Works

<Steps>
  <Step title="Start a Giveaway">
    Create a giveaway with your settings:

    ```bash theme={null}
    ~gw start 1d 2 Discord Nitro @Booster:3
    ```
  </Step>

  <Step title="Members Enter">
    Members react with 🎉 to enter:

    * Default: 1 entry per person
    * Boosters (in example): 3 entries each
    * Role restrictions apply if set
  </Step>

  <Step title="Winners Selected">
    When time expires (or you end it):

    * Random winners selected (weighted by entries)
    * Winners announced in channel
    * Giveaway message updated
  </Step>

  <Step title="Reroll if Needed">
    Pick new winners if needed:

    ```bash theme={null}
    ~gw reroll <message_link>
    ```
  </Step>
</Steps>

***

## Entry System

### Basic Entry

Everyone gets 1 entry by default when they react.

### Role Restrictions

Limit who can enter:

```bash theme={null}
~gw start 1d 1 Prize @Members
```

Only @Members can enter.

### Entry Multipliers

Give certain roles more entries:

```bash theme={null}
~gw start 1d 1 Prize @Booster:3 @VIP:5
```

* Regular members: 1 entry
* Boosters: 3 entries
* VIP: 5 entries

### Combined System

Restrict AND multiply:

```bash theme={null}
~gw start 1d 1 Prize @Verified @Booster:2 @VIP:4
```

* Must have @Verified to enter
* Boosters with @Verified: 2 entries
* VIP with @Verified: 4 entries

***

## Duration Examples

<Tabs>
  <Tab title="Common Durations">
    ```bash theme={null}
    # 30 minutes
    ~gw start 30m 1 Prize

    # 1 hour
    ~gw start 1h 1 Prize

    # 12 hours
    ~gw start 12h 1 Prize

    # 1 day
    ~gw start 1d 1 Prize

    # 1 week
    ~gw start 7d 1 Prize
    ```
  </Tab>

  <Tab title="Specific Times">
    ```bash theme={null}
    # 90 minutes
    ~gw start 90m 1 Prize

    # 6 hours
    ~gw start 6h 1 Prize

    # 3 days
    ~gw start 3d 1 Prize

    # 2 weeks
    ~gw start 14d 1 Prize

    # 1 month
    ~gw start 1mo 1 Prize
    ```
  </Tab>
</Tabs>

***

## Permission Requirements

<CardGroup cols={2}>
  <Card title="Bot Permissions" icon="robot">
    The bot needs:

    * Send Messages
    * Embed Links
    * Add Reactions
    * Manage Messages (to remove reactions)
  </Card>

  <Card title="User Permissions" icon="user">
    Command Requirements:

    * **Manage Server** — All giveaway commands
    * **None** — Entering giveaways (just react)
  </Card>
</CardGroup>

***

## Aliases

All giveaway commands support multiple aliases:

<CardGroup cols={4}>
  <Card title="giveaway" icon="gift">
    Full command
  </Card>

  <Card title="gway" icon="g">
    Short form
  </Card>

  <Card title="gwy" icon="g">
    Shorter form
  </Card>

  <Card title="gw" icon="g">
    Shortest form
  </Card>
</CardGroup>

***

## Usage Examples

<Tabs>
  <Tab title="Simple Giveaway">
    ```bash theme={null}
    # Basic giveaway
    ~gw start 1d 1 Discord Nitro

    # Multiple winners
    ~gw start 12h 3 Steam Keys

    # Longer duration
    ~gw start 7d 5 Custom Roles
    ```
  </Tab>

  <Tab title="Role Restricted">
    ```bash theme={null}
    # Members only
    ~gw start 1d 1 Prize @Members

    # VIP only
    ~gw start 12h 2 Exclusive Prize @VIP

    # Verified users
    ~gw start 3d 1 Prize @Verified
    ```
  </Tab>

  <Tab title="Entry Multipliers">
    ```bash theme={null}
    # Boosters get advantage
    ~gw start 1d 1 Nitro @Booster:3

    # Multiple tiers
    ~gw start 2d 2 Prize @VIP:5 @Supporter:2

    # Combined with restriction
    ~gw start 1d 1 Prize @Members @Booster:3 @VIP:5
    ```
  </Tab>

  <Tab title="Management">
    ```bash theme={null}
    # View active giveaways
    ~gw list

    # End early
    ~gw end <message_link>

    # Cancel giveaway
    ~gw cancel <message_link>

    # Pick new winners
    ~gw reroll <message_link>

    # Reroll 1 winner
    ~gw reroll <message_link> 1
    ```
  </Tab>

  <Tab title="Editing">
    ```bash theme={null}
    # Extend duration
    ~gw edit duration 2d <link>

    # Change winner count
    ~gw edit winner 5 <link>

    # Update prize
    ~gw edit prize New Amazing Prize <link>

    # Add entry roles
    ~gw edit add-entries @Supporter:2 <link>

    # Remove entry role
    ~gw edit remove-entries @VIP <link>
    ```
  </Tab>
</Tabs>

***

## Common Use Cases

<AccordionGroup>
  <Accordion title="Reward server boosters" icon="rocket">
    ```bash theme={null}
    # Give boosters more chances to win
    ~gw start 1d 1 Premium Role @Booster:5

    # Booster-only giveaway
    ~gw start 12h 2 Nitro @Booster
    ```

    Encourage boosting by giving advantages in giveaways.
  </Accordion>

  <Accordion title="Member milestones" icon="users">
    ```bash theme={null}
    # Celebrate 1000 members
    ~gw start 3d 10 Custom Roles

    # Thank active members
    ~gw start 1d 5 Gift Cards @Active:2
    ```

    Celebrate community growth with giveaways.
  </Accordion>

  <Accordion title="Event giveaways" icon="calendar">
    ```bash theme={null}
    # Holiday giveaway
    ~gw start 7d 3 Holiday Prizes

    # Birthday celebration
    ~gw start 24h 5 Birthday Prizes
    ```

    Host special event giveaways.
  </Accordion>

  <Accordion title="Tiered entry system" icon="layer-group">
    ```bash theme={null}
    # Multiple supporter tiers
    ~gw start 2d 3 Prize @Bronze:2 @Silver:3 @Gold:5 @Platinum:10

    # Staff appreciation
    ~gw start 1d 2 Prize @Helper:2 @Mod:3 @Admin:5
    ```

    Create fair but tiered entry systems.
  </Accordion>

  <Accordion title="Fix mistakes" icon="wrench">
    ```bash theme={null}
    # Wrong duration
    ~gw edit duration 3d <link>

    # Wrong prize
    ~gw edit prize Corrected Prize Name <link>

    # Change winner count
    ~gw edit winner 5 <link>

    # Invalid winner
    ~gw reroll <link> 1
    ```

    Correct errors after starting.
  </Accordion>
</AccordionGroup>

***

## Important Notes

<Info>
  **Winner Selection**

  * Winners selected randomly
  * Entry multipliers increase chances proportionally
  * Same person can't win multiple times
  * Winners must still have required role if restricted
</Info>

<Warning>
  **Data Persistence**

  * Giveaways persist through bot restarts
  * Timers automatically restart on bot reboot
  * Expired giveaways end immediately on restart
  * Backup system prevents data loss
</Warning>

<Note>
  **Entry Tracking**

  * Participants tracked in real-time
  * Rerolls use original participant list
  * Members who leave can't win
  * Role changes respected during selection
</Note>

***

## Related Features

<CardGroup cols={2}>
  <Card title="Role Management" icon="user-gear" href="/role">
    Create roles to use as giveaway prizes
  </Card>

  <Card title="Server Settings" icon="server" href="/server">
    Configure other server features
  </Card>
</CardGroup>