How to add a captcha or verification step for new Discord members

Before you start

• Enable the Free Welcome module on an online bot in a test server. Use a staff account with Manage Server to configure it through the welcome command. Arrange a controlled new-member join for verification testing.
• Create ordinary Unverified and Verified roles below the bot’s highest role, and give the bot Manage Roles. Choose a welcome channel the newcomer can see and the bot can view and use to send messages and embeds.
• Plan channel permissions so @everyone and Unverified cannot access member-only channels, while Verified grants the intended access. Check other role-granting modules, self-role lists and panels so they do not grant that access before verification.

1. Choose a visible welcome channel

   In Welcome Settings, select the server and welcome channel. In Discord, `!welcome channel #welcome` sets it using an actual channel mention; the caller needs Manage Server. Replace ! with your bot’s prefix. The prompt is a server message, not a private DM, so keep this channel reachable to newcomers.

   Set the channel explicitly to avoid a surprise destination. Without a usable configured channel, the module looks for a text channel named welcome, welcome-goodbye or greetings, may create one if auto-create is enabled, and otherwise falls back to the server’s system channel. If it cannot find a channel or send the prompt, the newcomer cannot complete the challenge. Check channel visibility, Send Messages and Embed Links before enabling it.

2. Configure the roles, then enable the challenge

   In Discord, use `!welcome captcha-role @Verified` to choose the role for a correct answer, then `!welcome unverified-role @Unverified` to choose the role given before the challenge. These are subcommands of welcome and require Manage Server. They accept actual role mentions. The interactive `!welcome setup` wizard also asks about captcha and the two roles. The dashboard exposes Enable captcha verification; use the Discord configuration above to set the verification-specific roles explicitly.

   Once the roles and permissions are ready, enable the dashboard’s Enable captcha verification switch and save. In Discord, `!welcome captcha` (also `!welcome verify`) toggles the current state; it is not an idempotent enable command, so read its result before running it again. Verification is off by default, and both verification-role settings are initially empty.

   When captcha is enabled, Welcome skips its immediate auto-role assignment on join. A correct answer gives the configured captcha role, or falls back to the stored auto-role ID if no captcha role is set. That fallback uses the stored ID even if the normal auto-role switch is off. Choose the verified role explicitly to avoid relying on that fallback. This only controls Welcome’s assignments: another module can still grant a role independently.

3. Understand what the new member sees

   On a non-bot member’s join, the module stores a pending challenge and adds the configured unverified role if it exists. It posts a mention of that member, a Verification Required embed, an addition question and numeric answer buttons. Each addend is from 1 to 10. The footer asks the member to click the correct answer below. The challenge does not ask them to type a code, read an image or visit a website.

   Only the member named by that challenge can answer it. A wrong choice gets a private “Wrong answer! Please try again.” reply. Once a staff review channel is set, wrong answers are bounded (three attempts by default); after the final wrong answer, the member stays unverified and the same staff-review message is sent. A correct choice clears the pending challenge, attempts to remove Unverified and add the configured verified or fallback role, then replaces the prompt with a verification success message and removes the embed and buttons.

4. Optional account-age and failed-captcha review

   In the Welcome Automation settings, turn on “Hold young accounts for staff review”, choose 1, 3, 7, 14 or 30 days, and enter a staff review channel ID. When an account younger than that age joins, Welcome keeps it unverified (if you configured Unverified) and posts its account age and join time for staff. Staff with Manage Server can choose Approve, which grants the configured verified role, or Kick when the bot has Kick Members. Without that permission, the review shows Approve and explains that kicking is unavailable.

   This is intentionally a narrow hold-and-review workflow. Account age and failed challenges do not prove an account is an alt, human, safe, or malicious. Free supports one review channel. Pro adds multiple review channels and a role-ID allowlist that skips only the account-age hold.

5. Plan for the five-minute timeout and failed role changes

   For a successfully posted prompt, a five-minute timer attempts to delete the message and clears the pending challenge. It does not kick or ban the member, grant the verified role, remove the unverified role or create another prompt. Someone who has not answered keeps the unverified role if it was assigned. Arrange a staff support path for that situation; this module registers no command to resend an expired challenge.

   Pending answers are stored in memory, so a bot restart loses them. A member leaving the server also clears their pending entry. Role additions and removals after a correct answer catch Discord errors without stopping the success message. That means “has been verified” is not proof that the expected roles or channel access actually changed. Inspect both after testing, particularly if the bot lacks Manage Roles or its highest role is below either target role.

6. Test a real join and keep the plan limits clear

   Use a staff-controlled test account joining the test server. Confirm it receives Unverified, can see the welcome prompt and cannot see protected channels. Click one wrong answer, then the correct one, and inspect its roles and channel access. In a separate controlled join, leave the prompt unanswered for five minutes and confirm the expected timeout behavior. `!testwelcome` only sends a sample welcome message; it does not start a verification challenge.

   Welcome is Free; its math challenge, bounded retries and one review channel have no separate Pro check. Free welcome output is text or embed. Pro adds image welcome cards, multiple review channels and an account-age role allowlist, not image captchas or alt detection. Both plans use the same five-minute expiry and lose pending challenges on restart. Follow Welcome and Pricing below for details.