Kaab'ot is a pretty little Discord bot that provides knowledge related to Islam and from the Holy Quran. Developed as a modern, lightweight replacement to other similar bots.
Note
This project has reached maturity. As such, there won't be any new features. The public instance of the bot will continue to be maintained for the foreseeable future (as well as bugfixes and general upkeep of functionality).
-
Cite verses from the Holy Quran with the
/verse
command. Provides English, Arabic, and Urdu translations automatically.- Analyze the individual Arabic words of each verse by passing the optional
analyse
parameter. - Verses provided from OpenQuran, an easy-to-use Quran search engine.
- Analyze the individual Arabic words of each verse by passing the optional
-
Cite hadiths from trusted Muslim scholars with the
/hadith
command.- Give it a single book name and verse reference (e.g.
bukhari:6594
) and the bot will post the relevant paragraph into chat.
- Give it a single book name and verse reference (e.g.
-
Retrieve interesting commentary of the Holy Quran with the
/5v
command. Sources commentary from the Five Volume Commentary collection (thus5v
).- Give it a single verse (e.g.
1:1
) and the bot will post the relevant page of the verse into chat.
- Give it a single verse (e.g.
-
On-demand retrieval of Salat timings with the
/salat
command, as well as an opt-in notifier/reminder for prayers with configurable location(s).- Uses Nominatim for geolocalization. If you are hosting Kaab'ot yourself, you will also have to host your own Nominatim instance.
- Experimental feature. Must be manually enabled by administrators of self-hosted bots.
-
Fetch Friday Sermons from Muslim Television Ahmadiyya International.
- Provides both a permalink on MTA and a direct download link to a 1920x1080 (full HD) MP4 of the sermon.
- Pass
list
parameter to retrieve the last 10 Friday sermons.
-
Retrieval of the Bai'at (initiation into Islam) form, as well as the Conditions of Bai'at, with the
/baiat
command.- Give it a single index from 1 until 10 and the bot will post the relevant Condition of Bai'at. If no index is provided, it will provide an explanation of Bai'at and a link to the form.
-
Access hundreds of selected writings and books from scholars, caliphs and Hazrat Mirza Ghulam Ahmad (a.s.).
- Local library can be built from alislam.org with the
npm run books
command. Automatically downloads all PDF files too. - Search results can be curated with
skip
andlimit
parameters to prevent listing of 100+ books all at once in a single message. /library search
to search through the library with a keyword (e.g., 'jesus')./library get
retrieves a book from its unique identifier. Displays a description, author information, and a download link to an English PDF./library download
uploads a PDF of the book directly into the Discord channel./library author
searches for, and displays information about, an author./library list-books
lists the books from an author./library list-authors
lists all currently indexed authors.
- Local library can be built from alislam.org with the
-
Convert between Gregorian and Hijri dates using
/calendar
, understands both precise (e.g., "March 10, 2024") and imprecise/relative (e.g., "next friday", "2 weeks from now", etc.) inputs.
This project requires Node.js 20 or above. Create a Discord bot first, making sure to invite it to your guild(s) immediately after. Then, clone this repository into an empty folder, and create a .env
file with the following values:
# Insert your bot's client ID here.
DISCORD_BOT_CLIENT="..."
# Insert your bot's token here.
DISCORD_BOT_SECRET="..."
Afterwards, run the following commands and the bot will launch automatically:
npm run build
# or "pnpm build" if you have pnpm.
npm run books
# Optional, see below!
npm run start
# or "pnpm start" if you have pnpm.
To enable use of /library
commands, you need to run npm run books
after installing dependencies. The books
command will automatically fetch most writings from alislam.org's online library and cache them into the library
folder, as to prevent users from constantly making requests to alislam.org through the bot. The resulting library will be quite large, around ~1 GB.
Not all writings will be retrieved (as not all books are available in PDF format), and building the library is entirely optional, especially if you are not comfortable with scraping the website. However, the /library
command will not be available if you do not do so.
To enable use of /salat
commands (and anything else that supports geolocalization queries), you have to provide a URL to a Nominatim backend as the geolocalizationUrl
field of your settings.json
file. The bot will automatically detect the setting and enable the relevant commands.
The public instance of Kaab'ot uses its own self-hosted backend, but it is exclusively for the use of the public instance (as to avoid overuse from other bots). You will have to host your own if you want to self-host Kaab'ot. If you want to avoid this, just add the public instance of the bot to your server instead.
If you want to self-host Nominatim, please read this guide. I highly recommend using a Docker container on a cheap VPS with a lot of storage so you can import the most geolocalization data possible with minimal setup.
Alternatively, you may use OpenStreetMap's public Nominatim backend for your own self-hosted bot, but do note that it is subject to strict rate limits and you will have to display attribution somewhere in your server, which may not be ideal. For more information, read their usage policy.
This work is licensed under the GNU Affero General Public License (AGPL) Version 3. For more information, consult the license file.