Alliance System

The Alliance System lets you partner with other guilds in Albion Online and grant their members access to your Discord server with a dedicated alliance role. Players from allied guilds go through a verification process where leadership can accept or deny their request. Once approved, the player receives the alliance role and can participate in your server's alliance-specific channels.

📖 Table of Contents

⚠️ Alliance vs Secondary Guilds — Read This First

This is the most common mistake. The bot has two completely different places to add guilds. Make sure you understand which one to use for allied guilds.

There are two separate pages in the dashboard that deal with guilds, and they serve entirely different purposes:

Page Purpose Who are they? What does adding do?
Guilds
Dashboard → Guilds		 Secondary guilds of your own organization Extra guilds your leadership controls directly (e.g., a farm guild, a secondary roster) Grants that guild's members your own member role — they are treated as full members of your server
Alliance
Dashboard → Alliance		 Partner guilds from other organizations Allied guilds you cooperate with but don't control Allows their players to request the alliance role — they are treated as allied visitors, not full members
Never add an allied guild in the Guilds page. If you do, their players will be treated as full guild members and receive your member role instead of the alliance role. This causes permission conflicts, clutters your member list, and breaks the separation between your guild members and your allies.
Rule of thumb: If you own the guild or it belongs to your organization — it goes in Dashboard → Guilds. If it's a partner/ally from another group — it goes in Dashboard → Alliance.

🔍 How the System Works

Here's the full flow from alliance setup to a player having the alliance role in your Discord:

Step 1 — Setup

A manager configures the system with /alliance setup: defines an alliance role and a verification category where temporary channels will be created.

Step 2 — Add Allied Guilds

Management adds partner guilds using /alliance add-guild or directly in the dashboard. Only players from registered allied guilds can request the alliance role.

Step 3 — Player Requests Perms

An allied player uses /alliance perms with their in-game nickname. The bot verifies they exist in the Albion API and belong to a registered allied guild.

Step 4 — Leadership Approves

A private verification channel is created for the player. Leadership reviews the request and clicks Accept or Deny. The channel automatically deletes after 10 seconds.

Double verification: When leadership clicks Accept, the bot performs a second real-time check against the Albion API to confirm the player is still in an allied guild at the moment of acceptance. This prevents players from changing guilds between the request and the approval.

⚙️ Initial Setup — /alliance setup

Before any allied player can request permissions, a manager must run the setup command once.

Requires the Management Role configured in your guild settings.

Command

/alliance setup alliance-role:@AllyRole category:#verification-category
Parameter Required Description
alliance-role Yes The Discord role that all approved alliance members will receive. Create a dedicated role for allies (e.g., @Ally).
category Yes A Discord channel category where temporary verification channels will be created for each player requesting alliance permissions. You control who can see this category.
Create a dedicated category called something like Alliance Verification and restrict its visibility so only leadership can see the temporary channels that appear there.

After running this command, the bot confirms with an embed showing the configured role and category, and also posts a log to the guild's designated log channel.

🛡️ Adding Allied Guilds — /alliance add-guild

Only players from guilds on your alliance list can request the alliance role. You must add each allied guild before their players can register.

Requires the Management Role.

Command

/alliance add-guild guild-name:GuildName
Parameter Description
guild-name The exact name of the guild in Albion Online. The bot searches the Albion API to confirm the guild exists before adding it.

Once added, the guild appears in the Allied Guilds table in the dashboard and its players can immediately start requesting alliance permissions.

🔑 Player Verification — /alliance perms

This command is used by allied players who want access to your Discord server. Anyone can use it, but they must be part of a registered allied guild.

Command

/alliance perms nickname:YourIngameName
/alliance perms nickname:YourIngameName api-nickname:APISearchName
Parameter Required Description
nickname Yes Your in-game character name exactly as it appears in Albion Online.
api-nickname No An alternative name to use when searching the Albion API, in case your name uses special characters that search poorly. If not provided, the same value as nickname is used.

What the bot checks before creating a verification channel

Check What happens if it fails
Alliance system is configured Error message — ask management to run /alliance setup
Discord user not already registered as an ally Tells the player they already have alliance permissions
Player nickname not already used by another Discord account Tells the player that nickname is already taken
Player exists in the Albion API Tells the player their name was not found
Player is currently in a guild Tells the player they are not in any guild
Player's guild is in the alliance list Tells the player their guild is not part of this alliance

If all checks pass, the bot creates a private verification channel under the configured category. This channel is visible only to the requesting player and the guild's management role. An embed appears in the channel with the player's details and two action buttons.

🔘 Embed Buttons — Accept & Deny

Inside the verification channel, a management member (someone with the management role) will see an embed with player information and two buttons:

Button Who can use it What it does
✅ Accept Management role only Opens a modal with an optional reason field. After confirming, the bot performs a second real-time check against the Albion API to verify the player is still in an allied guild. If the check passes:
  • The alliance role is granted to the player.
  • The player's Discord nickname is changed to [GUILDALIAS] PlayerName.
  • A record is saved in the database.
  • A log embed is posted to the server's log channel.
  • The verification channel is deleted after 10 seconds.
❌ Deny Management role only Opens a modal with a required reason field. After confirming, the player is notified with the reason for denial. A log embed is posted to the log channel. The verification channel is deleted after 10 seconds.
Only members with the Management Role (set in guild configuration) can click Accept or Deny. If someone else clicks the button, they will receive a private error message.
Nickname format after acceptance: The bot automatically renames the player in Discord to [GUILDTAG] PlayerName. For example, a player named ArcaneWizard from a guild called DragonOrder would become [DragonOrder] ArcaneWizard. This makes it immediately clear which guild each allied member belongs to.

📋 Listing Allied Guilds — /alliance guilds-list

Any member can run this command to see which guilds are currently part of the alliance. No special role is required.

/alliance guilds-list

The bot responds with an embed listing all registered allied guilds. Useful for players who want to verify whether their guild is on the alliance list before requesting permissions.

🧹 Alliance Flush — /alliance flush

Over time, alliances change. Players might leave their guild, or guilds might leave the alliance. The flush command scans all registered allies and removes anyone whose guild is no longer in the alliance list.

Requires the Management Role. This action removes the alliance role from affected players and deletes their registration. 
/alliance flush

The bot checks each registered ally's current guild via the Albion API. Anyone not in a registered allied guild is kicked from the alliance system (role removed, record deleted). A summary of removed players is posted after the process completes.

The bot also runs an automatic hourly ally flush in the background. The manual /alliance flush command is useful when you need an immediate cleanup after a guild leaves the alliance.

🖥️ Managing in the Dashboard

The Alliance Management page in the dashboard gives leadership a clear view of all allied guilds and registered members, with tools to manage the configuration without needing Discord commands.

Access it from the dashboard sidebar: Alliance Management.

Action Buttons

Two buttons appear in the top-right corner of the page:

Button What it does
⚙️ Config Opens the Alliance Configuration modal. Lets you change the Alliance Role, the Verification Category, and toggle the system on or off — without needing to run /alliance setup again in Discord.
➕ Add Guild Opens the Add Allied Guild modal. Type a guild name, search results from the Albion API appear below, select the correct guild, and confirm. The guild is immediately added to the alliance list.

Config Modal — Fields

When you click Config, a modal opens with the following fields:

Field Description
Alliance Role Dropdown with all roles in your Discord server. Select the role that will be granted to approved alliance members.
Verification Category Dropdown with all categories in your Discord server. Select the category where temporary verification channels will be created.
Enable Alliance System Checkbox to enable or disable the alliance system entirely without deleting the configuration.

Add Guild Modal

When you click Add Guild, a modal opens with:

  1. Guild Name field — Start typing a guild name. After 2 or more characters, the bot searches the Albion API and shows matching results below.
  2. Search results — Click on the correct guild in the dropdown to select it. The field updates with the selected guild name.
  3. Reason field (optional) — Add a note about why this guild is being added. For your own records only.
  4. Click Add Guild to confirm. The guild is added instantly.

Allied Guilds Table

The first table on the page shows all guilds currently in your alliance:

Column Description
Guild Name The Albion Online guild name.
Guild ID The internal Albion API ID for the guild.
Added By The username of whoever added this guild to the alliance.
Added Date When the guild was added.
Actions 🗑️ Remove — Removes the guild from the alliance list. Note: this does not automatically remove the alliance role from players of that guild. To clean up those players, run /alliance flush or remove players manually from the Registered Allies table.

You can search the table using the search box above it (filters by guild name, ID, or who added it) and sort any column by clicking its header. The table is paginated and shows 25 entries per page by default (adjustable to 10, 25, 50, or 100).

Registered Allies Table

The second table shows all individual allied players who have been approved and have the alliance role:

Column Description
Player Name The Albion Online in-game name of the allied player.
Guild The allied guild the player belonged to at the time of registration.
Discord User The Discord ID linked to this player.
Joined When the player was accepted into the alliance.
Actions 🗑️ Remove — Removes the player's registration from the alliance. This removes them from the database record but does not automatically remove their Discord alliance role. You must manually remove the role from the player in Discord if you want to revoke their access.
Removing a player from the table does not revoke their Discord role. The dashboard only manages the database record. To fully remove an allied player, you need to both remove them from this table and remove the alliance role from them in Discord's member list.

This table also supports search (by player name, Discord ID, or guild) and column sorting. It is paginated with the same 25/page default.

🔧 Troubleshooting

Problem Cause Solution
"Alliance system is not configured" Setup has not been run yet Run /alliance setup with the correct role and category
"Your guild is not part of this alliance" The player's guild has not been added yet Management must run /alliance add-guild or add the guild via the dashboard first
"Player not found" when accepting The player may have changed their name, or the Albion API is down Ask the player to resubmit. If the API is down, try again later
"Player's guild is no longer in the alliance" at accept time The player left their guild or their guild was removed between the request and the approval Do not accept. The request must be denied. The player must rejoin an allied guild and resubmit
No verification channel was created The verification category might have too many channels, or the bot lacks permission to create channels in that category Check bot permissions for the verification category (needs Manage Channels, Send Messages, View Channel)
Bot cannot change the player's nickname after accepting The player has a higher role than the bot, or nickname changes are restricted The acceptance still goes through. The bot logs a warning. Move the bot's role above ally roles in your server settings
Ally still has the alliance role after being removed from the table Dashboard removal only deletes the database record, not the Discord role Manually remove the alliance role from the player in Discord, then remove them from the dashboard table