Onboarding: Role Selection, Survey and Completion Role for New Members

Onboarding guides new members through a short, guided start: a personal greeting in a channel of its own, a role selection through your role panels, optionally a join survey ("How did you find us?") and a Done button that grants a completion role.

Onboarding is a module of its own, separate from the welcome message. Both can run at the same time. For short walkthroughs, see the guides Setting up onboarding questions and Server onboarding.

Requirements

• Access to the module: You sign in to the dashboard with Discord and need the Manage Server permission (or access granted for this module).
• Role panels: The role selection uses panels from the Role Panels module. Create them there first. Without panels, the role selection is missing.
• An onboarding channel: New members must be able to see and read it, even if they are otherwise still restricted (for example because of verification).
• Kage's permissions in the channel: Send Messages and Embed Links.
• Role order: Kage's role must be above the completion role and above the roles in the panels.

How onboarding works

1. A member joins. Kage checks whether onboarding is active and a channel is chosen. Otherwise nothing happens.
2. Kage looks up the channel. If it is deleted or unreachable, a warning appears in the operating log.
3. Kage posts the greeting in the onboarding channel, mentioning the member.
4. If the join survey is active and has at least one answer option, the question follows with a dropdown.
5. Then Kage posts up to 5 role panels that you selected, each with its buttons or dropdown. Kage skips panels without role options.
6. Last comes the Done button. It belongs to the member it was posted for: others get the message "This onboarding prompt isn't for you."
7. When the member clicks Done, Kage grants the completion role (if chosen and not yet held), deletes the Done message and confirms to the member.
8. Start and completion appear in the module's Logs tab.

The greeting, the panels and the survey remain in the channel. The buttons and the dropdown keep working after a bot restart.

The join survey

• You write the question and define the answer options (up to 25, each up to 100 characters).
• Without at least one option, the survey stays inactive even if it is switched on.
• Each member has one answer. If they choose again, the new answer replaces the old one.
• You see the evaluation in the dashboard in the Results section.

The texts of the button ("Done ✅"), the dropdown and the confirmations are in English.

Settings at a glance

Onboarding has no slash commands.

Interplay on join

Kage processes a join in a fixed order: invite attribution, anti-raid, welcome message, auto roles, verification, then onboarding and rules, and last the rank system. If verification blocks access until confirmation, make sure the onboarding channel is visible to the Unverified role; otherwise new members will not see the greeting.

Checking the result

1. Test join: Join with a second account. In the onboarding channel, the greeting, survey, panels and Done button appear.
2. Role selection: Choose a role in the panel and check that it is assigned.
3. Completion: Click Done. The completion role is assigned.
4. Evaluation: The survey answer is in the dashboard under Results, the flow in the Logs tab.

Troubleshooting

Nothing appears in the channel

Check that "Onboarding enabled" is on and a channel is chosen and saved. Check Kage's permissions in the channel and that the channel still exists.

The member cannot see the channel

The channel must be visible to new members, including the Unverified role if you use verification.

No panels are shown

No panels are selected, or the chosen panels have no role options. Create them in the Role Panels module and select them under Role panels in onboarding. Kage does not show more than 5 panels.

The survey is missing

It is switched off or has no answer option.

The completion role is not assigned

Kage's role is below the completion role in the role list, or Kage lacks the Manage Roles permission. Discord shows no message for this.

Further reading

Design the role selection with Role panels. Rules for new members are described in Rules and Verification.