Connect Discord to Agora: sign-in, bot and roles

In short. Your Discord application does two things. Sign-in (mandatory) lets your members sign in to your Hub with their Discord account. The bot (optional) automatically gives the right Discord role when a member joins a group, and sends a private message when their application is decided.

Before you start #

• The getting-started setup is done: your Discord application already exists.
• You are an administrator of the Hub (your Agora site). To change the sign-in ID and secret, you must also be the installation's owner.
• To invite the bot, you have the Manage Server permission on your Discord server.
• A word stops you? It is explained in the glossary.

Sign-in (OAuth), already set during setup #

OAuth is the standard way of "signing in with Discord": Discord tells Agora who the member is, with no password to create.

It is set during the getting-started setup. You find it again in Administration → Configuration → Discord connection, Discord login (OAuth) block: Client ID (your application's public identifier) and Client Secret (its secret). The value saved here applies without a restart.

<!-- CAPTURE C-020 -->

Agora asks Discord for two permissions, identify (your name, avatar and identifier) and email (your email), nothing else: a member's presence on your Discord server is checked by the bot, not by their sign-in.

Only the installation's owner can change this application's ID and secret, because it decides who can sign in to the site. The bot can be set by any administrator. See Manage members.

The redirect URL must be declared at Discord character for character: same protocol, same host, same port. Discord accepts http:// and IP addresses. See Discord sign-in fails.

Connect the bot (optional) #

Without the bot, everything works; only role synchronization is off. Each step below is detailed, with screenshots, in Create and set up your Discord bot.

1. In the Discord developer portal, open the same application, Bot tab, then Reset Token. Copy the bot token, a secret shown only once.
2. Still in Bot, turn on Server Members Intent. This is the switch that lets the bot see your Discord server's member list.
3. Invite the bot: OAuth2 → URL Generator, tick the bot scope and the Manage Roles permission, then open the generated URL and pick your server.
4. In Discord: Server Settings → Roles, drag the bot's role above every role it must give.
5. Copy the server ID: User Settings → Advanced → Developer Mode, then right-click the server and Copy Server ID (Discord's official help).
6. In Agora, Administration → Configuration → Discord connection, Discord bot (roles + messages) block: paste the Bot token and the Server (guild) ID, then Save.

The banner changes to "● Bot connected: name on server · N role(s) visible". The Test button checks the token, the server and what Discord would refuse at the next synchronization (bot role too low, deleted role…), without changing anything on Discord.

Link each site role to a Discord role #

Once the bot is connected, the Discord roles linked to roles section unlocks.

1. For each site role (Whitelist, Police…), pick the Discord role in the list.
2. Save.

From now on, giving a site role to a member (accepted application or an administrator's action) also gives them the Discord role. Removing the site role removes the Discord role.

A role the bot cannot give (placed above its own, or managed by an integration) is greyed out with the reason and refused on save. If you reorder roles later, the red Mappings Discord will refuse list shows it, with an Open in the Discord app button to fix it.

<!-- CAPTURE C-021 -->

You know it worked when… #

• The banner shows "● Bot connected: …".
• The Test button answers "No problem: role sync can work".
• You give a site role to a test account and it receives the matching Discord role.

If it does not work #

Go further #

• The other way round. For a group whose roles are already managed in Discord (another bot, a subscriber role), tick Sync Discord → Agora under its mapping: a member who receives the role on Discord enters the group, one who loses it leaves. This listening needs Server Members Intent (step 2); without it, Agora falls back on the audit log and the bot's role needs the View Audit Log permission. Everything is explained in Discord roles, sync and "Suspended member".

• Suspended member. The Suspended member setting decides what happens to a suspended member's Discord roles: keep them (the default), remove them during the suspension, or remove them and refuse their connection to the game server.

  <!-- CAPTURE C-022 -->

• The golden rule. A bot can never give a role placed higher than its own: it is the first cause of failure.