Secret Santa Discord Bot

Secret Santa is the bot to host Secret Santas with on Discord.

• Easy to set up. People can join by command or reaction, and are assigned a role upon joining.
• Supports latecomers. These can be assigned to each other or replace a Santa who has left.
• Anonymous communication between a Santa and their giftee (the one receiving their gift).
• Moderation. Get info about a specific participant, and ban them from the event if you must.
• Privacy. All data is encrypted and deleted 30 days after the Secret Santa has ended.

The bot supports both classic commands and slash commands.

1. santa>create to create a Secret Santa.
2. santa>message to create an invite message.
3. Participants use >letter [text] to write about themselves/what they want. (Participants use commands in the bot’s DM)
4. santa>start to start the Secret Santa.
5. Participants use >read to read their giftee’s letter.
6. Participants use >submit [text] to submit their gift.
7. santa>end to end the Secret Santa.
8. Participants use >receive to receive their gift.
9. santa>destroy to destroy the Secret Santa, deleting all data. Happens automatically 30 days after ending it.

After you have added the bot to your server you can create a Secret Santa using the moderator commands. To use these commands you need either the Manage messages, Manage channels or Manage roles permission. You can change the prefix with santa>prefix [prefix].

Use santa>create to create a Secret Santa.

Now you have a few more options:

• santa>role [name] - Set or create the role that will be assigned to people who join the Secret Santa.

• santa>word [word] - Set the word the bot will use instead of ‘Santa’. Useful if you want to host a Secret Valentine instead.

• santa>toggle-latecomers - Turn on or off whether latecomers are allowed to join. On by default.

• santa>toggle-reveal - Turn on or off whether everyone’s Santa will be revealed when everyone gets their gift. On by default.

When you’re ready with setting it up you can start inviting people to join. There are two ways to do this.

• santa>invite [text] - Create an invite with a message to which people need to react with ✅ to join. If no text is provided for the message a default text will be used.
• santa>channel - Use this command in a channel where people are allowed to join using santa>join.

Both commands can be used multiple times, but only the last one will count, and they can’t co-exist. Only one method should be used. People who want to join should have ‘Allow direct messages from server members.’ turned on, or else the bot can’t send them a DM. This is on by default.

People who have joined can write a letter using >letter [text]. This command, like with all commands for participants, is to be used in the bot’s DM. The commands in DMs always use the prefix >, regardless of what prefix you set it to in your server. It’s not recommended you use the slash command for writing the letter, as that doesn’t allow you to write multiple lines, nor does it allow you to edit your message.

What they should write in that letter is up to you as a host of the Secret Santa. In general, you probably want them to write something about themselves and what they like so that their future Santa will know what to buy or make. If file attachments are added when using the command then links to these files will automatically be added to the letter. As long as the Secret Santa hasn’t started yet they can reuse the command to change their letter.

If someone changed their mind about participating they can leave using >leave in the bot’s DM. If they changed their mind again they can join the same way as they joined before. Whether someone can join again after the Secret Santa has started is based on what you set santa>toggle-latecomers. This is on by default. If someone leaves after the Secret Santa has started they are automatically banned from joining again.

You can use santa>stats (in your server) to see how many people still need to write a letter. Use santa>list letter to get a list of participants who have yet to write a letter. Use santa>list all to get a list of all participants. When you’re ready you can use santa>start to start the Secret Santa. Everyone will be assigned a Santa. As a Santa the one you need to give a gift is your giftee, and you are the giftee of your Santa. Note that they are assigned in a chain. No one’s Santa is also their giftee, and it doesn’t matter if you have an odd or even number of participants.

If you only have a few participants the bot will automatically DM everyone their giftee’s letter. If you have lots of participants you should inform them that they can read their giftee’s letter using >read. A taggable role set with santa>role would come in handy for this. The reason for this is that rate limits will not allow the bot to DM many people in a short period.

With santa>list read you get a list of participants who still need to read their giftee’s letter. Send them a personal reminder, or if they take too long use santa>ban [ID] (in your server) to ban them from the Secret Santa. Note that the Secret Santa bot does no server moderation. They are not banned from the server.

You can unban participants using santa>unban [ID].

The ID-parameter is the Discord ID of the user. To get this ID you first need to turn on Developer Mode. In Discord go to User Settings -> Appearance -> Developer Mode. After you’ve enabled this you can right-click on a user to get their Discord ID.

Participants can communicate with their giftee using the command >write-giftee [text]. Giftees can reply back using >write-santa [text]. This is useful in case the Santa has some questions for the giftee.

If this feature is abused (e.g. spam, foul language) it should be reported to you, the host of the Secret Santa. Using the ID of the person complaining you can use santa>info [ID] (in your server) to find out who their Santa and giftee is. You can then ban the culprit from the Secret Santa using the abuser’s ID.

If you have a bunch of people who joined after the Secret Santa had started you can assign them to each other using santa>assign-latecomers. You can use this command multiple times, but only when you have 3 or more latecomers.

When someone leaves or is banned after the Secret Santa has started they leave their Santa without a giftee and their giftee without a Santa. The Santa is offered to switch to the abandoned giftee using >switch. However, it might be the case that they already bought/made something for the giftee who left them. In that case, they can use >stay to stay with their old giftee.

While the Santa is still deciding, or if the Santa has decided to stay with their old giftee, latecomers come in handy. A latecomer (who doesn’t have a giftee yet) will automatically be assigned as the Santa of the abandoned giftee. In turn, that latecomer still won’t have a Santa. If there is another latecomer it will be assigned to the other latecomer. This can be repeated for as many latecomers there are. If the Santa whose giftee abandoned them eventually decides to >switch they will be assigned to the last latecomer in the chain, which closes the gap.

If this sounds confusing to you, don’t worry. It all happens automatically!

When a Santa has bought or made the gift for their giftee they can submit it using >submit [text]. If they have something physically sent to their giftees address the submission could simply inform them about it. Just like with letters the links to file attachments will automatically be added. This is useful if you made a drawing for example.

Even after the Secret Santa has ended participants can still submit their gift. However, they can’t edit their gift after their Secret Santa has ended.

You can use santa>list submit to get a list of participants who have yet to submit their gift.

Using santa>stats you can see how many people have submitted a gift. When you’re ready you can use santa>end to end the Secret Santa. If you only have a few participants the bot will automatically DM everyone their gift. If you have lots of participants you should inform them that they can read their giftee’s letter using >receive. Again the role comes in handy.

The letters written for the Secret Santa can contain sensitive information likes names and addresses. After everyone has submitted and received their gift you can use santa>destroy to destroy the Secret Santa. This will delete all the relevant data from the database. A Secret Santa is automatically destroyed 30 days after it has ended.

After you have started a Secret Santa you can always reset it. This brings it back to the state before you started the Secret Santa, allowing you to start it again. Members that already joined won’t have to rejoin the Secret Santa, and members that want to join can now do so. Note that by doing this everyone will be assigned to a random Santa again.

Resetting is useful when:

• You just started the Secret Santa too early by accident. There were still a few people that wanted to join. You reset the Secret Santa, have them join, and then start it again.
• You just finished the Secret Santa, and would like to do another Secret Santa with the same people (or more).
• The majority of the participants would like a different giftee for whatever reason.

By using >events the user can see a numbered list of Secret Santa events they are in. Using >select [number] they can select which Secret Santa their commands should be applied to. This way the user can participate in multiple Secret Santas just fine.

Secret Santa is made with Discord.js and Typescript.