{"id":50549623,"url":"https://github.com/beacoder/telegram_bot","last_synced_at":"2026-06-04T02:01:18.335Z","repository":{"id":356850546,"uuid":"1234324941","full_name":"beacoder/telegram_bot","owner":"beacoder","description":"telegram_bot powered by opencode.","archived":false,"fork":false,"pushed_at":"2026-05-18T02:50:46.000Z","size":212,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-18T04:55:15.091Z","etag":null,"topics":["opencode","piper-tts","telegram","whisper"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beacoder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2026-05-10T03:15:47.000Z","updated_at":"2026-05-18T02:50:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beacoder/telegram_bot","commit_stats":null,"previous_names":["beacoder/telegram_bot"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/beacoder/telegram_bot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beacoder%2Ftelegram_bot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beacoder%2Ftelegram_bot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beacoder%2Ftelegram_bot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beacoder%2Ftelegram_bot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beacoder","download_url":"https://codeload.github.com/beacoder/telegram_bot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beacoder%2Ftelegram_bot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33886160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","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":["opencode","piper-tts","telegram","whisper"],"created_at":"2026-06-04T02:01:16.442Z","updated_at":"2026-06-04T02:01:18.326Z","avatar_url":"https://github.com/beacoder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Telegram ↔ OpenCode Agent Bridge\n\n## Overview\n\nA Telegram bot that connects directly to an OpenCode agent backend. Supports persistent AI sessions, file uploads, interactive menus, multiple model switching, task scheduling, voice I/O, and proxy environments.\n\n## Architecture\n\n```\nTelegram → Python Bot → OpenCode Agent\n                          ↓\n                    Local Workspace\n                          ↓\n                 Files + Agent Output\n                          ↓\n                   Telegram Response\n```\n\n## Project Structure\n\n```\ntelegram_bot/\n├── telegram_bot.py         # Bot entry point, Telegram app setup\n├── README.md\n├── bot/\n│   ├── __init__.py\n│   ├── agent.py            # OpenCode agent runner + task executor\n│   ├── auth.py             # @authorized decorator for command handlers\n│   ├── config.py           # Configuration, env vars, constants\n│   ├── handlers.py         # Command handlers (help, status, history, etc.)\n│   ├── media.py            # File download, voice transcription, Piper TTS\n│   ├── menu.py             # Interactive menu system (builders + callback handler)\n│   ├── messaging.py        # Telegram message utilities (send_text, send_audio, send_files)\n│   ├── scheduler.py        # Task scheduler (cron-like)\n│   ├── state.py            # Agent lock, running process, model key, bot start time, pending actions\n│   ├── status.py           # Bot health status builder (uptime, CPU, memory, disk)\n│   └── utils.py            # Helpers (process runner, cleanup)\n```\n\n## Interactive Menu\n\nUse `/menu` or the menu appears automatically on bot startup:\n\n| Menu | Options |\n|------|---------|\n| **🧠 Models** | Free / Flash / Pro (with ✓ on current) |\n| **📂 Sessions** | New Session / View History (with pagination) / Search Session |\n| **📅 Tasks** | New Task / View Tasks / Search Task |\n| **🎤 Voice** | Toggle voice output ON/OFF |\n| **📊 Status** | Uptime, model, tasks health, CPU, memory, disk |\n\nTo add a task, just send a natural language prompt like:\n*\"提醒我每天早上7点起床\"*, *\"remind me to check email tomorrow at 9am\"*, *\"每天下午3点查询大盘数据\"*\n\nAll menus have ⬅️ Back buttons to return to the main menu.\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/menu` | Show interactive menu |\n| `/help` | Show available commands |\n| `/status` | Show bot health info (uptime, model, tasks, CPU, memory, disk) |\n| `/history [n]` | Show session history (latest n, default all) |\n| `/continue \u003csession-id\u003e` | Continue session |\n| `/delete \u003csession-id\u003e` | Delete a session |\n| `/free` | Switch to the free model |\n| `/flash` | Switch to `deepseek/deepseek-v4-flash` model |\n| `/pro` | Switch to `deepseek/deepseek-v4-pro` model |\n| `/voice` | Toggle voice output (TTS) |\n| `/cancel` | Stop the currently running agent task |\n| `/restart` | Restart the bot (reconnects to Telegram API) |\n| `/new` | New session |\n| Any text | Send to the agent for processing |\n| Any file | Download and optionally transcribe, then run agent |\n\n## Key Features\n\n- **Interactive Menu System** — Button-driven menus for all bot functions; no need to memorize slash commands\n- **Remote AI Agent Access** — Use Telegram as a mobile interface for your OpenCode agent\n- **Persistent Sessions** — Maintains conversation continuity across messages; continue any past session by title\n- **File Support** — Documents, images, videos, audio; files auto-returned to Telegram\n- **Voice Transcription** — Voice messages transcribed via whisper.cpp before agent execution\n- **Multiple AI Models** — Switch between `free`, `flash`, and `pro` models\n- **Task Scheduler** — Lightweight cron-style scheduler supporting daily, weekly, monthly, and interval-based tasks; add/edit/delete tasks via menu; add tasks using natural language\n- **Bot Status Monitoring** — Real-time bot health: uptime, model, scheduler health, CPU, memory, disk usage\n- **Voice Output (TTS)** — Agent responses converted to speech via Piper; non-Chinese characters filtered automatically for stable Chinese voice synthesis\n- **Proxy Support** — Works through HTTP/SOCKS proxy environments\n- **Task Locking** — Prevents overlapping agent executions\n- **Cancel Running Task** — Use `/cancel` or menu button to stop an in-progress agent task mid-execution\n- **Authorized User Only** — All operations restricted to `AUTHORIZED_USER_ID`\n- **Health Check \u0026 Auto-Restart** — Tracks consecutive connection errors (TimedOut, NetworkError, OSError); after 10 consecutive failures the bot automatically restarts itself via `os.execv`; exponential backoff (5s–300s) on startup failures\n- **Manual Restart Command** — Use `/restart` to gracefully restart the bot without stopping the process\n\n## Configuration\n\nSet these environment variables before running:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `TELEGRAM_BOT_TOKEN` | Yes | Your Telegram bot token from @BotFather |\n| `AUTHORIZED_USER_ID` | Yes | Your Telegram user ID (integer) |\n| `PROXY_URL` | No | HTTP/SOCKS proxy URL (e.g., `socks5://127.0.0.1:7890`) |\n| `WHISPER_CPP_DIR` | No | Path to whisper.cpp directory for voice transcription |\n| `WHISPER_MODEL` | No | Path to whisper.cpp model file |\n| `PIPER_DIR` | No | Path to Piper TTS directory |\n| `PIPER_MODEL` | No | Path to Piper model file (.onnx) |\n\nAdd [OpenCode Configuration](https://github.com/beacoder/llm/tree/main/opencode)\n\n### schedule.json\n\nPlace in `~/agent/schedule.json`:\n\n```json\n[\n  {\n    \"id\": \"a1b2c3d4\",\n    \"prompt\": \"Give me today's tech news summary\",\n    \"run_at\": \"2026-05-11 09:00\",\n    \"repeat\": \"daily\",\n    \"done\": false\n  },\n  {\n    \"id\": \"e5f6g7h8\",\n    \"prompt\": \"Weekly report\",\n    \"run_at\": \"2026-05-17 10:00\",\n    \"repeat\": \"weekly:1\",\n    \"done\": false\n  },\n  {\n    \"id\": \"i9j0k1l2\",\n    \"prompt\": \"Monthly reminder\",\n    \"run_at\": \"2026-06-01 08:00\",\n    \"repeat\": \"monthly:1\",\n    \"done\": false\n  },\n  {\n    \"id\": \"m3n4o5p6\",\n    \"prompt\": \"Ping check\",\n    \"run_at\": \"2026-05-10 12:00\",\n    \"repeat\": \"interval:30m\",\n    \"done\": false\n  }\n]\n```\n\nRepeat modes: `daily`, `weekly:N` (1=Mon), `monthly:N` (day), `interval:30m` / `interval:2h`\n\n## Requirements\n\n- Python 3\n- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot)\n- [psutil](https://github.com/giampaolo/psutil) — for bot status monitoring\n- [OpenCode CLI](https://opencode.ai)\n- [whisper.cpp](https://github.com/ggml-org/whisper.cpp) + model (optional, for voice transcription)\n- [ffmpeg](https://github.com/ffmpeg/ffmpeg) (optional, for audio conversion)\n- [Piper](https://github.com/OHF-Voice/piper1-gpl) + model (optional, for voice output TTS)\n\n## Installation\n\n```bash\npip install python-telegram-bot aiohttp psutil\ngit clone https://github.com/beacoder/telegram_bot.git\ncd telegram_bot\n# Set environment variables, then:\npython telegram_bot.py\n```\n\n## Typical Workflow\n\n1. Send a message, file, or use the interactive `/menu`\n2. Bot downloads \u0026 transcribes if needed, forwards to OpenCode\n3. Agent processes the request locally\n4. Response text (with optional TTS voice) + generated files are returned to Telegram\n\n## Security Notes\n\n- Single-user design — `AUTHORIZED_USER_ID` restricts access\n- Never expose your bot token publicly\n- Run in trusted environments only\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeacoder%2Ftelegram_bot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeacoder%2Ftelegram_bot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeacoder%2Ftelegram_bot/lists"}