Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/thegamecracks/theticketbot
A ticket bot built on Discord's native threads.
https://github.com/thegamecracks/theticketbot
discord discord-py gettext i18n python python-package ticketing-system
Last synced: about 3 hours ago
JSON representation
A ticket bot built on Discord's native threads.
- Host: GitHub
- URL: https://github.com/thegamecracks/theticketbot
- Owner: thegamecracks
- License: mit
- Created: 2024-06-03T03:37:48.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2024-10-23T19:14:48.000Z (26 days ago)
- Last Synced: 2024-10-24T05:46:14.395Z (26 days ago)
- Topics: discord, discord-py, gettext, i18n, python, python-package, ticketing-system
- Language: Python
- Homepage:
- Size: 481 KB
- Stars: 2
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# theticketbot
[](https://pypi.org/project/theticketbot/)
[](https://black.readthedocs.io/en/stable/)
[](https://microsoft.github.io/pyright/#/)
A simple Discord bot for handling ticket systems using channel threads.
## Resources
- Changelog: https://github.com/thegamecracks/theticketbot/blob/main/CHANGELOG.md
- Issues: https://github.com/thegamecracks/theticketbot/issues?q=
- Milestones: https://github.com/thegamecracks/theticketbot/milestones
- Releases: https://github.com/thegamecracks/theticketbot/releases
## Contributing
Before submitting any changes, please read and follow the [Contributing Guide]!
[Contributing Guide]: https://github.com/thegamecracks/theticketbot/blob/main/CONTRIBUTING.md
Want to help out by adding translations? This bot stores them in the [locales/]
directory. You can [fork this repository], create a new branch, commit your
FTL files there, and make a pull request!
[locales/]: https://github.com/thegamecracks/theticketbot/tree/main/src/theticketbot/locales/
[fork this repository]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects
## Usage
I am not hosting a public instance of this bot, and I have no endorsements
for any bots that claim to host this project. Sorry for the inconvenience!
If you're technically inclined, you can host this bot yourself.
With Python 3.11+, you can set up this bot by following these steps:
1. Create a virtual environment and install theticketbot from PyPI:
```sh
python -m venv .venv
source .venv/bin/activate # or .venv\Scripts\activate on Windows
pip install theticketbot
```
Alternatively, you can install the latest, in-development version using Git:
```sh
pip install git+https://github.com/thegamecracks/theticketbot
```
2. Start the bot:
```sh
theticketbot
# or
python -m theticketbot
```
You will be prompted to enter your bot token so it can be written to
a [config.toml] file in a user-specific directory. After this, the bot
will automatically synchronize its application commands for the first time.
On subsequent updates, application commands will automatically be synced
as needed. You can also use `theticketbot --sync` to manually synchronize
the bot's application commands again.
Alternatively, you can use the "<@mention> sync" text command once your bot
is in a server to synchronize application commands.
3. Invite your bot to a server.
Once logged in, the bot will print out an invite link with the appropriate
permissions. If you want to manually generate an invite link, you can go to
the [Applications](https://discord.com/developers/applications) > OAuth2
page, select only `bot` for the scope, then in the permissions list below,
select at least the following permissions:
- Read Messages/View Channels
- Send Messages
- Create Private Threads
- Send Messages in Threads
- Embed Links
- Attach Files
A few other permissions like Manage Threads and Mention Everyone
may be useful, but are not required.
Leave the Integration Type as "Guild Install", and copy the generated URL
at the bottom. You can now use that URL to invite the bot or let others
invite the bot if "Public Bot" is ticked in the Bot page.
[config.toml]: https://github.com/thegamecracks/theticketbot/blob/main/src/theticketbot/config_default.toml
To set up an inbox, first post a message with the content you would like your
inbox message to have. This message may include image attachments, or custom
embeds sent by a webhook as long as the message has no content.
Afterwards, use `/inbox create` to choose the channel you want your inbox posted in.
You will then be prompted to select a message to be sent with your inbox.
You can then right-click or long tap the message you sent, open the Apps menu,
and use `Select this message`.
New tickets will be created in the same channel as the inbox by default.
If you want to customize this, you can specify a different channel with
the `/inbox create ` parameter, or use the `/inbox destination`
command to re-route new tickets from an existing inbox.
When choosing a channel, the bot must be able to view, send messages,
and create private threads in that channel.
Each inbox has a set of staff that will be mentioned when a new ticket is created.
Any members or roles that you explicitly grant Manage Threads in the channel's
permissions will be automatically added as staff for the inbox, but you can
change this later with `/inbox staff`.
Tickets are managed using Discord's native thread functionality.
Closing the thread archives it, preserving their messages without
needing a separate transcript.
Staff with the Manage Threads permission can also add and remove members,
useful for bringing in relevant members or for removing the ticket owner
to allow internal discussions inside the ticket. Tickets can be renamed
to make them more easily searchable, and can be deleted permanently if desired.
If the owner leaves or is removed from their ticket, the bot will automatically
archive the ticket. Staff are free to re-open it afterwards.
The bot will also lock the ticket to prevent further discussion if it has
the Manage Threads permission, which can be set on a per-channel basis.
In this case, staff must have the Manage Threads permission to re-open the
ticket.
If you have multiple inboxes in one channel, any staff with the Manage Threads
permission will be able to view and manage all threads in that channel
even if they aren't listed as staff for those inboxes.
If maintaining privacy is important, inboxes should be organized into
different channels according to which staff should be allowed to view
the threads of those inboxes. This layout can look like:
- `#mod-tickets` (moderators have Manage Threads)
- `General Support`
- `Member Reports`
- `#admin-tickets` (admins have Manage Threads)
- `Ban Appeals`
- `Feedback And Suggestions`
- `Staff Applications`
Alternatively, you can choose to not grant the Manage Threads permission to staff.
This will prevent them from closing tickets, inviting other members,
or sending messages in locked tickets.
This also means future staff members won't be able to view older tickets.
With all the above said, the recommended workflow for most community servers
is to give your staff and the bot Manage Threads permission for a single channel.
When staff needs to close a ticket, they should remove all invited members first,
then the ticket owner last to automatically trigger archival and locking of the ticket.
Staff are free to continue conversations in the ticket if needed, which
automatically re-opens it.
If you need to deviate from this workflow to accommodate alternative requirements,
like allowing ticket owners to read their past tickets or having multiple staff
roles with different management permissions, feel free to develop and document
a new procedure for your staff team to follow.
## Customization
There are various settings that can be customized for each inbox.
When you use the below commands, you will be prompted to select the message
of the inbox that you want to change, i.e. the message that has the
Create Ticket button.
- `/inbox destination`
Route new tickets from an inbox to another channel.
- `/inbox message`
Edit the message of an inbox with a new message.
- `/inbox staff`
Inspect and manage staff members/roles for an inbox.
- `/inbox new-tickets starter`
Inspect the starting message for new tickets and optionally change it.
Allowed placeholders are:
- `$author`
The ticket owner's mention. Must be included in the message
for the owner to be invited.
- `$staff`
A list of mentions for the inbox's staff members and roles.
Must be included in the message for staff to be invited
if they do not have the Manage Threads permission.
For example, a starting message for a moderation inbox might look like:
```
$author Thank you for creating a moderation ticket! $staff will be with you shortly.
```
Note that role mentions require either the role to be mentionable or the bot
to have the *Mention all roles* permission in the inbox's channel.
- `/inbox new-tickets name`
Inspect and manage the default name for new tickets.
Allowed placeholders are:
- `$year`
- `$month`
- `$day`
- `$author`
The ticket owner's display name.
- `$counter`
An incrementing 4-digit counter starting from 0001.
Upon exceeding 9999, the counter will overflow back to 0000.
The counter is not guaranteed to be sequential and may skip
if the bot is unsuccessful in creating a ticket.
Thread names will be limited to 100 characters by Discord.
## Ticket Limits
Each inbox limits users to a minimum of 1 thread every 60 seconds.
If a channel slowmode above 60 seconds is set, the inbox will match
that delay to limit new tickets.
Inboxes will also try to limit users to 1 active thread per inbox,
but may not be guaranteed due to technical limitations.
## Encryption
> [!WARNING]
>
> This feature is experimental and may be removed in the future.
>
> This bot does not store any sensitive data on users and persists only
> the bare minimum needed to function, so encrypting the database is not
> significantly useful in contrast to protecting your bot's token.
>
> Encryption is also not a substitute for properly configured file permissions.
> You should ensure that other users on your system are not able to read the
> database or the config.toml file. Other secure methods of transferring
> these files between systems should be applied as well.
>
> Finally, derived keys are not cached by the bot, meaning that every connection
> made to the database, which can be several connections per command, requires
> repeating the same key derivation which may be performance intensive.
This bot supports using an encrypted SQLite database with encryption extensions
like [SQLiteMultipleCiphers], [SQLCipher], or [SEE]. On a Windows system,
pre-built DLLs can be found for SQLiteMultipleCiphers in their
[releases](https://github.com/utelle/SQLite3MultipleCiphers/releases) page.
With one of the encryption extensions installed, you can use it to encrypt
the database and then add the decryption to theticketbot. Run the bot once
so your database file is created - use `theticketbot --dump-config` to locate it
if you didn't explicitly set a `db.path` in your config - then open the database
using the SQLite shell from your encryption extension and encrypt it:
```sql
$ sqlite3 theticketbot.db
SQLite version 3.46.0 2024-05-23 13:25:27 (UTF-16 console I/O) (SQLite3 Multiple Ciphers 1.8.5)
Enter ".help" for usage hints.
sqlite> PRAGMA rekey = 'Hello world!';
sqlite> .exit
```
After that, open your config.toml file and add a template for the pragma
to decrypt your database like so:
```toml
[db]
key_template = "PRAGMA key = '{}'"
```
A more complex encryption setup might look like:
```toml
[db]
pragmas = ["PRAGMA cipher = sqlcipher", "PRAGMA kdf_iter = 512000"]
key_template = "PRAGMA hexkey = '{}'"
```
At startup, you will be prompted to enter the database key.
Once the database is opened, all pragmas will be executed in order.
To change the encryption key later, shut down the bot and then manually execute
the necessary pragmas according to the documentation for your encryption extension.
If you get an error like `file is not a database` or `unsupported file format`,
this may mean that the bot was unable to decrypt the database, or that the database
hasn't yet been encrypted. In this case, please double check your pragmas and/or
try to manually decrypt your database in an SQLite shell.
During encryption, if you get `Rekeying is not supported in WAL journal mode`,
you will need to run `PRAGMA journal_mode = delete;` before rekeying.
[SQLiteMultipleCiphers]: https://utelle.github.io/SQLite3MultipleCiphers/
[SQLCipher]: https://www.zetetic.net/sqlcipher/documentation/
[SEE]: https://sqlite.org/com/see.html
## License
This project is written under the [MIT] license.
[MIT]: https://github.com/thegamecracks/theticketbot/blob/main/LICENSE