Skip to main content

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

​
Complete Giveaway Lifecycle

1

Launch the Raffle (/raffle)

An administrator launches the giveaway by specifying the prize title, total winner spots, and duration:
Clyr commits the giveaway to the PostgreSQL database, registers a timer in the background scheduler, and posts the announcement card in chat:
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:
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:

​
Command Reference

​
/raffle — Create a New Raffle

Initializes a timed giveaway in the active group.

​
Parameters

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.
Aliases: /enter, /join-raffle

​
/raffle-status — Check Active Draw

Returns live participant count and time remaining.

​
/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.
Requires Group Administrator privileges.

​
/raffle-cancel — Abort Raffle

Cancels the active raffle immediately. No winners are selected and the background timer is cleared.
Requires Group Administrator privileges.