Alliance Auth Discord Bot

Common errors

• ModuleNotFoundError: No module named 'aadiscordbot.providers.esi'

  cause Attempting to import or use the internal ESI provider after upgrading to version 5.0.0, where it was removed.
  fix Remove all references to `aadiscordbot.providers.esi` from your custom cogs and use an external ESI library or implement your own API calls instead.

• RuntimeError: You must run the bot in a Django environment.

  cause The `python manage.py runbot` command was executed outside of a valid Django project context (e.g., not from the directory containing `manage.py`) or before Django is fully set up.
  fix Navigate to your Django project's root directory (where `manage.py` is located) and ensure your Django `settings.py` is correctly configured before running `python manage.py runbot`.

• discord.errors.Forbidden: 403 Forbidden (error code: 50001): Missing Access

  cause The Discord bot token provided to `AABOT_TOKEN` does not have the necessary permissions enabled in the Discord Developer Portal, or the bot has not been granted required permissions in the Discord server.
  fix Go to the Discord Developer Portal, select your bot, and ensure all necessary Gateway Intents are enabled (e.g., Message Content Intent, Privileged Intents). Also, ensure the bot has the required permissions in the Discord server settings.

• Command 'my_command_name' is not found

  cause A custom cog containing the command was not loaded correctly, or the bot's prefix is incorrect.
  fix Verify that your custom cog's module path is correctly listed in `AABOT_COG_PATH` in `settings.py`. Check for any errors during bot startup that indicate a cog failed to load. Ensure you are using the correct command prefix defined by `AABOT_PREFIX`.

Warnings

• breaking The internal ESI provider has been removed in version 5.0.0. If you had custom cogs or extensions that relied on `aadiscordbot.providers.esi` for EVE Online ESI data, they will no longer function.
  Fix: Migrate your custom cogs to use an external ESI client library (e.g., PyESI) or implement your own OpenAPI client for ESI calls. The library now encourages users to roll their own client.
• breaking Version 4.0.0 introduced significant changes to custom task functionality and helper modules for external services. While not all changes are directly breaking, custom implementations relying on older patterns for tasks or inter-module communication might need updates.
  Fix: Review the official documentation and GitHub README for 4.0.0+ regarding 'Running Custom Bot Context Tasks' and 'Using AA-Discordbot from my Project' to adapt your code to the new helper functions and task mechanisms.
• gotcha allianceauth-discordbot requires Python 3.8 or higher. Attempting to install or run the bot with older Python versions will result in dependency resolution failures or runtime errors.
  Fix: Ensure your environment uses Python 3.8 or a newer compatible version (e.g., Python 3.9, 3.10, 3.11).
• gotcha When developing custom cogs, ensure that `aadiscordbot` and your custom cog's Django app are correctly listed in `INSTALLED_APPS` and `AABOT_COG_PATH` in your Django `settings.py`. Forgetting this is a common cause of cogs not loading.
  Fix: Double-check your `settings.py`: `INSTALLED_APPS = ['aadiscordbot', 'your_app']` and `AABOT_COG_PATH = ['your_app.cogs']` (where 'your_app.cogs' is the Python import path to your cogs module/directory).

Install

• pip install allianceauth-discordbot Install latest stable

Imports

• commands

  from discord.ext import commands

  Standard discord.py commands module for creating cogs and commands.
• has_perm

  from aadiscordbot.cogs.utils.decorators import has_perm

  Decorator for checking Alliance Auth permissions on bot commands.
• AABot
  wrong:

  from aadiscordbot.bot import DiscordBot

  correct:

  from aadiscordbot.bot import AABot

  The main bot class was renamed from DiscordBot to AABot in earlier versions to avoid conflicts and improve clarity.

Quickstart

To quickly get started with allianceauth-discordbot, you need a running Alliance Auth (Django) project. This example shows how to define a simple custom cog within one of your Django applications. This cog provides two basic commands: `!myhello` (requires Alliance Auth 'basic_access' permission) and `!myping`. The bot is then run using `python manage.py runbot` after configuring `AABOT_TOKEN` and `AABOT_COG_PATH` in your Django `settings.py`.

import discord
from discord.ext import commands
from aadiscordbot.cogs.utils.decorators import has_perm

# This cog should be placed within a Django app included in INSTALLED_APPS
# and its path added to AABOT_COG_PATH in your Django settings.

class MyCustomCog(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.hybrid_command(name="myhello")
    @has_perm("aadiscordbot.basic_access") # Requires 'Basic Access' permission in Alliance Auth
    async def my_hello_command(self, ctx: commands.Context):
        """Greets the user from Alliance Auth bot."""
        await ctx.send(f"Hello from your custom cog, {ctx.author.display_name}!", ephemeral=True)

    @commands.hybrid_command(name="myping")
    async def my_ping_command(self, ctx: commands.Context):
        """Responds with the bot's latency."""
        await ctx.send(f"Pong! {round(self.bot.latency * 1000)}ms", ephemeral=True)

async def setup(bot):
    # This 'setup' function is called by the bot to load the cog.
    await bot.add_cog(MyCustomCog(bot))

# To run the bot, ensure it's configured in your Django settings (settings.py):
# INSTALLED_APPS = [
#     ...,
#     'aadiscordbot',
#     'my_django_app' # Where your custom cogs reside
# ]
# 
# AABOT_TOKEN = os.environ.get('AABOT_TOKEN', 'YOUR_DISCORD_BOT_TOKEN')
# AABOT_PREFIX = '!'
# AABOT_COG_PATH = ['my_django_app.cogs'] # List of paths to your cog modules
#
# Then, from your Django project root:
# python manage.py runbot