{"id":31042857,"url":"https://github.com/bintangyosua/cashflowy","last_synced_at":"2026-05-01T10:31:23.085Z","repository":{"id":284862044,"uuid":"956301700","full_name":"bintangyosua/cashflowy","owner":"bintangyosua","description":"Telegram Financial Bot is an AI-powered WhatsApp bot that records financial transactions in Google Sheets. It categorizes transactions automatically using Google Gemini AI and provides instant responses.","archived":false,"fork":false,"pushed_at":"2025-09-08T10:48:54.000Z","size":145,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-17T02:41:47.168Z","etag":null,"topics":["ai","bot","chatbot","finance-management","gemini","machine-learning","whatsapp"],"latest_commit_sha":null,"homepage":"https://cashflowy-minuettaro.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bintangyosua.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-28T02:59:42.000Z","updated_at":"2025-11-08T14:22:22.000Z","dependencies_parsed_at":"2025-09-08T12:26:30.314Z","dependency_job_id":"bbe7d5b4-a074-4c02-82ab-f34bdaf35194","html_url":"https://github.com/bintangyosua/cashflowy","commit_stats":null,"previous_names":["bintangyosua/whatsapp-ai-financial-report","bintangyosua/cashflowy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bintangyosua/cashflowy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bintangyosua%2Fcashflowy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bintangyosua%2Fcashflowy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bintangyosua%2Fcashflowy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bintangyosua%2Fcashflowy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bintangyosua","download_url":"https://codeload.github.com/bintangyosua/cashflowy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bintangyosua%2Fcashflowy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32494270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["ai","bot","chatbot","finance-management","gemini","machine-learning","whatsapp"],"created_at":"2025-09-14T12:20:43.033Z","updated_at":"2026-05-01T10:31:23.033Z","avatar_url":"https://github.com/bintangyosua.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram AI Transaction Bot\n\nAn AI-powered Telegram bot that records transactions from text messages and receipt images with detailed item extraction.\n\n## 🚀 Features\n\n- Receives and processes transactions from Telegram messages and images\n- **Multi-AI Support**: Choose between ChatGPT or Gemini AI for transaction processing\n- AI-powered receipt OCR with item detail extraction\n- Google Sheets integration for transaction storage (latest entries appear at top)\n- Support for multiple items per transaction (e.g., grocery receipts)\n- RESTful API endpoints for AI provider configuration\n\n## 📦 Technologies\n\n- **Python** (FastAPI)\n- **Telegram Bot API**\n- **Google Sheets API**\n- **ChatGPT/OpenAI API** (Primary AI provider)\n- **Gemini AI** (Alternative AI provider)\n\n## 🔧 Installation\n\n1. Clone this repository:\n   ```sh\n   git clone https://github.com/your-username/telegram-ai-bot.git\n   cd telegram-ai-bot\n   ```\n2. Install dependencies:\n   ```sh\n   pip install -r requirements.txt\n   ```\n3. Configure environment variables:\n   ```sh\n   cp .env.example .env\n   # Edit .env with your configuration:\n   # - TELEGRAM_BOT_TOKEN: Your Telegram bot token\n   # - OPENAI_API_KEY: Your OpenAI API key (for ChatGPT)\n   # - GEMINI_API_KEY: Your Google Gemini API key (optional)\n   # - AI_PROVIDER: Set to \"chatgpt\" or \"gemini\"\n   ```\n\n## 🤖 AI Provider Configuration\n\nThis bot supports two AI providers:\n\n### ChatGPT (Default, Recommended)\n\n- Better accuracy for financial data extraction\n- Excellent image processing capabilities\n- More reliable JSON response formatting\n\n### Gemini AI (Alternative)\n\n- Free tier available\n- Good for basic text processing\n- Backup option when OpenAI is unavailable\n\nYou can switch between providers using the API endpoints or by updating the `AI_PROVIDER` environment variable.\n\n````\n\n## 🚀 Running the Bot\n\nStart the server with FastAPI:\n\n```sh\nuvicorn main:app --host 0.0.0.0 --port 8000 --reload\n````\n\n## 📌 Usage\n\nThe bot will automatically respond to Telegram messages:\n\n- **Send text** → AI extracts transaction details and saves to Google Sheets\n- **Send image** → OCR processes receipt with item details\n- **Latest transactions appear at the top** of your Google Sheets\n\n### Transaction Processing\n\nWhen you send transaction data (text or image), the bot will:\n\n1. Process with selected AI provider (ChatGPT or Gemini)\n2. Extract transaction details (amount, category, payment method, etc.)\n3. Save to Google Sheets with newest entries at the top\n4. Send confirmation message with extracted details\n\nExample response for a grocery receipt:\n\n```\n✅ Transaksi tercatat!\nBelanja groceries di Alfamart\nJumlah: Rp87,900\n\nDetail items:\n• Indomie Goreng x5 @Rp3,000\n• Teh Botol x2 @Rp4,500\n• Snack x3 @Rp2,500\n```\n\n## 🛠 API Endpoints\n\n| Method | Endpoint              | Description                           |\n| ------ | --------------------- | ------------------------------------- |\n| `GET`  | `/`                   | Home Page                             |\n| `POST` | `/webhook`            | Receives webhooks from Telegram       |\n| `GET`  | `/health`             | Health check \u0026 service status         |\n| `GET`  | `/ai-provider`        | Get current AI provider               |\n| `POST` | `/ai-provider`        | Set AI provider (chatgpt/gemini)      |\n| `POST` | `/test-chatgpt`       | Test ChatGPT processing (development) |\n| `POST` | `/test-gemini`        | Test Gemini processing (development)  |\n| `POST` | `/test-google-sheets` | Test Google Sheets connection         |\n\n### Example: Switch to ChatGPT\n\n```bash\ncurl -X POST \"http://localhost:8000/ai-provider\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"provider\": \"chatgpt\"}'\n```\n\n### Example: Check current AI provider\n\n```bash\ncurl -X GET \"http://localhost:8000/ai-provider\"\n```\n\n## 👨‍💻 Contributing\n\nPull requests are welcome! Please open an issue first if you want to add a new feature.\n\n## 📜 License\n\nMIT License. Feel free to use and modify it as needed!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbintangyosua%2Fcashflowy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbintangyosua%2Fcashflowy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbintangyosua%2Fcashflowy/lists"}