Tangem Feedback Bot

Telegram bot that listens to your internal Telegram group, extracts structured feedback from forwarded moderator posts, and writes it to Google Sheets with a CSV daily fallback.

What it does

• Reads new messages from your internal Telegram group.
• Extracts:
  • A: Wish/suggestion - ABSTRACT
  • B: Category (dropdown-ready)
  • C: Product/direction (dropdown-ready)
  • D: Comment/ Text of the appeal (full text)
  • E: Source (FB, Telegram, X, Discord, Insta, Reddit)
  • F: Created by (Moderators by default)
  • G: Date
• Detects original username via forwarded metadata when available.
• If no forwarded metadata exists, tries to parse username from text (for example From vadrasla: ... or @DecentralizeADA (X)).
• Uses an OpenAI-compatible endpoint for extraction and categorization.
• Deduplicates processed Telegram messages via SQLite.
• Writes to Google Sheets (if configured) and also exports daily CSV (configurable).

Important Telegram limits

• A bot receives only updates after it is added to the group. It cannot backfill old history by default.
• Disable bot privacy mode in BotFather (/setprivacy -> Disable) so it can read non-command messages in groups.
• Add the bot to the internal group and make sure it has permission to read messages.
• Use /whereami in a chat with the bot to get chat_id for TELEGRAM_ALLOWED_CHAT_IDS.

Quick start

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Create .env from .env.example:

cp .env.example .env

3. Fill required values in .env:

• TELEGRAM_BOT_TOKEN
• OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL
• Optional Google Sheets integration:
  • GOOGLE_SHEETS_ID
  • GOOGLE_SERVICE_ACCOUNT_FILE
  • GOOGLE_WORKSHEET_NAME

4. If using Google Sheets:

• Create a Google Cloud service account and download JSON key.
• Share the target Google Sheet with service account email (Editor role).
• Put the JSON key at ./credentials/service-account.json (default in .env.example).

5. Run the bot:

set -a; source .env; set +a
python -m tangem_feedback_bot.main

Run with Docker

1. Prepare env:

cp .env.example .env

2. Fill .env with your TELEGRAM_BOT_TOKEN and OpenAI values.

3. Optional Google Sheets:

• Save service account key to ./credentials/service-account.json.
• Keep GOOGLE_SERVICE_ACCOUNT_FILE=./credentials/service-account.json in .env.

4. Start:

docker compose up -d --build

5. Check logs:

docker compose logs -f tangem-feedback-bot

6. Stop:

docker compose down

Environment variables

• TELEGRAM_BOT_TOKEN (required)
• TELEGRAM_ALLOWED_CHAT_IDS (optional, comma-separated chat IDs; if empty, accepts all chats)
• OPENAI_BASE_URL (default https://api.openai.com/v1)
• OPENAI_API_KEY (optional but recommended)
• OPENAI_MODEL (default gpt-4o-mini)
• GOOGLE_SHEETS_ID (optional)
• GOOGLE_WORKSHEET_NAME (default Feedback)
• GOOGLE_SERVICE_ACCOUNT_FILE (optional)
• FALLBACK_EXPORT_DIR (default ./exports)
• ALWAYS_EXPORT_DAILY_CSV (default true)
• INCLUDE_ORIGIN_IN_COMMENT (default true)
• SQLITE_PATH (default ./data/state.db)
• CREATED_BY_VALUE (default Moderators)
• DATE_FORMAT (default %d/%m/%Y)
• TIMEZONE (default Europe/Warsaw)
• LOG_LEVEL (default INFO)

Category values

• Networks / Providers Adding
• Tokens/Coins/Memes Adding
• NFT Adding
• New Features
• Statistics / Charts
• Flow Changing
• UX/UI
• Other

Product/direction values

• Wallet app
• Staking
• Swap
• Pay
• Connect
• On-ramp / Off-ramp
• Earn
• Rings
• Cards
• Orders & Delivery
• Other

Output

• Google Sheets append (A-G columns), with data validation dropdowns for Category, Product/direction, and Source.
• Daily CSV file in exports/feedback-YYYY-MM-DD.csv.
• Internal SQLite DB for dedup + audit records in data/state.db.