A simple yet powerful support bot that allows you to receive and respond to user feedback.

User-side	Support-side

See more at Screenshots

• Message-based (question-answer)
• Anonymous (pseudonym system)
• Configurable
• Dockerized
• Internationalization support
• Access control & usage limitting
• Monitoring support (Prometheus)

• Python 3.11
• python-telegram-bot Telegram Bot HTTP API wrapper (that you can't refuse)
• peewee as an ORM
• babel for localization
• prometheus-client for instrumentation & serving the /metrics endpoint
• SQLite as a database

Client-side:

• /start Welcome message
• /ticket Create a new ticket

Support-side:

• /open View open tickets
• /ban Ban the user
• /unban Unban the user
• /pseudonym Set pseudonym

1. Bot account
   1. Start the @BotFather
   2. Type the /newbot command
   3. Follow the instructions to get your own bot and TELEGRAM_TOKEN
2. Supergroup
   1. Create a regular private group
   2. Upgrade it to a supergroup (for example, by changing the visibility of chat history for new members) [1]
3. chat_id of the supergroup
   1. Invite the bot to the supergroup
   2. You will see that the bot automatically leaves from unauthorized groups.
   3. Notice the log line ... | INFO | callbacks::leave_chat (...) | Chat is not authorized: 'chat_id', where chat_id is supergroup id

   ℹ️ Optionally, use a bot or a custom telegram client of your choice that gives you chat_id of the group, for example @getidsbot

[1] - Learn more about supergroup triggers here: https://stackoverflow.com/a/62291433

⚠️ Requires Python 3.11 or above

First of all, clone the repository using the git clone command and cd into the ticketgram directory.

poetry install
poetry shell

pip install -r requirements.txt

# dont forget about environment variables
# Powershell syntax
$env:KEY="VALUE"
# Bash syntax
export KEY=VALUE

...

python src/bot.py

You can pull the latest image from Docker Hub:

docker pull mikurei/ticketgram:latest

Head to the build section if you want to build the image by yourself.

cd ticketgram
docker build -t ticketgram .

Replace YOUR_TOKEN with a valid Telegram bot token and GROUP_CHAT_ID with the chat id of the group where the bot will operate.

docker run -d \
   -e TELEGRAM_TOKEN="YOUR_TOKEN" \
   -e AUTHORIZED_GROUP_ID="GROUP_CHAT_ID" \
   -e DB_URI="/app/db/sqlite.db" \
   --mount "type=volume,src=ticketgram_db,target=/app/db/" \
   ticketgram

ℹ️ You can specify other environment variables here using -e KEY="VALUE" syntax to configure runtime of the bot.

Bot is configured using the Environment Variables.

List of available env vars

To change the welcome and support reply messages, review the templates.py module.

Ticketgram 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.

You will need a configured Prometheus server for pulling metrics from the bot. You can use the awesome Grafana for visualizaiton.

Currently, ticketgram provides two metrics:

• ticketgram_callbacks_total{func_name}
• ticketgram_callbacks_duration_seconds{func_name}

To check if the exporter works, open http://HOST:PROMETHEUS_PORT in your browser, for example http://localhost:8000

Project uses GNU gettext and Babel utilities for internationalization.

locales/                | Message catalog
|  LANGUAGE_CODE/       | Concrete translation
|  |  LC_MESSAGES/      |
|  |  |  base.mo        | Compiled translation file
|  |  |  base.po        | Translation file
|  base.pot             | Template translation file

1. Create a new language directory under the locales/, for example ja_JP/
2. Create LC_MESSAGES/ in new language directory
3. Copy the base.pot from locales/ folder into LC_MESSAGES and rename it to base.po
4. Translate the strings to desired language
   • msgid key is original string
   • msgstr key is translated string
5. Compile the base.po to base.mo either using pybabel compile or msgfmt (Linux/WSL only)

I'd appreciate it if you'd leave a star ⭐ and fork the repo. Thanks!

Created by mikurei 2023