Evlampiy Notes Bot

English | Русский | Español | Deutsch

Voice-to-text bot for Telegram and WhatsApp with multi-language support.

Try it: https://t.me/evlampiy_notes_bot

Features

• Voice transcription — Convert voice messages to text using Wit.ai
• Groq Whisper fallback — Automatic fallback to Groq Whisper when Wit.ai monthly limit is reached
• Credit system — Monetization via Telegram Stars with per-user credit balance
• Multi-platform — Works with Telegram and WhatsApp
• Multi-language — Supports English, German, Russian, Spanish
• Per-chat settings — Each user/group can have individual language preferences
• GPT integration — Trigger GPT commands via voice (say "evlampiy" + your question)
• Obsidian integration — Auto-save voice transcriptions to Obsidian vault via GitHub (OAuth Device Flow)

Architecture

src/
├── transcription/       # Domain layer (platform-agnostic)
│   ├── service.py       # Core transcription logic
│   ├── wit_client.py    # Wit.ai clients
│   └── groq_client.py   # Groq Whisper client
├── telegram/            # Telegram adapter
│   ├── bot.py
│   ├── handlers.py
│   ├── voice.py
│   └── payments.py      # Telegram Stars payment handlers
├── whatsapp/            # WhatsApp adapter
│   ├── client.py
│   └── handlers.py
├── credits.py           # Credit system & usage stats
├── wit_tracking.py      # Wit.ai monthly usage tracking
├── const.py             # Shared constants
├── github_oauth.py      # GitHub OAuth Device Flow
├── github_api.py        # GitHub API operations
├── obsidian.py          # Obsidian vault integration
└── main.py              # Application entry point

Requirements

• Python 3.12+
• MongoDB
• FFmpeg (for audio processing)
• Wit.ai API tokens
• Telegram Bot token from @BotFather
• (Optional) WhatsApp Business API credentials
• (Optional) GitHub OAuth App client ID (for Obsidian integration)
• (Optional) Groq API key (for Whisper fallback)

Quick Start

# Clone
git clone https://github.com/yastcher/evlampiy.git
cd evlampiy

# Install dependencies
pip install uv
uv sync

# Configure
cp .env.example .env
# Edit .env with your tokens

# Run
uv run python -m src.main

Configuration

Create .env file:

TELEGRAM_BOT_TOKEN=your_bot_token
MONGO_URI=mongodb://localhost:27017/

# Wit.ai tokens (get from https://wit.ai/)
WIT_EN_TOKEN=your_english_token
WIT_RU_TOKEN=your_russian_token
WIT_ES_TOKEN=your_spanish_token
WIT_DE_TOKEN=your_german_token

# Optional: GPT integration
GPT_TOKEN=your_openai_token

# Optional: WhatsApp integration (see docs/WHATSAPP_SETUP.md)
WHATSAPP_TOKEN=your_whatsapp_token
WHATSAPP_PHONE_ID=your_phone_id
WHATSAPP_VERIFY_TOKEN=your_verify_token

# Optional: GitHub OAuth (for Obsidian integration)
GITHUB_CLIENT_ID=your_github_oauth_app_client_id

# Optional: Monetization
GROQ_API_KEY=your_groq_api_key
VIP_USER_IDS=123456,789012
ADMIN_USER_IDS=123456789
INITIAL_CREDITS=3
WIT_FREE_MONTHLY_LIMIT=500

For WhatsApp setup instructions, see docs/WHATSAPP_SETUP.md.

Bot Commands

Command	Description
/start	Show help and current settings
/choose_your_language	Set voice recognition language
/enter_your_command	Set custom GPT trigger word
/buy	Buy credits with Telegram Stars
/balance	Show current credit balance
/mystats	Show your personal usage statistics
/connect_github	Connect GitHub account (OAuth Device Flow)
/toggle_obsidian	Enable/disable Obsidian sync
/disconnect_github	Disconnect GitHub and disable sync

For admin commands, see docs/ADMIN.md.

Development

# Install dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run linter
uv run ruff check

# Run with coverage
uv run pytest --cov=src --cov-fail-under=85

Deployment

See DEPLOY.md for Docker deployment instructions.

Roadmap

• Voice-to-text transcription
• Multi-language support (EN, RU, ES, DE)
• GPT command integration
• CI/CD with GitHub Actions
• WhatsApp integration
• Obsidian integration via GitHub OAuth
• Monetization (Telegram Stars, credit system, Groq Whisper fallback)
• Message classification by topics
• ChatMemberUpdated handler for cleanup

License

Proprietary. All rights reserved. See LICENSE.