Following document describes the setup process of Guilds on GuildPlanner.Pro (“WebSite”).
As previously explained in Getting Started page, the titles we support might support Web API and/or UI-Addon API. And based on this, during our regular Data-Import process, among many, we also import Guild data.
Due to security concerns, Guild data is imported via the Data-Imports coming through guildmasters’ accounts. Especially in UI-Addon API based games (e.g. ESO), where it is easy to fake an Addon data file. As the guilds on WebSite are tightly synced with their associated Discord servers, a fabricated data-set import would easily lead to the unwanted privilege grants, both for related guilds on WebSite and their associated Discord Servers. As such, in order to avoid this kind of high-risk situations, WebSite only accepts Guild data via guildmaster accounts. WebSite does not process such data from any other guild roles, including guild officers.
When a guild data is imported for the first time, WebSite checks all members of the guild against our database. If a WebSite member is found among our users, they are linked to the guild with their actual Ingame Guild Roles. All guild members then see the guild under My Guilds dropdown on the WebSite:
At this stage, this new guild is Inactive and the guildmaster in question can start setting up their guild for usage on WebSite.
First order of business is to associate a Discord Server with the new guild.
Only Discord server owners and administrators can associate a Discord server with a guild!
In order to do that, on guild Setup & Configuration page, the guildmaster selects one of the Discord servers they own or administer, associating that server with the guild in question:
Once done, they will be asked to invite GuildPlanner.Pro Discord Bot to the server they just associated with the guild:
This process is straight forward: through two OAuth authorization stages, the bot is invited and authorized.
These permissions are paramount for the Bot’s operations. As such, please do not disable any permissions at this stage, or later on!
Question: Why Bot requires Manage Server permission, which is very high permission to give?
Answer: We always strive to request as less as possible privileges from discord administrators. Unfortunately, in this case, as you noticed in the previous screenshot, we requested Create commands in a Server permission/scope. To be able to verify our Bot’s granted scopes (such as this Create commands in a Server), we need to query for your Discord server’s so called “Integrations”. To access these Integrations data (which, in a nutshell, is a detailed list of all bots on your server, including our own), Bot needs to have Manage Guild (i.e. “Manage Server”) permission. We need Integrations data in order to avoid unexpected errors in our systems, which would cause unnecessary interruptions, even the deactivation of your guild on WebSite due to missing permissions/scopes.
At this point, the guild leader can fix the problem by repeating OAuth Authorization procedure.
This is important! On Discord, a user can only manage members belonging to the roles below their own role. Since Bot handles member roles automatically (e.g. via Data-Imports we regularly upload, the actions we regularly perform on WebSite and Discord etc), keeping guild members in sync between WebSite and Discord server, it is important its integration role is at the top of all Discord roles, including officer ones!
Doing so, will not endanger the server-owner role, as it is the highest role on Discord and can’t be managed by any other party! This actually is the reason why certain Bot commands (e.g./ign2name
) won’t work on server-owner user accounts.
To fix this, simply open Server Settings on Discord, and move GuildPlanner.Pro role to the top of the list, then save that configuration:
Its a widely known practice to create a separate role called “Bots” or similar and group all your Discord server bots under it. For security reasons, we recommend not to assign any privileges to such roles!
If later on the Bot permissions are revoked, or Bot’s integration role removed from the top of the server role list, the guild in question will be automatically suspended and guild leader be notified via email.
All of the steps from here on are optional and can be changed after the guild is activated.
TODO: Create docs about Communities
Read more here about Progression Tiers.
Read more here about Participants.
Read more here about Guild Roles.
Clubs feature has been deprecated as of May 1st, 2023.