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

# Raffles & Whitelists

> Execute provably fair, reaction-driven whitelist giveaways and prize draws natively inside WhatsApp groups.

## Overview

Community giveaways are often plagued by chat clutter and manual winner tracking. Clyr provides an automated giveaway engine built directly on top of WhatsApp's native **Emoji Reaction** architecture.

Instead of flooding chat with text commands, community members enter giveaways simply by **reacting with any emoji** (e.g. 👍, ❤️, 🚀, 🔥) to the bot's announcement.

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                       CLYR RAFFLE LIFECYCLE                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. Admin initializes: /raffle <title> <spots> <duration>                   │
│  2. Bot publishes interactive announcement in group                         │
│  3. Members react with any emoji ──> Baileys socket records unique sender   │
│  4. Timer reaches 0:00 ──> Cryptographic Fisher-Yates winner selection      │
│  5. Bot tags winners in group with submission instructions                  │
└─────────────────────────────────────────────────────────────────────────────┘
```

***

## Complete Giveaway Lifecycle

**1. Launch the Raffle (/raffle)**

An administrator launches the giveaway by specifying the prize title, total winner spots, and duration:

```bash theme={null}
/raffle CyberPunks WL 5 2h
```

Clyr commits the giveaway to the PostgreSQL database, registers a timer in the background scheduler, and posts the announcement card in chat:

```text theme={null}
🎟️ *COMMUNITY WHITELIST RAFFLE* 🎟️
Prize: CyberPunks WL
Winners: 5 spots
Time Remaining: 2 hours

👉 *HOW TO ENTER:*
React to this message with ANY emoji to enter!

(Fallback: Send /raffle-enter if your WhatsApp does not support reactions)
```

**2. Live Participant Collection**

As members tap reactions, Clyr's socket listener captures the reaction metadata:

* **Participant Phone Number:** Verified directly from the message sender JID.
* **Sybil Defense:** Duplicate reactions from the same user are automatically deduplicated. If a user changes their emoji from 👍 to 🔥, their entry remains counted exactly once.
* **Unreaction Handling:** If a member removes their reaction, their entry is retracted.

**3. Check Mid-Raffle Status (/raffle-status)**

At any point during the countdown, members or admins can check entry counts:

```bash theme={null}
/raffle-status
```

```text theme={null}
📊 *Raffle Status: CyberPunks WL*
• Total Valid Entries: 48 participants
• Spots: 5
• Time Remaining: 42 minutes
```

**4. Automated Draw & Winner Announcement**

When the countdown timer expires (or if an admin forces an early draw with `/raffle-end`), Clyr executes a cryptographic Fisher-Yates shuffle across all verified participant JIDs:

```text theme={null}
🎉 *RAFFLE COMPLETED: CyberPunks WL* 🎉

Congratulations to our 5 verified winners:
1. @2348057416596
2. @2349012345678
3. @14155552671
4. @447123456789
5. @2348033334444

📩 *Next Steps:*
Winners, please DM your Solana / EVM wallet address to a group admin within 24 hours to claim your whitelist spot!
```

***

## Command Reference

### `/raffle` — Create a New Raffle

Initializes a timed giveaway in the active group.

```bash theme={null}
/raffle <title> <spots> <duration>
```

#### Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `title` | String | **Yes** | Name of the prize or project (e.g. `CyberPunks WL`, `100 USDT`, `Alpha Pass`). |
| `spots` | Number | **Yes** | Total number of winners to pick (must be at least 1). |
| `duration` | String | **Yes** | Time before automatic draw: `15m`, `30m`, `1h`, `2h`, `6h`, `1d`. |

> [!WARNING]
>
> Only **Group Administrators** can run `/raffle`. Only one active raffle can run per group at a time.

***

### `/raffle-enter` — Fallback Manual Entry

For users using legacy WhatsApp versions or third-party clients that do not support message reaction events, this command serves as a direct manual entry.

```bash theme={null}
/raffle-enter
```

**Aliases:** `/enter`, `/join-raffle`

***

### `/raffle-status` — Check Active Draw

Returns live participant count and time remaining.

```bash theme={null}
/raffle-status
```

***

### `/raffle-end` — Draw Winners Early

Forces the active raffle to conclude immediately, drawing winners from the current pool of entrants without waiting for the timer to expire.

```bash theme={null}
/raffle-end
```

> [!NOTE]
>
> Requires **Group Administrator** privileges.

***

### `/raffle-cancel` — Abort Raffle

Cancels the active raffle immediately. No winners are selected and the background timer is cleared.

```bash theme={null}
/raffle-cancel
```

> [!NOTE]
>
> Requires **Group Administrator** privileges.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.