Discord Integration
Connect your Discord server to vAMSYS for automatic role assignment, nickname management, and VA notifications.
The vAMSYS Discord bot connects your Discord server to your Virtual Airline. It automatically assigns roles based on pilot ranks, manages member nicknames, and posts notifications for alerts, NOTAMs, badge awards, PIREPs, flights, and daily statistics.
Subscription Required
Discord integration is only available to airlines with an active subscription. It is not accessible during the trial period.
What the Bot Does
Assigns Discord roles based on pilot ranks — when a pilot is promoted, their Discord roles update automatically
Sets member nicknames using vAMSYS data (name, Pilot ID, or both)
Posts notifications to designated channels — alerts, NOTAMs, activities, badge awards, PIREP reviews, bookings, departures, landings, and daily VA statistics
Removes pilots from the Discord server when they are banned, removed for inactivity, or leave the VA
Supports multiple Virtual Airlines in a single Discord server
Setting Up the Bot
Setup is done partly in Discord and partly in Orwell. You need Manage Server permission on your Discord server (the server owner should handle the initial invite).
Step 1: Open Discord Settings in Orwell
Go to HQ → Settings → Discord Settings. This page shows the setup wizard and your airline's setup token.
Step 2: Invite the Bot
Click the Invite Bot button on the Discord Settings page. This opens the Discord authorization screen. The server owner (or someone with Manage Server permission) should authorize the bot. Do not untick any permissions — the bot needs Manage Roles, Manage Nicknames, Send Messages, Manage Messages, and View Channel to function.
Step 3: Link the Bot
In any channel on your Discord server, run the /link command. A dialog appears asking for an Airline Token. Copy the token shown in Orwell (Step 3 of the setup wizard) and paste it in. The bot verifies its permissions and links your server.
Step 4: Verify the Connection
Back in Orwell, click Check Connection. If successful, the page refreshes and shows your Discord channels and roles in the configuration form below. You can now set up notification channels and rank role mappings.
Notification Channels
Once the bot is connected, you can assign Discord channels for various types of notifications. Each channel also has an optional role mention — when a notification is posted, the specified role is @mentioned so those members get pinged.
Notification | What Is Posted |
|---|---|
Alerts | When a new Alert becomes visible. Checked every 5 minutes. |
NOTAMs | When a new NOTAM becomes visible. Checked every 5 minutes. |
Activities | When a new Activity starts showing. Checked every 5 minutes. |
Badge Awards | When a pilot earns a badge. |
PIREP Review | When a PIREP needs staff review. Best pointed at a staff-only channel. |
Booking / Departure / Landing | When a pilot books a flight, takes off, or lands. Each has its own channel. |
VA Statistics (Full) | Detailed daily statistics posted at midnight (your VA timezone). Best suited for a staff channel. |
VA Statistics (Simple) | Summary daily statistics posted at midnight. More suitable for a public channel. |
All notification channels are optional. If you leave a channel empty, that notification type is simply not sent.
Pilot Rank Roles
Map each of your VA ranks to one or more Discord roles. When a pilot is promoted in vAMSYS, the bot automatically updates their Discord roles to match. Create the roles in Discord first, then select them on the Discord Settings page in Orwell.
Role Hierarchy
The vAMSYS Bot's role must be positioned above all pilot rank roles in your Discord server's role list. The bot cannot assign roles that are at or above its own level. If you see permission errors, check the role order in Discord Server Settings → Roles.
Each VA in a shared Discord server must use unique roles — the same Discord role cannot be assigned to ranks from different airlines.
Auto-Assign on Join
Enable the Automatically Assign toggle to have the bot assign roles and set nicknames automatically when a pilot joins your Discord server — provided they have already linked their Discord account to vAMSYS. If they have not linked yet, the bot sends them a message with a link to do so.
Bot Commands
All commands are run in Discord, not in Orwell. Most require Manage Server permission.
Command | Permission | Description |
|---|---|---|
| Manage Server | Link your Discord server to a vAMSYS airline using the setup token from Orwell |
| Manage Server | Unlink the server from all connected airlines. Existing roles are not removed. |
| Manage Server | Open the server configuration panel to set nickname format, separator, and a staff notification channel |
| Server Owner | Create a customizable button that members click to request their pilot roles and nickname |
| Manage Server | Bulk re-sync all member roles and nicknames with vAMSYS. Has a 6-hour cooldown. Supports a dry-run preview. |
| Manage Server | Run diagnostic checks on the bot — database connection, API connectivity, permissions, and uptime |
| Everyone | Check bot latency |
Nickname Configuration
Use /config in Discord to set how member nicknames appear. There are four formats:
Format | Example |
|---|---|
Name - Pilot ID (default) | John Smith - ABC1234 |
Pilot ID - Name | ABC1234 - John Smith |
Name Only | John Smith |
Pilot ID Only | ABC1234 |
For formats that include both name and Pilot ID, you can choose a separator: space, dash (default), pipe, forward slash, backslash, or comma.
Nicknames are truncated to 32 characters (Discord's limit) — the bot removes words from the end of the name while preserving the Pilot ID suffix. Nickname changes only take effect on new role requests; existing members must click the role request button again to update.
How Pilots Get Their Roles
There are two ways pilots receive their Discord roles:
Role Request Button
Use /setup-role-button (server owner only) to create a button in a channel of your choice. Members click it, the bot looks up their vAMSYS account via their linked Discord, and assigns the correct roles and nickname. If a pilot belongs to multiple VAs in the same server, they choose which Pilot ID to display — but they receive roles from all VAs regardless.
If a member's Discord account is not linked to vAMSYS, the bot directs them to link it at https://auth.vamsys.io/user/social.
Automatic on Join
When Automatically Assign is enabled in Orwell, the bot handles new members joining the server:
Linked and a pilot — roles and nickname are assigned automatically. A welcome message is posted briefly in the first text channel.
Linked but not a pilot — the bot sends a message explaining they are not a pilot in any of the server's linked VAs.
Not linked — the bot sends a message (via DM or in-channel) with a link to connect their Discord account.
Automatic Updates
Once set up, the bot stays in sync with vAMSYS automatically:
Rank promotion — Discord roles are updated when a pilot's rank changes
Name change — Discord nickname is updated when a user changes their public name preference in vAMSYS (polled every 30 seconds)
Pilot removal — when a pilot is banned, removed for inactivity, or leaves the VA, the bot removes them from the Discord server
Multiple Airlines Per Server
One Discord server can host multiple Virtual Airlines. Each VA admin runs /link with their own token. Pilots who are members of multiple VAs in the same server receive roles from all of them. Nickname format and notification channel are server-level settings shared by all linked airlines; rank-to-role mappings and auto-assign are configured per airline in Orwell.
Staff Notification Channel
Separate from the VA notification channels configured in Orwell, the bot has its own staff notification channel set via /config in Discord. This receives operational messages: successful role assignments, permission errors, and system events. Point it at a staff-only channel.
Permissions
The bot requires these Discord permissions to function:
Manage Roles — to assign and remove pilot rank roles
Manage Nicknames — to set member nicknames
Send Messages — to post notifications and respond to commands
Manage Messages — to clean up temporary welcome messages
View Channel — to see channels it needs to post in
The bot's role must be positioned above all pilot rank roles in your Discord role hierarchy. It cannot manage the server owner or users with roles higher than its own (Discord limitation).
Removing the Bot
If you remove the bot from your Discord server (kick or ban it), the airline is automatically unlinked from vAMSYS. Existing roles are not removed from members — you need to clean those up manually in Discord. To re-enable, invite the bot again and run /link with a fresh token.
Orwell Permission
Access to the Discord Settings page in Orwell requires the Discord Settings staff permission.
Related
Thank you for your feedback!
Your input helps us improve our documentation.
