{"id":9454,"library":"allianceauth-discordbot","title":"Alliance Auth Discord Bot","description":"allianceauth-discordbot is a modular Discord bot designed to integrate deeply with Alliance Auth, a Django-based authentication system for EVE Online alliances. It provides features like user lookup, permissions management, and custom commands, leveraging Django's ORM and authentication. The current version is 5.0.0, and it maintains an active release cadence, often pushing minor updates and bug fixes.","status":"active","version":"5.0.0","language":"en","source_language":"en","source_url":"https://github.com/Solar-Helix-Independent-Transport/allianceauth-discordbot","tags":["django","discord","bot","eveonline","allianceauth"],"install":[{"cmd":"pip install allianceauth-discordbot","lang":"bash","label":"Install latest stable"}],"dependencies":[{"reason":"It is a Django application and requires a running Django project.","package":"Django","optional":false},{"reason":"It is a Discord bot built on discord.py.","package":"discord.py","optional":false},{"reason":"It is an extension for Alliance Auth.","package":"AllianceAuth","optional":false}],"imports":[{"note":"Standard discord.py commands module for creating cogs and commands.","symbol":"commands","correct":"from discord.ext import commands"},{"note":"Decorator for checking Alliance Auth permissions on bot commands.","symbol":"has_perm","correct":"from aadiscordbot.cogs.utils.decorators import has_perm"},{"note":"The main bot class was renamed from DiscordBot to AABot in earlier versions to avoid conflicts and improve clarity.","wrong":"from aadiscordbot.bot import DiscordBot","symbol":"AABot","correct":"from aadiscordbot.bot import AABot"}],"quickstart":{"code":"import discord\nfrom discord.ext import commands\nfrom aadiscordbot.cogs.utils.decorators import has_perm\n\n# This cog should be placed within a Django app included in INSTALLED_APPS\n# and its path added to AABOT_COG_PATH in your Django settings.\n\nclass MyCustomCog(commands.Cog):\n    def __init__(self, bot):\n        self.bot = bot\n\n    @commands.hybrid_command(name=\"myhello\")\n    @has_perm(\"aadiscordbot.basic_access\") # Requires 'Basic Access' permission in Alliance Auth\n    async def my_hello_command(self, ctx: commands.Context):\n        \"\"\"Greets the user from Alliance Auth bot.\"\"\"\n        await ctx.send(f\"Hello from your custom cog, {ctx.author.display_name}!\", ephemeral=True)\n\n    @commands.hybrid_command(name=\"myping\")\n    async def my_ping_command(self, ctx: commands.Context):\n        \"\"\"Responds with the bot's latency.\"\"\"\n        await ctx.send(f\"Pong! {round(self.bot.latency * 1000)}ms\", ephemeral=True)\n\nasync def setup(bot):\n    # This 'setup' function is called by the bot to load the cog.\n    await bot.add_cog(MyCustomCog(bot))\n\n# To run the bot, ensure it's configured in your Django settings (settings.py):\n# INSTALLED_APPS = [\n#     ...,\n#     'aadiscordbot',\n#     'my_django_app' # Where your custom cogs reside\n# ]\n# \n# AABOT_TOKEN = os.environ.get('AABOT_TOKEN', 'YOUR_DISCORD_BOT_TOKEN')\n# AABOT_PREFIX = '!'\n# AABOT_COG_PATH = ['my_django_app.cogs'] # List of paths to your cog modules\n#\n# Then, from your Django project root:\n# python manage.py runbot","lang":"python","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Ensure your environment uses Python 3.8 or a newer compatible version (e.g., Python 3.9, 3.10, 3.11).","message":"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.","severity":"gotcha","affected_versions":"<=3.8.0"},{"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).","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import or use the internal ESI provider after upgrading to version 5.0.0, where it was removed.","error":"ModuleNotFoundError: No module named 'aadiscordbot.providers.esi'"},{"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`.","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.","error":"RuntimeError: You must run the bot in a Django environment."},{"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.","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.","error":"discord.errors.Forbidden: 403 Forbidden (error code: 50001): Missing Access"},{"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`.","cause":"A custom cog containing the command was not loaded correctly, or the bot's prefix is incorrect.","error":"Command 'my_command_name' is not found"}]}