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:

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

   🎟️ *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:

   /raffle-status
   

   📊 *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:

   🎉 *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.

/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.

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.

/raffle-enter

Aliases: /enter, /join-raffle

---

/raffle-status — Check Active Draw

Returns live participant count and time remaining.

/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.

/raffle-end

Requires Group Administrator privileges.

---

/raffle-cancel — Abort Raffle

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

/raffle-cancel

Requires Group Administrator privileges.