Start with the smallest necessary scope
A verification bot commonly needs access to the designated channel, message sending, embeds and role management. File attachments are necessary when CAPTCHA images are sent as attachments. Do not grant Administrator simply to conceal a configuration error.
Check the hierarchy
The bot’s role must be above the role it grants. Manage Roles does not remove that restriction. Do not choose a role managed by another integration as the verification result. Check channel overrides separately: they may block visibility or posting even when server permissions look correct.
- The bot is in the intended guild and uses the correct channel ID.
- The target role exists and is neither @everyone nor an integration-managed role.
- The bot’s role is above the target role.
- Effective channel permissions allow the required operations.
Validate on the server
Do not accept a user-selected role ID from a form. The target role should come from server configuration. Bind each CAPTCHA challenge to a user, guild, expiry and attempt limit. Invalidate it after success. Recheck membership and relevant permissions before granting access.
Handle errors and repeated clicks
A slow operation should acknowledge the interaction within Discord’s required window. Display a clear error to the user and log the technical status without the token or CAPTCHA answer. Repeated clicks after success should not rerun the entire verification operation.
Gateway intents, OAuth scopes and channel permissions are different controls. Enable only intents required by events you actually consume. Store the bot token as a secret. If exposed, reset it in Developer Portal rather than merely deleting the message where it appeared.
Sources and documentation
Source links are retained for checking dates, availability and original context.