Zeron Telegram Bot

Zeron is a production-ready Telegram AI assistant built with Python, Claude, and SQLite.

It is designed for real-world usage, portfolio showcase, and rapid deployment. You can run it locally in minutes and deploy it on worker-friendly platforms with minimal setup.

Why Use Zeron

Zeron is useful when you want one bot that combines AI chat, productivity, media tools, and monetization in a single clean architecture.

Key reasons to use it:

• AI-first experience: natural chat powered by Claude with persistent context
• Productivity built-in: tasks, reminders, summaries, and daily digest
• Creator-ready: image/video generation and PDF Q&A workflows
• Business-ready: subscription model, referral credits, analytics, admin tools
• Secure-by-default: sanitization, injection checks, moderation, and rate limiting
• Resume-friendly: clear codebase, Dockerized deployment path, practical feature depth

Benefits

For users:

• Fast answers and assistant-like conversations in Telegram
• One place for chat, tasks, document Q&A, and media generation
• Better daily planning with scheduled digest updates

For developers/builders:

• Modular handler architecture that is easy to extend
• SQLite persistence for quick setup and no external DB requirement
• Feature flags and env-based configuration for flexible deployment
• Strong base for SaaS bot ideas (subscriptions, referrals, admin metrics)

For portfolio/resume:

• Demonstrates backend design, API integrations, async bot workflows, security practices, and production deployment skills in one project

Feature Overview

• Claude chat with persistent conversation history
• Photo analysis (multimodal)
• PDF Q&A and optional voice transcription
• Task manager with reminders
• Google Sheets, Drive, and Gmail integration
• Image and video generation (Stitch)
• Telegram Stars subscriptions + referral system
• Daily digest scheduling
• Outbound webhooks and optional inbound receiver
• Admin commands for stats and broadcasting

Tech Stack

• Python 3.11+
• python-telegram-bot
• Anthropic API
• SQLite
• Optional: OpenAI, Google APIs, OpenWeather

Quick Start

1. Install dependencies

pip install -r requirements.txt

2. Configure environment

cp .env.example .env

Set at least:

TELEGRAM_TOKEN=your_botfather_token
ANTHROPIC_API_KEY=your_anthropic_api_key
ADMIN_USER_IDS=123456789

3. Run locally

python bot.py

If WEBHOOK_URL is empty, Zeron runs in polling mode.

How To Use Zeron

Basic flow:

1. Start chat with /start
2. Ask anything in normal text
3. Use /task, /tasks, /done for productivity
4. Use /image or /video for media generation
5. Upload a PDF and ask questions
6. Use /digest 08:00 for daily AI summary

Useful commands:

• /start, /help, /clear, /summarize
• /task <text>, /tasks, /done <id>, /deltask <id>
• /image <prompt>, /video <prompt>
• /sheets [range], /drive <query>, /gmail
• /subscribe, /referral
• /digest, /webhook, /clearpdf
• /stats, /broadcast (admin)

Deployment

Worker-first recommendation

This bot is ideal for worker-style deployment in polling mode.

Included files:

• koyeb.yaml
• Dockerfile
• .dockerignore

Required variables

• TELEGRAM_TOKEN
• ANTHROPIC_API_KEY
• ADMIN_USER_IDS

Recommended variables

• ENCRYPTION_KEY
• WEBHOOK_SECRET_KEY

Optional variables

• ALLOWED_USER_IDS
• OPENAI_API_KEY
• OPENWEATHER_API_KEY
• GOOGLE_CREDENTIALS_PATH
• GOOGLE_SHEET_ID
• STITCH_API_URL
• ENABLE_INCOMING_WEBHOOKS
• INCOMING_WEBHOOK_PORT

Important:

• Keep WEBHOOK_URL empty for polling mode.

Environment Variables

Variable	Required	Purpose
TELEGRAM_TOKEN	Yes	Telegram bot token from BotFather
ANTHROPIC_API_KEY	Yes	Claude API key
ADMIN_USER_IDS	Yes	Comma-separated Telegram IDs for admin commands
ALLOWED_USER_IDS	No	Optional access allowlist
OPENAI_API_KEY	No	Required for voice transcription
OPENWEATHER_API_KEY	No	Required for weather tool
GOOGLE_CREDENTIALS_PATH	No	Google service account JSON path
GOOGLE_SHEET_ID	No	Default Google Sheet ID
STITCH_API_URL	No	Stitch endpoint override
WEBHOOK_URL	No	Enables webhook mode when set
PORT	No	Webhook mode port (default 8443)
ENCRYPTION_KEY	No	Enables encrypted storage
WEBHOOK_SECRET_KEY	No	HMAC secret for webhook signatures
ENABLE_INCOMING_WEBHOOKS	No	Enables inbound webhook server
INCOMING_WEBHOOK_PORT	No	Inbound webhook server port (default 8080)

Security Highlights

• Input sanitization for user content
• Prompt-injection pattern detection
• Content moderation checks
• Tier-aware rate limiting
• Optional user allowlist

Project Structure

telegram-bot-v4/
  bot.py
  database.py
  middleware.py
  security.py
  retry.py
  encryption.py
  handlers/
    ai_handler.py
    admin_handler.py
    digest_handler.py
    google_handler.py
    payment_handler.py
    pdf_handler.py
    plugin_handler.py
    stitch_handler.py
    task_handler.py
    voice_handler.py
    webhook_handler.py

Troubleshooting

• Error: TELEGRAM_TOKEN is missing or invalid

  • Generate/revoke token in BotFather, update .env, restart.

• Error: bot starts but AI responses fail

  • Verify ANTHROPIC_API_KEY is valid.

• Error: voice/PDF premium flow not working

  • Check optional feature keys and subscription logic.

License

MIT

Credits

• python-telegram-bot
• Anthropic Claude API
• OpenAI Whisper
• pypdf