# theticketbot
[](https://pypi.org/project/theticketbot/)
[](https://microsoft.github.io/pyright/#/)
A simple Discord bot for handling ticket systems using channel threads.
## Resources
- 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
PO files there, and make a pull request!
See [discord.py-gettext-demo's onboarding] for more information.
[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
[discord.py-gettext-demo's onboarding]: https://github.com/thegamecracks/discord.py-i18n-demo/blob/main/docs/en/onboarding.md
## 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
```
When installing from the source code like above, localizations may be
compiled using gettext's `msgfmt` program if it is available on your system.
This dependency is not needed when installing the wheel distributions
from PyPI as they already contain the localizations pre-compiled.
If you don't have gettext when installing from source, localizations
will be disabled.
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.
If you update the bot later on, you may need to run `theticketbot --sync`
to synchronize the bot's application commands again.
See the [changelog] to know if this is needed.
Alternatively, you can use the "<@mention> sync" text command once your bot
is in a server to synchronize application commands.
3. Create an invite link in the Discord Developer Portal to add your bot to a server.
In 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
[changelog]: https://github.com/thegamecracks/theticketbot/blob/main/CHANGELOG.md
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`.
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.
## 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 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
Raw data
{
"_id": null,
"home_page": null,
"name": "theticketbot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "i18n, discord, gettext, discord.py, ticketing-system",
"author": "thegamecracks",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9d/7b/9483e6a17b3eba6a5aa068d7ba10d0f03bff4a3dc7cd2490d0f49d5ab874/theticketbot-0.4.2.tar.gz",
"platform": null,
"description": "# theticketbot\n\n[](https://pypi.org/project/theticketbot/)\n[](https://microsoft.github.io/pyright/#/)\n\nA simple Discord bot for handling ticket systems using channel threads.\n\n\n\n## Resources\n\n- Issues: https://github.com/thegamecracks/theticketbot/issues?q=\n- Milestones: https://github.com/thegamecracks/theticketbot/milestones\n- Releases: https://github.com/thegamecracks/theticketbot/releases\n\n## Contributing\n\nBefore submitting any changes, please read and follow the [Contributing Guide]!\n\n[Contributing Guide]: https://github.com/thegamecracks/theticketbot/blob/main/CONTRIBUTING.md\n\nWant to help out by adding translations? This bot stores them in the [locales/]\ndirectory. You can [fork this repository], create a new branch, commit your\nPO files there, and make a pull request!\nSee [discord.py-gettext-demo's onboarding] for more information.\n\n[locales/]: https://github.com/thegamecracks/theticketbot/tree/main/src/theticketbot/locales/\n[fork this repository]: https://docs.github.com/en/get-started/quickstart/contributing-to-projects\n[discord.py-gettext-demo's onboarding]: https://github.com/thegamecracks/discord.py-i18n-demo/blob/main/docs/en/onboarding.md\n\n## Usage\n\nI am not hosting a public instance of this bot, and I have no endorsements\nfor any bots that claim to host this project. Sorry for the inconvenience!\nIf you're technically inclined, you can host this bot yourself.\n\nWith Python 3.11+, you can set up this bot by following these steps:\n\n1. Create a virtual environment and install theticketbot from PyPI:\n\n ```sh\n python -m venv .venv\n source .venv/bin/activate # or .venv\\Scripts\\activate on Windows\n pip install theticketbot\n ```\n\n Alternatively, you can install the latest, in-development version using Git:\n\n ```sh\n pip install git+https://github.com/thegamecracks/theticketbot\n ```\n\n When installing from the source code like above, localizations may be\n compiled using gettext's `msgfmt` program if it is available on your system.\n This dependency is not needed when installing the wheel distributions\n from PyPI as they already contain the localizations pre-compiled.\n If you don't have gettext when installing from source, localizations\n will be disabled.\n\n2. Start the bot:\n\n ```sh\n theticketbot\n # or\n python -m theticketbot\n ```\n\n You will be prompted to enter your bot token so it can be written to\n a [config.toml] file in a user-specific directory. After this, the bot\n will automatically synchronize its application commands for the first time.\n\n If you update the bot later on, you may need to run `theticketbot --sync`\n to synchronize the bot's application commands again.\n See the [changelog] to know if this is needed.\n\n Alternatively, you can use the \"<@mention> sync\" text command once your bot\n is in a server to synchronize application commands.\n\n3. Create an invite link in the Discord Developer Portal to add your bot to a server.\n\n In the [Applications](https://discord.com/developers/applications) > OAuth2 page,\n select only `bot` for the scope, then in the permissions list below,\n select at least the following permissions:\n\n - Read Messages/View Channels\n - Send Messages\n - Create Private Threads\n - Send Messages in Threads\n - Embed Links\n - Attach Files\n\n A few other permissions like Manage Threads and Mention Everyone\n may be useful, but are not required.\n\n Leave the Integration Type as \"Guild Install\", and copy the generated URL\n at the bottom. You can now use that URL to invite the bot or let others\n invite the bot if \"Public Bot\" is ticked in the Bot page.\n\n[config.toml]: https://github.com/thegamecracks/theticketbot/blob/main/src/theticketbot/config_default.toml\n[changelog]: https://github.com/thegamecracks/theticketbot/blob/main/CHANGELOG.md\n\nTo set up an inbox, first post a message with the content you would like your\ninbox message to have. This message may include image attachments, or custom\nembeds sent by a webhook as long as the message has no content.\n\nAfterwards, use `/inbox create` to choose the channel you want your inbox posted in.\nYou will then be prompted to select a message to be sent with your inbox.\nYou can then right-click or long tap the message you sent, open the Apps menu,\nand use `Select this message`.\n\nWhen choosing a channel, the bot must be able to view, send messages,\nand create private threads in that channel.\n\nEach inbox has a set of staff that will be mentioned when a new ticket is created.\nAny members or roles that you explicitly grant Manage Threads in the channel's\npermissions will be automatically added as staff for the inbox, but you can\nchange this later with `/inbox staff`.\n\nTickets are managed using Discord's native thread functionality.\nClosing the thread archives it, preserving their messages without\nneeding a separate transcript.\nStaff with the Manage Threads permission can also add and remove members,\nuseful for bringing in relevant members or for removing the ticket owner\nto allow internal discussions inside the ticket. Tickets can be renamed\nto make them more easily searchable, and can be deleted permanently if desired.\n\nIf the owner leaves or is removed from their ticket, the bot will automatically\narchive the ticket. Staff are free to re-open it afterwards.\n\nThe bot will also lock the ticket to prevent further discussion if it has\nthe Manage Threads permission, which can be set on a per-channel basis.\nIn this case, staff must have the Manage Threads permission to re-open the\nticket.\n\nIf you have multiple inboxes in one channel, any staff with the Manage Threads\npermission will be able to view and manage all threads in that channel\neven if they aren't listed as staff for those inboxes.\nIf maintaining privacy is important, inboxes should be organized into\ndifferent channels according to which staff should be allowed to view\nthe threads of those inboxes. This layout can look like:\n\n- `#mod-tickets` (moderators have Manage Threads)\n - `General Support`\n - `Member Reports`\n- `#admin-tickets` (admins have Manage Threads)\n - `Ban Appeals`\n - `Feedback And Suggestions`\n - `Staff Applications`\n\nAlternatively, you can choose to not grant the Manage Threads permission to staff.\nThis will prevent them from closing tickets, inviting other members,\nor sending messages in locked tickets.\nThis also means future staff members won't be able to view older tickets.\n\n## Customization\n\nThere are various settings that can be customized for each inbox.\nWhen you use the below commands, you will be prompted to select the message\nof the inbox that you want to change, i.e. the message that has the\nCreate Ticket button.\n\n- `/inbox message`\n\n Edit the message of an inbox with a new message.\n\n- `/inbox staff`\n\n Inspect and manage staff members/roles for an inbox.\n\n- `/inbox new-tickets starter`\n\n Inspect the starting message for new tickets and optionally change it.\n\n Allowed placeholders are:\n\n - `$author`\n\n The ticket owner's mention. Must be included in the message\n for the owner to be invited.\n\n - `$staff`\n\n A list of mentions for the inbox's staff members and roles.\n Must be included in the message for staff to be invited\n if they do not have the Manage Threads permission.\n\n For example, a starting message for a moderation inbox might look like:\n\n ```\n $author Thank you for creating a moderation ticket! $staff will be with you shortly.\n ```\n\n Note that role mentions require either the role to be mentionable or the bot\n to have the *Mention all roles* permission in the inbox's channel.\n\n- `/inbox new-tickets name`\n\n Inspect and manage the default name for new tickets.\n\n Allowed placeholders are:\n\n - `$year`\n - `$month`\n - `$day`\n - `$author`\n\n The ticket owner's display name.\n\n - `$counter`\n\n An incrementing 4-digit counter starting from 0001.\n\n Upon exceeding 9999, the counter will overflow back to 0000.\n The counter is not guaranteed to be sequential and may skip\n if the bot is unsuccessful in creating a ticket.\n\n Thread names will be limited to 100 characters by Discord.\n\n## Ticket Limits\n\nEach inbox limits users to a minimum of 1 thread every 60 seconds.\nIf a channel slowmode above 60 seconds is set, the inbox will match\nthat delay to limit new tickets.\n\nInboxes will also try to limit users to 1 active thread per inbox,\nbut may not be guaranteed due to technical limitations.\n\n## Encryption\n\n> [!WARNING]\n>\n> This feature is experimental and may be removed in the future.\n>\n> This bot does not store any sensitive data on users and persists only\n> the bare minimum needed to function, so encrypting the database is not\n> significantly useful in contrast to protecting your bot's token.\n>\n> Encryption is also not a substitute for properly configured file permissions.\n> You should ensure that other users on your system are not able to read the\n> database or the config.toml file. Other secure methods of transferring\n> these files between systems should be applied as well.\n>\n> Finally, derived keys are not cached by the bot, meaning that every connection\n> made to the database, which can be several connections per command, requires\n> repeating the same key derivation which may be performance intensive.\n\nThis bot supports using an encrypted SQLite database with encryption extensions\nlike [SQLiteMultipleCiphers], [SQLCipher], or [SEE]. On a Windows system,\npre-built DLLs can be found for SQLiteMultipleCiphers in their\n[releases](https://github.com/utelle/SQLite3MultipleCiphers/releases) page.\n\nWith one of the encryption extensions installed, you can use it to encrypt\nthe database and then add the decryption to theticketbot. Run the bot once\nso your database file is created - use `theticketbot --dump-config` to locate it\nif you didn't explicitly set a `db.path` in your config - then open the database\nusing the SQLite shell from your encryption extension and encrypt it:\n\n```sql\n$ sqlite3 theticketbot.db\nSQLite version 3.46.0 2024-05-23 13:25:27 (UTF-16 console I/O) (SQLite3 Multiple Ciphers 1.8.5)\nEnter \".help\" for usage hints.\nsqlite> PRAGMA rekey = 'Hello world!';\nsqlite> .exit\n```\n\nAfter that, open your config.toml file and add a template for the pragma\nto decrypt your database like so:\n\n```toml\n[db]\nkey_template = \"PRAGMA key = '{}'\"\n```\n\nA more complex encryption setup might look like:\n\n```toml\n[db]\npragmas = [\"PRAGMA cipher = sqlcipher\", \"PRAGMA kdf_iter = 512000\"]\nkey_template = \"PRAGMA hexkey = '{}'\"\n```\n\nAt startup, you will be prompted to enter the database key.\nOnce the database is opened, all pragmas will be executed in order.\nTo change the encryption key later, shut down the bot and then manually execute\nthe necessary pragmas according to the documentation for your encryption extension.\n\nIf you get an error like `file is not a database` or `unsupported file format`,\nthis may mean that the bot was unable to decrypt the database, or that the database\nhasn't yet been encrypted. In this case, please double check your pragmas and/or\ntry to manually decrypt your database in an SQLite shell.\n\nDuring encryption, if you get `Rekeying is not supported in WAL journal mode`,\nyou will need to run `PRAGMA journal_mode = delete;` before rekeying.\n\n[SQLiteMultipleCiphers]: https://utelle.github.io/SQLite3MultipleCiphers/\n[SQLCipher]: https://www.zetetic.net/sqlcipher/documentation/\n[SEE]: https://sqlite.org/com/see.html\n\n## License\n\nThis project is written under the [MIT] license.\n\n[MIT]: https://github.com/thegamecracks/theticketbot/blob/main/LICENSE\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A ticket discord bot.",
"version": "0.4.2",
"project_urls": {
"Changelog": "https://github.com/thegamecracks/theticketbot/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/thegamecracks/theticketbot",
"Issues": "https://github.com/thegamecracks/theticketbot/issues"
},
"split_keywords": [
"i18n",
" discord",
" gettext",
" discord.py",
" ticketing-system"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8caf34070a99bcd9ab7bf28f09f1f5f63b1609b5abf20e65b103f1814b064f64",
"md5": "296909751af0aea7960a7a31c26fd9ec",
"sha256": "2a1836cb06730f778cb307b33e64a2cb64e78e9485675bfca298db92e396c2c1"
},
"downloads": -1,
"filename": "theticketbot-0.4.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "296909751af0aea7960a7a31c26fd9ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 47957,
"upload_time": "2024-06-26T23:31:52",
"upload_time_iso_8601": "2024-06-26T23:31:52.762852Z",
"url": "https://files.pythonhosted.org/packages/8c/af/34070a99bcd9ab7bf28f09f1f5f63b1609b5abf20e65b103f1814b064f64/theticketbot-0.4.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9d7b9483e6a17b3eba6a5aa068d7ba10d0f03bff4a3dc7cd2490d0f49d5ab874",
"md5": "d6099a8e4df836c5fa31dc84ee258b5a",
"sha256": "62f1ffa9ee37a27af9117e60907886bccc24ff539ca87e88d1d12fe1ba0f6444"
},
"downloads": -1,
"filename": "theticketbot-0.4.2.tar.gz",
"has_sig": false,
"md5_digest": "d6099a8e4df836c5fa31dc84ee258b5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 98932,
"upload_time": "2024-06-26T23:31:54",
"upload_time_iso_8601": "2024-06-26T23:31:54.461930Z",
"url": "https://files.pythonhosted.org/packages/9d/7b/9483e6a17b3eba6a5aa068d7ba10d0f03bff4a3dc7cd2490d0f49d5ab874/theticketbot-0.4.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-26 23:31:54",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thegamecracks",
"github_project": "theticketbot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "theticketbot"
}
JSON
