Verification: Settings, Flow and Troubleshooting

Verification keeps new members away from your server until they confirm with one click that they have read the rules. Kage only swaps roles: new members get the Unverified role, and after the click they get the Verified role. Which channels each role can see is something you set in Discord.

This page is the reference: every setting, every step of the flow, every message. For a short setup walkthrough, see the guide How to set up Discord verification.

Requirements

• Access to the module: You sign in to the dashboard with Discord and need the Manage Server permission on the server (or access that a server admin has granted you for this module). The /verification command is also only visible with Manage Server.
• Two roles: Create the roles for "Unverified" and "Verified" in Discord. You can name them anything.
• Role order: Kage's role must be above both roles in the role list, otherwise Kage cannot assign them. Kage also needs the Manage Roles permission, which is part of the permissions of the standard invite.
• Channel permissions: Kage does not change channel permissions. For verification to have any effect, allow the Unverified role to see only the verification channel and block all other channels for it in Discord.
• Posting in the channel: In the verification channel Kage needs Send Messages and Embed Links, because the panel is a message with an embed and a button.

How verification works

When a member joins

1. If verification is switched on and an Unverified role is selected, Kage assigns that role right away, unless the member already has it.
2. If verification is off or no Unverified role is selected, nothing happens.
3. If Kage cannot assign the role (for example because of the role order), no message appears in Discord. The error is only recorded in the bot's operating log. In that case, check the role order.

When a member clicks the button

1. If verification is off, Kage replies that it is not active on the server.
2. If a minimum account age is set, Kage checks the age of the Discord account (the day the account was created, not when it joined your server). If the account is too new, the member gets a message and is not verified.
3. If the member already has the Verified role, Kage replies that they are already verified.
4. If a Verified role is configured but cannot be found (for example it was deleted), the member gets an error message. Beforehand Kage refreshes the role list from Discord so that a freshly created role is not wrongly treated as missing.
5. Kage assigns the Verified role and removes the Unverified role if the member has it. If no Verified role is configured, only the Unverified role is removed.
6. If Discord refuses the role assignment, Kage replies with a hint about role order and permissions.
7. On success Kage replies with a confirmation that only the member can see.

The button keeps working after a bot restart, including on older panel messages.

Settings at a glance

You find them in the dashboard under Verification, in the Configuration tab. The same values can be set with the /verification setup command.

The default text and the default label are in English. On a non-English server you may want to change both.

Setting it up in the dashboard

1. Create the two roles in Discord and set the role order and the channel permissions (see Requirements).
2. Open the Verification module in the dashboard, Configuration tab.
3. Select the verification channel, the Unverified role and the Verified role. Adjust the panel text, button label and minimum account age.
4. Click Post panel. This saves the settings, switches the module on and posts the panel message in the channel. Save stores changes without posting the panel.
5. If a value changes later, click Update panel. The existing message is then adjusted. If it no longer exists, Kage posts a new one.

Setting it up with commands

Good to know:

• Every call of /verification setup posts a new panel message. Earlier panels stay and keep working. To change the existing message, use Update panel in the dashboard.
• Kage points out in its reply if one of the two roles is not below Kage's highest role.
• When posting with /verification setup, the button shows the default label "I agree ✅". The button_label you pass is saved and only appears once you choose Update panel in the dashboard.
• If you switch verification off, Kage no longer assigns the Unverified role and the button no longer verifies anyone. Members who already have the Unverified role keep it. You then have to remove it yourself or give them the Verified role.

Messages members see

Kage currently sends these replies in English, visible only to the member in question:

Checking the result

1. Settings: Run /verification status. Status, channel, both roles and minimum account age should be correct.
2. Practical test: Join with a second Discord account that meets the minimum requirement. It should receive the Unverified role and see only the verification channel. After clicking the button it should have the Verified role and see the other channels.
3. Log in Discord: If the Audit Log module is switched on and a log channel is chosen, Kage writes entries titled "Verification" there for successful verifications, rejected accounts (too new) and a missing Verified role. A failure caused by the role order is not logged there.
4. Log in the dashboard: In the Verification module the Logs tab shows each successful verification, and the Statistics tab shows the count over time.

Troubleshooting

New members do not get the Unverified role

Check that "Verification enabled" is on and an Unverified role is selected. Then check the role order: Kage's role must be above the Unverified role. Members who were already on the server before setup do not get the role retroactively.

Members see all channels despite the Unverified role

Kage does not change channel permissions. In Discord, block the Unverified role from every channel except the verification channel.

The panel cannot be posted

In the dashboard: choose a channel first. If Kage says the channel does not exist, select it again. If Kage reports a missing permission, give Kage "Send Messages" and "Embed Links" in that channel. With the command, a missing permission produces the reply "I can't post in that channel.".

The button reports a role error

This is usually the role order. Move Kage's role above "Unverified" and "Verified". If Kage says the Verified role cannot be found, it was deleted or the wrong role is selected.

The button label is not what I set

After /verification setup the button shows the default label. Choose Update panel in the dashboard to apply your label.

Genuine members are rejected because of account age

The limit applies to the age of the Discord account, not to the time on your server. Lower the value or set it to 0.

Further reading

Verification is one building block for onboarding new members. Against coordinated mass joins, the anti-raid module helps: Preventing Discord raids. If newcomers should pick roles after verifying, onboarding helps.