{"id":13610679,"url":"https://github.com/mikurei/ticketgram","last_synced_at":"2025-04-13T01:32:29.894Z","repository":{"id":175013489,"uuid":"652734587","full_name":"mikurei/ticketgram","owner":"mikurei","description":"Telegram Support Bot","archived":false,"fork":false,"pushed_at":"2023-07-27T13:29:42.000Z","size":6659,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-01T19:55:29.864Z","etag":null,"topics":["bot","python","python-telegram-bot","python3","sqlite3","support","support-tools","telegram-bot","ticket-bot","ticket-system","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":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikurei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-06-12T17:27:17.000Z","updated_at":"2024-05-31T08:50:03.000Z","dependencies_parsed_at":"2024-01-14T06:56:27.254Z","dependency_job_id":null,"html_url":"https://github.com/mikurei/ticketgram","commit_stats":null,"previous_names":["mikurei/ticketgram"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikurei%2Fticketgram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikurei%2Fticketgram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikurei%2Fticketgram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikurei%2Fticketgram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikurei","download_url":"https://codeload.github.com/mikurei/ticketgram/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223558266,"owners_count":17165098,"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":["bot","python","python-telegram-bot","python3","sqlite3","support","support-tools","telegram-bot","ticket-bot","ticket-system","ticketing-system"],"created_at":"2024-08-01T19:01:46.978Z","updated_at":"2024-11-07T17:30:24.219Z","avatar_url":"https://github.com/mikurei.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Ticketgram\nA simple yet powerful support bot that allows you to receive and respond to user feedback.\n\n## Gallery\n|User-side|Support-side|\n|-|-|\n|![](/screenshots/user_side.png)|![](/screenshots/support_side.png)|\n\nSee more at [Screenshots](screenshots/SCREENSHOTS.md)\n\n# Features\n- Message-based (question-answer)\n- Anonymous (pseudonym system)\n- Configurable\n- Dockerized\n- Internationalization support\n- Access control \u0026 usage limitting\n- Monitoring support (Prometheus)\n\n# Uses\n- `Python 3.11`\n- `python-telegram-bot` Telegram Bot HTTP API wrapper (that you can't refuse)\n- `peewee` as an ORM\n- `babel` for localization\n- `prometheus-client` for instrumentation \u0026 serving the `/metrics` endpoint\n- `SQLite` as a database\n\n# Commands\nClient-side:\n- `/start` Welcome message\n- `/ticket` Create a new ticket\n\nSupport-side:\n- `/open` View open tickets\n- `/ban` Ban the user\n- `/unban` Unban the user\n- `/pseudonym` Set pseudonym\n\n# Usage\n## Prerequisites\n1. Bot account\n   1. Start the [@BotFather](https://t.me/BotFather)\n   2. Type the `/newbot` command\n   3. Follow the instructions to get your own bot and `TELEGRAM_TOKEN`\n2. Supergroup\n   1. Create a regular private group\n   2. Upgrade it to a supergroup (for example, by changing the visibility of `chat history for new members`) [1]\n3. `chat_id` of the supergroup\n   1. Invite the bot to the supergroup\n   2. You will see that the bot automatically leaves from unauthorized groups.\n   3. Notice the log line `... | INFO | callbacks::leave_chat (...) | Chat is not authorized: 'chat_id'`, where `chat_id` is supergroup id\n   \u003e ℹ️ Optionally, use a bot or a custom telegram client of your choice that gives you `chat_id` of the group, for example [@getidsbot](https://t.me/getidsbot)\n\n[1] - Learn more about supergroup triggers here: https://stackoverflow.com/a/62291433\n\n# Installation\n\u003e⚠️ Requires Python 3.11 or above\n\nFirst of all, clone the repository using the `git clone` command and `cd` into the `ticketgram` directory.\n\n## Using Poetry (recommended)\n```bash\npoetry install\npoetry shell\n```\n\n## Using pip\n```bash\npip install -r requirements.txt\n```\n\n# Launch\n```bash\n# dont forget about environment variables\n# Powershell syntax\n$env:KEY=\"VALUE\"\n# Bash syntax\nexport KEY=VALUE\n\n...\n\npython src/bot.py\n```\n\n# Deploy using Docker\nYou can pull the latest image from Docker Hub:\n```bash\ndocker pull mikurei/ticketgram:latest\n```\nHead to the [build section](#build) if you want to build the image by yourself.\n\n## Build\n```bash\ncd ticketgram\ndocker build -t ticketgram .\n```\n\n## Deploy\nReplace `YOUR_TOKEN` with a valid Telegram bot token and `GROUP_CHAT_ID` with the chat id of the group where the bot will operate.\n\n```\ndocker run -d \\\n   -e TELEGRAM_TOKEN=\"YOUR_TOKEN\" \\\n   -e AUTHORIZED_GROUP_ID=\"GROUP_CHAT_ID\" \\\n   -e DB_URI=\"/app/db/sqlite.db\" \\\n   --mount \"type=volume,src=ticketgram_db,target=/app/db/\" \\\n   ticketgram\n```\n\u003e ℹ️ You can specify other environment variables here using `-e KEY=\"VALUE\"` syntax to configure runtime of the bot.\n\n# Configuration\nBot is configured using the `Environment Variables`.\n\nList of available env vars\n|Name|Description|\n|-|-|\n|TELEGRAM_TOKEN|**Required** bot token to access the HTTP Bot API|\n|AUTHORIZED_GROUP_ID|**Required** group in which the bot operates|\n|BOT_LANGUAGE|*Optional* Language of the bot's messages. Defaults to `\"en\"`|\n|DB_URI|*Optional* SQLite connection URI. Defaults to `\"sqlite.db\"`|\n|USER_OPEN_TICKETS_MAX|*Optional* Maximum amount of open tickets per user. Defaults to `\"3\"`|\n|BOT_TIME_ACTIVE|*Optional* Support opening hours which are displayed in the welcome message. Defaults to `\"09:00-17:00\"`|\n|BOT_TIME_ZONE|*Optional* Timezone of the support. Defaults to `\"+0\"`|\n|BOT_ACTIVE_DAYS|*Optional* Working days of the support. Defaults to `\"monday tuesday wednesday thursday friday saturday sunday\"`|\n|PROMETHEUS_ENABLED|*Optional* Enables the Prometheus metrics exporter. Defaults to `False`|\n|PROMETHEUS_PORT|*Optional* Port on which the bot serves the `/metrics` endpoint. Defaults to `8000`|\n\nTo change the welcome and support reply messages, review the `templates.py` module.\n\n# Monitoring the bot\nTicketgram provides an optional feature that allows you to export metrics to **Prometheus**. To enable it, set the `PROMETHEUS_ENABLED` to `1` and provide a port using `PROMETHEUS_PORT`.\n\nYou will need a configured [Prometheus](https://prometheus.io/) server for pulling metrics from the bot. You can use the awesome [Grafana](https://grafana.com/) for visualizaiton.\n\nCurrently, ticketgram provides two metrics:\n- `ticketgram_callbacks_total{func_name}`\n- `ticketgram_callbacks_duration_seconds{func_name}`\n\nTo check if the exporter works, open `http://HOST:PROMETHEUS_PORT` in your browser, for example http://localhost:8000\n\n# Localization\nProject uses [GNU gettext](https://docs.python.org/3/library/gettext.html) and [Babel](https://babel.pocoo.org/en/latest/index.html) utilities for internationalization.\n```\nlocales/                | Message catalog\n|  LANGUAGE_CODE/       | Concrete translation\n|  |  LC_MESSAGES/      |\n|  |  |  base.mo        | Compiled translation file\n|  |  |  base.po        | Translation file\n|  base.pot             | Template translation file\n```\n\n## Adding a new language\n1. Create a new language directory under the `locales/`, for example `ja_JP/`\n2. Create `LC_MESSAGES/` in new language directory\n3. Copy the `base.pot` from `locales/` folder into `LC_MESSAGES` and rename it to `base.po`\n4. Translate the strings to desired language\n   - `msgid` key is original string\n   - `msgstr` key is translated string\n5. Compile the `base.po` to `base.mo` either using `pybabel compile` or `msgfmt` (Linux/WSL only)\n\n___\n*I'd appreciate it if you'd leave a **star ⭐** and **fork the repo**. Thanks!*\n\n*Created by [mikurei](https://github.com/mikurei) 2023*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikurei%2Fticketgram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikurei%2Fticketgram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikurei%2Fticketgram/lists"}