Recruitment System Documentation

The Recruitment System automates the entire recruiting pipeline inside your Discord server. Players apply by clicking a button in a public embed, fill out a brief form, and are automatically assigned a private text channel where your staff can review, verify, and approve or reject the application — all without leaving Discord.

🎯 Prerequisites: Before configuring the Recruitment System, make sure the bot is set up with /setup start and that it has permission to create channels and manage roles in your server.

Table of Contents

System Overview

The Recruitment System handles the full lifecycle of a player application in three stages:

  1. An admin configures the system via the web dashboard and publishes a public recruitment embed in a channel of their choice.
  2. A player clicks one of the category buttons in that embed, selects their in-game role, fills out a short form, and receives a private channel automatically.
  3. Staff reviews the application inside the private channel using action buttons (Approve, Reject, etc.). The bot logs every action and notifies the applicant by DM.
One application at a time: A player can only have one open application at a time. If they try to apply again while their previous request is still open, the bot will refuse and remind them to wait.

Roles & Permissions

Who How assigned What they can do
Administrator Discord native permission Full access to the web dashboard to configure every aspect of the system
Staff Role Configured in dashboard → Channel Settings Approve, approve & delete, and reject applications in the recruitment channel
Applicant (any member) — Submit an application and cancel their own request
Staff Role: Approve and Reject buttons are restricted to members who have the Staff Role configured in the dashboard. If the staff role is not configured, any user can interact with those buttons — make sure to set it up before going live.
Approved Role: If an Approved Role is configured in Basic Settings, it is automatically assigned to the applicant whenever they are approved using either the Approve or Approve & Delete button. This is optional — if not configured, no role is assigned on approval.

Initial Setup (Dashboard)

All configuration is done through the web dashboard. Go to your guild's page and click Recruitment in the sidebar navigation.

Order matters: Configure Basic Settings first to activate the system, then set up Categories and Channel Settings before sending the embed. Without at least one category, the embed will have no buttons.

Basic Settings

Field Description Required
Enable Recruitment System Toggle to activate or deactivate the entire system. When disabled, the embed buttons stop working and no new applications can be submitted. Yes
Channel Name Template Template used to generate the name of each private recruitment channel. Supports the following placeholders:
  • {playerName} — the player's Albion Online name
  • {username} — the applicant's Discord username
  • {role} — the selected in-game role (e.g., dps, healer)
  • {category} — the application category chosen (e.g., pvp)
Example: recruitment-{playerName} → creates a channel named recruitment-dragonslayer 		Yes
Staff Role Discord role whose members can approve and reject applications. If not configured, any member can interact with the action buttons. Recommended
Approved Role Discord role automatically assigned to an applicant when their application is approved (via Approve or Approve & Delete). If not configured, no role is assigned on approval. No
Application Instructions Custom text sent inside every recruitment channel as a dedicated embed. Use it to tell applicants what to do next, what links to share, or what to wait for. Supports plain text and basic Discord markdown. No

Embed Configuration

This section controls how the public-facing recruitment embed looks inside your Discord channel. This is the embed that everyone sees and clicks to start an application.

Field Description
Embed Title Title shown at the top of the embed, e.g. "Join Our Guild!"
Embed Description Body text of the embed. Explain what your guild is looking for, requirements, or general info for applicants.
Embed Color Left-border color of the embed in hex format (e.g., #2ecc71).
Embed Image Optional image displayed at the bottom of the embed. Upload a banner, guild logo, or any image relevant to your recruitment. The current image is previewed on the page with an option to delete it.

Categories

Categories define the buttons that appear in the public recruitment embed. Each category represents a different track or type of recruit. When a player clicks a category button, their application is tagged with that category and their private channel is created inside the corresponding Discord category.

Discord limit: A maximum of 25 categories can be created, as Discord only allows 25 buttons per message (spread across action rows).

Adding a Category

Fill in the following fields in the Add New Category form and click Add Category:

Field Description Required
Category Name Display name of the category shown on the button, e.g. "PvP Elite" or "Gathering". Must be unique. Yes
Discord Category The Discord channel category (folder) where new recruitment channels will be created for this track. This is not the bot category — it is a Discord server category. Select it from the dropdown. Yes
Icon An emoji that appears on the category button. Click the emoji you want from the icon picker. Yes
Minimum Kill Fame If set above 0, the bot will check the applicant's Kill Fame via the Albion Online API and block the application if they do not meet the minimum. Set to 0 to disable this check. No
Minimum Kills If set above 0, the bot checks the kill count reported by the applicant. If the applicant's number is below the minimum, the application is blocked. Set to 0 to disable this check. No
Stat checks and the Albion API: Kill Fame is verified automatically by the bot querying the Albion Online public API using the player name provided in the application form. Kill Count, however, is self-reported by the applicant — it is not verified by the API. If the player's name is not found in the API, Kill Fame is treated as 0 and the check will fail if a minimum is configured.

Removing a Category

Each category listed on the dashboard has a Remove button. Removing a category does not delete any open recruitment channels — it only removes the button from the public embed the next time it is sent/updated.

Channel Settings

Field Description Required
Embed Channel The text channel where the public recruitment embed will be sent. This should be a channel that all members can see but not type in. Yes
Recruitment Log Channel A staff-only channel where the bot posts a log entry every time a new application is received, approved, rejected, or cancelled. Recommended
Staff Role The Discord role that allows members to Approve or Reject applications. Members without this role can view the channel but cannot interact with the action buttons. Strongly recommended

Verification Websites

Verification websites are external links auto-generated for each applicant and posted inside the recruitment channel so staff can quickly check a player's stats and history without manually searching.

Popular examples: albiondb.net, murderledger.albiononline2d.com.

Adding a Verification Website

Field Description Required
Website Name Display name, e.g. "AlbionDB". Must be unique. Yes
URL The full URL to the player's profile page. Use the placeholder {playerName} where the player name should be inserted. The bot replaces this placeholder automatically with the applicant's Albion Online name.

Example: https://albiondb.net/players/{playerName} 		Yes
Icon Emoji shown next to the website name in the verification embed. Yes
Tags Optional comma-separated labels that describe what the website shows, e.g. kills, history, fame. These appear as small badges in the embed to help staff know what to look at. No
Tip: If your URL does not contain {playerName}, the bot will display a confirmation before saving, since the link will be the same for every applicant regardless of who applies.

Sending the Embed

After all settings are configured, scroll to the top of the Recruitment dashboard page and click Send Recruitment Embed. The bot will post (or update) the embed in the channel configured under Channel Settings → Embed Channel.

Updating the embed: Every time you click Send Recruitment Embed, the bot posts a new embed message. If you update categories or the embed text and want to refresh the Discord message, click the button again. The old message is not automatically deleted — you should delete it manually to avoid confusion.

Player Application Flow

The following steps describe exactly what a player experiences from the moment they find the recruitment embed to the moment their private channel is ready.

Step What happens Who sees it
1. Click Category Button The player clicks one of the category buttons in the public embed (e.g., ⚔️ PvP Elite). The bot checks whether the system is active and whether the player already has an open application. If either check fails, the bot replies with an error (visible only to them). Applicant only (ephemeral)
2. Select In-Game Role A dropdown menu appears with five role options: DPS ⚔️, Healer 💚, Battlemount 🐎, Tank 🛡️, Support 🔧. The player picks one. Applicant only (ephemeral)
3. Fill Out the Application Form A modal (pop-up form) appears with three fields:
  • Albion Online Nickname (required) — the player's exact in-game name
  • Kill Count (optional) — self-reported approximate number of kills
  • Old Nickname (optional) — previous name if Sandbox Interactive ever changed it. When filled, the bot uses this name to look up stats in the Albion API instead of the current name
 Applicant only (modal)
4. Bot Validates Requirements After form submission, the bot queries the Albion Online API for the player's Kill Fame. If the selected category has minimum requirements (Kill Fame or Kill Count) and the player does not meet them, the application is blocked and the player receives a detailed message explaining their current stats vs. the requirements. Applicant only (ephemeral)
5. Private Channel Created The bot creates a private text channel inside the configured Discord category for that track. The channel is visible only to the applicant, the staff role, and the bot. The bot immediately sends the application embed, verification websites, instructions, and action buttons. Channel visible to applicant + staff
6. Confirmation The bot replies to the applicant (privately) with a success message and a mention link to their new channel so they can click directly to it. Applicant only (ephemeral)
Albion API note: The bot searches the Albion API using the player's name. API data can sometimes be delayed by hours or even days after a name change or guild move. If the player is not found, their Kill Fame is treated as 0. This affects Kill Fame requirement checks but does NOT block the application on its own — only the requirement check may block it.

Inside the Recruitment Channel

When a recruitment channel is created, the bot sends the following messages in sequence:

  1. Application Embed — a blue embed summarizing the application with all fields visible to staff:
    • Discord mention of the applicant
    • Albion Online nickname provided
    • Selected in-game role
    • Reported kill count (if provided)
    • Old nickname / alternative name (if provided)
    • Albion Player ID, Kill Fame, Death Fame, Fame Ratio (pulled from API if the player was found)
    • Current guild in Albion Online (if the player was found in the API)
    • API status warning if the player was not found
  2. Verification Websites Embed (if configured) — a red embed listing all verification website links, each one already pre-filled with the player's name. Staff can click any link directly.
  3. Application Instructions Embed (if configured) — an orange embed showing the custom instructions text set in the dashboard.
  4. Action Buttons — four buttons for managing the application:
    • ✅ Approve
    • 🗑️ Approve & Delete
    • ❌ Reject
    • 🚫 Cancel Application
Footer: The application embed footer always shows the internal Application ID and the exact date/time the application was created, useful for audit purposes.

Staff Actions & Buttons

✅ Approve

Who can use it: Members with the configured Staff Role only.

Clicking Approve opens a modal where the staff member can optionally write internal notes about the applicant (visible to staff and the applicant). After submitting:

  1. The application is marked as approved in the database.
  2. The channel is renamed to accepted-{playerName}.
  3. A green approval embed is posted in the channel, tagging the applicant and showing the reviewer's name.
  4. A 🗑️ Delete Channel button appears so staff can manually clean up the channel when ready.
  5. The applicant receives a DM notification with the approval details (including staff notes, if provided).
  6. If an Approved Role is configured, it is automatically assigned to the applicant.
  7. A log entry is posted to the recruitment log channel.

🗑️ Approve & Delete

Who can use it: Members with the configured Staff Role only.

This button approves the application and automatically deletes the channel 10 seconds later. It is ideal for fast-tracking applicants when no further discussion is needed in the channel.

  1. The application is marked as approved.
  2. A green approval embed is posted with a countdown notice ("this channel will be deleted in 10 seconds").
  3. The applicant receives a DM notification.
  4. If an Approved Role is configured, it is automatically assigned to the applicant.
  5. A log entry is posted to the recruitment log channel.
  6. After 10 seconds, the channel is permanently deleted.
⚠️ This action is irreversible. Once the channel is deleted, the conversation and embeds are gone. Use Approve (without Delete) if you want to keep the channel for onboarding or further instructions.

❌ Reject

Who can use it: Members with the configured Staff Role only.

Clicking Reject opens a modal where the staff member must provide a rejection reason (required field). After submitting:

  1. The application is marked as rejected.
  2. A red rejection embed is posted in the channel showing the reason.
  3. The applicant receives a DM notification with the rejection reason.
  4. A log entry is posted to the recruitment log channel.
  5. After 10 seconds, the channel is automatically deleted.

🚫 Cancel Application

Who can use it: The applicant only (the player who submitted the application).

Staff members cannot use this button — it belongs exclusively to the applicant. Clicking it opens a modal where they can optionally explain why they are withdrawing. After submitting:

  1. The application is marked as cancelled.
  2. A cancellation embed is posted in the channel.
  3. A log entry is posted to the recruitment log channel.
  4. After 10 seconds, the channel is automatically deleted.
Re-applying: After an application is cancelled (or rejected), the player is free to submit a new application immediately. The one-active-application limit only applies while an application is in open status.

🗑️ Delete Channel (post-approval)

Who can use it: Members with the configured Staff Role.

This button only appears after an application is approved using the regular Approve button (not Approve & Delete). It lets staff manually delete the channel once they are done with onboarding or follow-up conversation. The channel is deleted immediately with no countdown.

Managing Active Requests (Dashboard)

The bottom section of the Recruitment dashboard page shows a table of all currently open applications for your server. Each row displays:

Clicking Close Request from the dashboard performs a full closure of the application: it marks the request as closed in the database and deletes the associated Discord channel. Use this as an administrative override when the request needs to be cleared without going through the in-channel buttons (e.g., the bot lost access to the channel, or the channel was already manually deleted).

No active requests? The table only appears when there is at least one open application. If all applications have been processed, this section is hidden.

Log Channel

When a Recruitment Log Channel is configured, the bot automatically posts a structured embed every time one of the following events occurs:

Event Embed color Key information logged
New application submitted 🔵 Blue Applicant, player name, category, role, date, channel link, Kill Fame (if found in API)
Application approved 🟢 Green Applicant, player name, category, role, approved by, approval date, staff notes
Application approved & deleted 🟢 Green Same as above + note about channel deletion
Application rejected 🔴 Red Applicant, player name, category, role, rejected by, rejection date, rejection reason
Application cancelled 🟠 Orange Applicant, player name, category, cancellation date, channel, reason

Full Flow Summary

Status Meaning Channel exists? Action buttons active?
Open Application submitted, waiting for staff review ✅ Yes ✅ Yes — all 4 buttons
Approved Staff approved the application ✅ Yes (renamed to accepted-…) Only 🗑️ Delete Channel
Rejected Staff rejected the application ❌ No (deleted after 10s) —
Cancelled Applicant withdrew their own request ❌ No (deleted after 10s) —
Closed Manually closed via the web dashboard ❌ No (deleted by dashboard action) —

Troubleshooting

Problem Likely cause Solution
Recruitment embed has no buttons No categories have been added Add at least one category in the dashboard, then re-send the embed
Buttons don't respond / "System not configured" The recruitment system is disabled or not saved Go to Basic Settings and make sure Enable Recruitment System is toggled on, then save
Channel not created after form submission Bot lacks Manage Channels permission, or the Discord category ID is wrong Make sure the bot has Manage Channels and Manage Roles permissions server-wide. Verify the Discord Category ID in each recruitment category
Approve / Reject buttons say "No permission" The acting user does not have the configured staff role Assign the staff role to the user, or update the Staff Role in Channel Settings
Kill Fame check fails for a valid player Albion Online API did not return data (player not found or API delay) Ask the player to try again later, or temporarily lower the minimum Kill Fame while the API syncs
Player cannot re-apply after rejection Application is stuck in "open" status (channel was manually deleted without using the buttons) Use the Close Request button in the dashboard to properly close the lingering record
Applicant did not receive a DM The applicant has DMs from server members disabled (common Discord privacy setting) No action needed — the result is still visible inside the recruitment channel. You may inform the applicant directly in the channel
Verification website links are broken URL does not contain the {playerName} placeholder, or the player's name has special characters Edit the website URL in the dashboard to include {playerName} in the correct position. Special characters in player names are URL-encoded automatically by the bot