A heraldry-related bot, designed for the Heraldry Community.


cchardet and aiodns are also recommended to improve performance.

For convenience, these can all be installed with pip install -r requirements/main.txt.


As one may expect, this bot requires a bot account to run. Refer to the discord.py instructions on creating one for more information.

For some functionality, a Google Cloud Platform account is required, with the Custom Search and Google Drive APIs enabled. Custom search features additionally require a Programmable Search engine, since Google has discontinued general search APIs. This must have image search enabled, and it is strongly recommended that you enable the "Search the entire web" setting.

Before running, the bot requires an config.json file in the root directory containing data that it needs to run:

  • DISCORD_TOKEN: The Discord Developer API token.
  • GCS_TOKEN: The Google Cloud Platform API key. Custom Search and Google Drive must be enabled for this key.
  • GCS_CX: The Programmable Search engine identifier.
  • AR_RIJKS: The key for the Rijksmuseum API.
  • AR_EURO: The key for the Europeana Pro API.
  • AR_DGTNZ: The key for the Digital NZ API.
  • AR_SMTHS: The key for the Smithsonian API, provided by data.gov.
  • AR_DDBTK: The key for the German Digital Library/Deutsche Digitale Bibliothek API
  • DEEP_AI: The key for !textgen, from DeepAI.

Additionally, there are a number of optional settings that can be specified:

  • USE_JISHAKU: If true, load the jishaku debugger (must be installed separately).
  • OWNER_ONLY: If true, disable usage of the bot for members that are not the owner.
  • LOG_LEVEL: The numeric logging level for the bot. Defaults to 20 (INFO).
  • DB_PATH: An alternate path for the SQLite file to use, instead of the default data/db/heraldtron.db.


Once your bot is set up, use the standard Python package initialisation method (of course, use python3 if there is an overlapping python2 install):

cd path/to/heraldtron
python -m ht

Run the !help command for information about the bot's functionality.