Secret Santa Discord Bot 🎅

A Discord bot that manages Secret Santa gift exchanges with reaction-based signups and anonymous gift status updates.

Features

✨ Commands:

• /secretsanta - Start a Secret Santa sign-up (organizer)
• /assign - Close signups and assign Secret Santas (organizer only)
• /participants - List all participants in the Secret Santa (anyone)
• /santastatus - Check how many participants have received their gifts (anyone)
• /finish - End the Secret Santa and remove the session (organizer only)
• /ordered - Anonymously notify recipient their gift was ordered (participants)
• /delivered - Anonymously notify recipient their gift was delivered (participants)
• /received - Notify your Secret Santa that you received your gift (participants)

🎁 Features:

• React with 🎁 to join the Secret Santa
• Real-time participant counter
• Participants frozen at assignment time (reactions after /assign don't count)
• DM assignments to keep them secret
• Anonymous status updates to recipients
• Track gift receipt progress with /santastatus
• View participant list with /participants
• Automatic celebration when all gifts are received
• Multiple concurrent Secret Santas (different channels)

Setup

1. Create a Discord Bot

1. Go to Discord Developer Portal
2. Click "New Application" and give it a name
3. Go to the "Bot" tab
4. Click "Add Bot"
5. Under "Privileged Gateway Intents", enable:
   • ✅ MESSAGE CONTENT INTENT
   • ✅ SERVER MEMBERS INTENT
6. Click "Reset Token" and copy your bot token
7. Save this token securely (you'll need it in step 3)

2. Invite Bot to Your Server

1. Go to the "OAuth2" → "URL Generator" tab
2. Select scopes:
   • ✅ bot
3. Select bot permissions:
   • ✅ Send Messages
   • ✅ Send Messages in Threads
   • ✅ Embed Links
   • ✅ Read Message History
   • ✅ Add Reactions
   • ✅ Use External Emojis
4. Copy the generated URL and open it in your browser
5. Select your server and authorize the bot

3. Configure the Bot

1. Install dependencies:

   npm install

2. Create environment file:

   cp .env.example .env

3. Add your bot token to .env:

   DISCORD_BOT_TOKEN=your-actual-bot-token-here

4. Run the Bot

npm start

For development with auto-reload:

npm run dev

You should see:

✅ Logged in as YourBotName#1234
Bot is ready and listening for commands!

How to Use

Starting a Secret Santa

1. In any channel, type: /secretsanta
2. The bot posts an embed with instructions
3. Users react with 🎁 to join
4. The participant counter updates in real-time

Assigning Secret Santas

1. When ready, the organizer types: /assign
2. The bot:
   • Shuffles participants randomly
   • Creates a circular assignment (everyone gives and receives)
   • Posts an announcement tagging all participants
   • DMs each person their assignment (includes server and channel name)
   • Lists any users who failed to receive DMs with instructions to enable them

Finishing a Secret Santa

When the gift exchange is complete:

• The organizer types: /finish
• The bot removes the Secret Santa session
• You can start a new one anytime with /secretsanta

Updating Gift Status

Commands can be sent in channel OR via DM to the bot!

When you order a gift:

• In channel: Type /ordered (your message is deleted for privacy)
• In DM to bot: Type /ordered
  • If you're in only one Secret Santa, it auto-detects which one
  • If you're in multiple, the bot will ask you to specify which one
• Your recipient gets an anonymous DM: "Your Secret Santa has ordered your gift!"

When you deliver a gift:

• In channel: Type /delivered (your message is deleted for privacy)
• In DM to bot: Type /delivered
  • If you're in only one Secret Santa, it auto-detects which one
  • If you're in multiple, the bot will ask you to specify which one
• Your recipient gets an anonymous DM: "Your Secret Santa gift has been delivered!"

When you receive your gift:

• In channel: Type /received (your message is deleted for privacy)
• In DM to bot: Type /received
  • If you're in only one Secret Santa, it auto-detects which one
  • If you're in multiple, the bot will ask you to specify which one
• Your Secret Santa gets a DM: "Your recipient has confirmed they received their gift!"
• Both you and your Secret Santa see the overall progress (e.g., "5/10 gifts received")
• When all gifts are received, the bot announces completion in the channel!

Checking Progress and Participants

View participants:

• Type /participants in the channel
• See a numbered list of all participants (usernames only, no @mentions)
• Shows whether assignments have been sent

Check gift receipt status:

• Type /santastatus in the channel
• See total participants (frozen at assignment time), assignments status, and gift receipt progress
• Visual progress bar shows completion percentage

Commands Reference

Command	Where	Who Can Use	Description
/secretsanta	Channel	Anyone	Start a new Secret Santa in the channel
/assign	Channel	Organizer only	Close signups and assign Secret Santas
/participants	Channel	Anyone	List all participants (no mentions)
/santastatus	Channel	Anyone	Check gift receipt progress
/finish	Channel	Organizer only	End the Secret Santa and clear the session
/ordered	Channel or DM	Participants	Notify recipient gift was ordered (anonymous)
/delivered	Channel or DM	Participants	Notify recipient gift was delivered (anonymous)
/received	Channel or DM	Participants	Notify your Secret Santa you received your gift

Important Notes

⚠️ Users must have DMs enabled to receive:

• Their Secret Santa assignment
• Gift status notifications

💡 Tips:

• Each channel can have its own Secret Santa
• Need at least 2 participants to assign
• Removing your 🎁 reaction removes you from the list (before assignment)
• The organizer is the person who runs /secretsanta

Troubleshooting

Bot doesn't respond to commands

• Make sure MESSAGE CONTENT INTENT is enabled in Discord Developer Portal
• Verify the bot has permission to read/send messages in the channel

Bot can't send DMs

• Users must have "Allow direct messages from server members" enabled in Privacy Settings
• Check the bot's role has permissions in the server

"There is no active Secret Santa"

• Make sure you run /secretsanta in the channel first
• Each channel has separate Secret Santa sessions

Project Structure

.
├── bot.js              # Main bot code
├── package.json        # Dependencies
├── .env.example        # Environment template
├── .env               # Your bot token (create this)
└── README.md          # This file

Security Notes

• Never share your bot token
• Never commit .env to version control
• The .gitignore file protects your token automatically

Example Flow

User: /secretsanta
Bot: [Posts embed] "React with 🎁 to join!"

[Users react with 🎁]
[Participant counter updates: 0 → 1 → 2 → 3...]

Organizer: /assign
Bot: @User1, @User2, @User3 - Check your DMs!
Bot: ✅ Sent 3 assignment(s)!
[Sends DMs to each user with their assignment, including server and channel info]
[If any users fail: Lists them and reminds them to enable DMs]

User1 (in DM to bot): /ordered
Bot → User2 DM: "Your Secret Santa has ordered your gift!"
Bot → User1 DM: "✅ Notification sent!"

User1 (in DM to bot): /delivered
Bot → User2 DM: "Your gift has been delivered! 🎉"
Bot → User1 DM: "✅ Notification sent!"

User2 (in DM to bot): /received
Bot → User1 DM: "🎉 Great news! Your recipient confirmed they received their gift! (Progress: 1/3 gifts received - 33%)"
Bot → User2 DM: "✅ Notification sent! (Progress: 1/3 gifts received - 33%)"

[Check progress anytime]
Anyone: /santastatus
Bot: 📊 Secret Santa Status
     👥 Total Participants: 3
     ✅ Assignments Sent: Yes
     🎁 Gifts Received: 1/3
     📈 Progress: 🟩🟩🟩⬜⬜⬜⬜⬜⬜⬜ 33% complete

Anyone: /participants
Bot: 🎅 Secret Santa Participants
     1. Alice
     2. Bob
     3. Charlie
     Status: ✅ Assignments sent

[When all gifts are received]
Bot (in channel): 🎄 Secret Santa Complete! 🎄
                  🎉 All participants have received their gifts! 🎉

[After gift exchange is complete]
Organizer: /finish
Bot: 🎄 Secret Santa Finished! Happy holidays! 🎅

Alternative: Commands also work in channel
User1 (in channel): /ordered
[Message deleted immediately]
Bot → User2 DM: "Your Secret Santa has ordered your gift!"
Bot → User1 DM: "✅ Notification sent!"

License

MIT