{"id":20918804,"url":"https://github.com/thegamecracks/theticketbot","last_synced_at":"2025-05-13T12:31:31.915Z","repository":{"id":242451560,"uuid":"809580843","full_name":"thegamecracks/theticketbot","owner":"thegamecracks","description":"A ticket bot built on Discord's native threads.","archived":false,"fork":false,"pushed_at":"2025-02-09T10:06:46.000Z","size":518,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-20T18:17:49.110Z","etag":null,"topics":["discord","discord-py","i18n","project-fluent","python","python-package","ticketing-system"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thegamecracks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-03T03:37:48.000Z","updated_at":"2025-02-09T10:06:50.000Z","dependencies_parsed_at":"2024-07-26T21:46:16.987Z","dependency_job_id":"d68e523d-bc42-496a-90ee-03d994251205","html_url":"https://github.com/thegamecracks/theticketbot","commit_stats":null,"previous_names":["thegamecracks/theticketbot"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thegamecracks%2Ftheticketbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thegamecracks%2Ftheticketbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thegamecracks%2Ftheticketbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thegamecracks%2Ftheticketbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thegamecracks","download_url":"https://codeload.github.com/thegamecracks/theticketbot/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253942310,"owners_count":21988025,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["discord","discord-py","i18n","project-fluent","python","python-package","ticketing-system"],"created_at":"2024-11-18T16:40:00.870Z","updated_at":"2025-05-13T12:31:31.481Z","avatar_url":"https://github.com/thegamecracks.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# theticketbot\n\n[![](https://img.shields.io/pypi/v/theticketbot?style=flat-square)](https://pypi.org/project/theticketbot/)\n[![](https://img.shields.io/github/actions/workflow/status/thegamecracks/theticketbot/black-lint.yml?style=flat-square\u0026label=black)](https://black.readthedocs.io/en/stable/)\n[![](https://img.shields.io/github/actions/workflow/status/thegamecracks/theticketbot/pyright-lint.yml?style=flat-square\u0026label=pyright)](https://microsoft.github.io/pyright/#/)\n\nA simple Discord bot for handling ticket systems using channel threads.\n\n![](https://raw.githubusercontent.com/thegamecracks/theticketbot/main/docs/images/demo.png)\n\n## Resources\n\n- Changelog: https://github.com/thegamecracks/theticketbot/blob/main/CHANGELOG.md\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\nFTL files there, and make a pull request!\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\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\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   On subsequent updates, application commands will automatically be synced\n   as needed. You can also use `theticketbot --sync` to manually synchronize\n   the bot's application commands again.\n\n   Alternatively, you can use the \"\u003c@mention\u003e sync\" text command once your bot\n   is in a server to synchronize application commands.\n\n3. Invite your bot to a server.\n\n   Once logged in, the bot will print out an invite link with the appropriate\n   permissions. If you want to manually generate an invite link, you can go to\n   the [Applications](https://discord.com/developers/applications) \u003e OAuth2\n   page, 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\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\nNew tickets will be created in the same channel as the inbox by default.\nIf you want to customize this, you can specify a different channel with\nthe `/inbox create \u003cdestination\u003e` parameter, or use the `/inbox destination`\ncommand to re-route new tickets from an existing inbox.\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\nWith all the above said, the recommended workflow for most community servers\nis to give your staff and the bot Manage Threads permission for a single channel.\nWhen staff needs to close a ticket, they should remove all invited members first,\nthen the ticket owner last to automatically trigger archival and locking of the ticket.\nStaff are free to continue conversations in the ticket if needed, which\nautomatically re-opens it.\n\nIf you need to deviate from this workflow to accommodate alternative requirements,\nlike allowing ticket owners to read their past tickets or having multiple staff\nroles with different management permissions, feel free to develop and document\na new procedure for your staff team to follow.\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 destination`\n\n  Route new tickets from an inbox to another channel.\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\u003e [!WARNING]\n\u003e\n\u003e This feature is experimental and may be removed in the future.\n\u003e\n\u003e This bot does not store any sensitive data on users and persists only\n\u003e the bare minimum needed to function, so encrypting the database is not\n\u003e significantly useful in contrast to protecting your bot's token.\n\u003e\n\u003e Encryption is also not a substitute for properly configured file permissions.\n\u003e You should ensure that other users on your system are not able to read the\n\u003e database or the config.toml file. Other secure methods of transferring\n\u003e these files between systems should be applied as well.\n\u003e\n\u003e Finally, derived keys are not cached by the bot, meaning that every connection\n\u003e made to the database, which can be several connections per command, requires\n\u003e 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\u003e PRAGMA rekey = 'Hello world!';\nsqlite\u003e .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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthegamecracks%2Ftheticketbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthegamecracks%2Ftheticketbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthegamecracks%2Ftheticketbot/lists"}