{"id":51037843,"url":"https://github.com/potatoenergy/telegram-ai-replier","last_synced_at":"2026-06-22T08:01:17.183Z","repository":{"id":339460904,"uuid":"1072993767","full_name":"potatoenergy/telegram-ai-replier","owner":"potatoenergy","description":"A modular Telegram bot using AI for business replies","archived":false,"fork":false,"pushed_at":"2026-02-19T19:31:19.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-19T22:24:05.754Z","etag":null,"topics":["ai","bot","composer","docker","php","php8","telegram","telegram-bot","telegrambot"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":false,"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/potatoenergy.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":"2025-10-09T13:36:26.000Z","updated_at":"2026-02-19T19:31:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/potatoenergy/telegram-ai-replier","commit_stats":null,"previous_names":["potatoenergy/telegram-ai-replier"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/potatoenergy/telegram-ai-replier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potatoenergy%2Ftelegram-ai-replier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potatoenergy%2Ftelegram-ai-replier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potatoenergy%2Ftelegram-ai-replier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potatoenergy%2Ftelegram-ai-replier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/potatoenergy","download_url":"https://codeload.github.com/potatoenergy/telegram-ai-replier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/potatoenergy%2Ftelegram-ai-replier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34639715,"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-22T02:00:06.391Z","response_time":106,"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","composer","docker","php","php8","telegram","telegram-bot","telegrambot"],"created_at":"2026-06-22T08:01:16.435Z","updated_at":"2026-06-22T08:01:17.178Z","avatar_url":"https://github.com/potatoenergy.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# telegram-ai-replier\n\nA modular Telegram bot using AI for business replies.\n\n## Compliance Statement\n\n⚠️ **Ethical Usage Requirements**\n\n- Ensure your Telegram Business account complies with [Telegram's Terms of Service](https://telegram.org/tos).\n- Use responsibly and avoid spamming.\n- Be aware of the usage costs associated with your chosen AI provider (OpenAI, Ollama, custom).\n\n## Prerequisites\n\n- A **publicly accessible server** or hosting service capable of receiving HTTPS webhooks from Telegram (for webhook mode).\n- A **domain name** pointing to your server (recommended for HTTPS, webhook mode only).\n- A **Telegram Bot Token** (get it from [@BotFather](https://t.me/BotFather)).\n- An **AI Provider** configured (OpenAI API Key, Ollama instance, or custom OpenAI-compatible API).\n\n## Environment Variables\n\nCopy `.env.example` to `.env` and fill in your values. See the file for full documentation of each variable.\n\n| Variable                    | Purpose                                           | Default                             |\n| --------------------------- | ------------------------------------------------- | ----------------------------------- |\n| `UPDATE_MODE`               | `webhook` or `polling`                            | `webhook`                           |\n| `BOT_TOKEN`                 | Telegram Bot Token                                | —                                   |\n| `ADMIN_USER_IDS`            | Comma-separated tech admin IDs (commands only)    | —                                   |\n| `BUSINESS_USER_ID`          | Business owner ID (AI processing + commands)      | —                                   |\n| `TELEGRAM_WEBHOOK_URL`      | Webhook URL (required for webhook mode)           | —                                   |\n| `TELEGRAM_API_BASE_URL`     | Custom Telegram API base URL                      | `https://api.telegram.org`          |\n| `AI_PROVIDER`               | `openai` or `ollama`                              | —                                   |\n| `OPENAI_API_KEY`            | OpenAI API Key (required if `AI_PROVIDER=openai`) | —                                   |\n| `OPENAI_MODEL`              | OpenAI model name                                 | `gpt-3.5-turbo`                     |\n| `OPENAI_BASE_URL`           | Custom OpenAI-compatible API base URL             | —                                   |\n| `OLLAMA_URL`                | Ollama API URL                                    | `http://host.docker.internal:11434` |\n| `OLLAMA_MODEL`              | Ollama model name                                 | `llama3.2`                          |\n| `AI_MAX_TOKENS`             | Max tokens for AI response                        | `500`                               |\n| `AI_TEMPERATURE`            | AI creativity setting                             | `0.7`                               |\n| `AI_SYSTEM_PROMPT`          | System prompt for AI                              | \"You are a helpful assistant...\"    |\n| `CHAT_HISTORY_SIZE`         | Number of messages kept per chat                  | `10`                                |\n| `PROXY_URL`                 | Proxy for outgoing requests (HTTP/SOCKS4/SOCKS5)  | —                                   |\n| `RATE_LIMIT_WINDOW`         | Rate limit window (seconds)                       | `60`                                |\n| `RATE_LIMIT_MAX_REQUESTS`   | Max requests per window per chat                  | `5`                                 |\n| `MIN_RESPONSE_DELAY`        | Min reply delay (ms)                              | `3000`                              |\n| `MAX_RESPONSE_DELAY`        | Max reply delay (ms)                              | `8000`                              |\n| `CHAT_RESPONSE_PROBABILITY` | Response probability (0.0–1.0)                    | `1.0`                               |\n| `IGNORE_USER_IDS`           | Comma-separated user IDs to ignore                | —                                   |\n| `IGNORE_USER_PATTERNS`      | Comma-separated name patterns to ignore           | —                                   |\n| `MAX_MESSAGE_LENGTH`        | Max AI response length (chars)                    | `4096`                              |\n| `POLLING_TIMEOUT`           | Long polling timeout (seconds)                    | `30`                                |\n| `DEBUG`                     | Enable verbose logging                            | `false`                             |\n\n## Key Features\n\n**1. Dual Update Modes:**\n\n- **Webhook** — instant delivery via HTTPS POST (requires public URL).\n- **Long Polling** — works behind NAT/firewall, no public URL needed.\n- Seamless switching via `UPDATE_MODE` environment variable.\n\n**2. Business Message Handling:**\n\n- Processes `business_message`, `business_connection`, and `deleted_business_messages` events.\n- Handles media captions in addition to plain text.\n- Replies generated by selected AI provider (OpenAI, Ollama, custom).\n\n**3. Role-Based Access Control:**\n\n- **Tech admins** (`ADMIN_USER_IDS`) — manage bot via commands, ignored in business AI processing.\n- **Business owner** (`BUSINESS_USER_ID`) — messages processed by AI + full admin command access.\n\n**4. Contextual AI Conversations:**\n\n- Per-chat message history with configurable size (`CHAT_HISTORY_SIZE`).\n- `/clear` command to reset conversation context in a specific business chat.\n\n**5. Safety \u0026 Timing Controls:**\n\n- Humanized response delay (random between `MIN_RESPONSE_DELAY` and `MAX_RESPONSE_DELAY`).\n- Configurable response probability (`CHAT_RESPONSE_PROBABILITY`).\n- User ignore lists by ID and name patterns.\n- Max response length truncation.\n\n**6. In-Memory Rate Limiting:**\n\n- Sliding-window rate limiting per `chat_id`.\n- No external dependencies (no Redis needed).\n\n**7. Proxy Support:**\n\n- Universal `PROXY_URL` for all outgoing requests (Telegram API, OpenAI API).\n- Supports HTTP, SOCKS4, SOCKS5 with optional authentication.\n\n**8. Modular Command System:**\n\n- Commands in separate classes implementing `CommandInterface`.\n- `/start` — admin configuration panel with full settings overview.\n- `/status` — system diagnostics (API health, rate limiter, update mode).\n- `/clear` — reset AI conversation history in current business chat.\n\n**9. Status Page:**\n\n- Available at webhook URL root (GET request) in both webhook and polling modes.\n- Displays system status, Safety \u0026 Timing settings, API diagnostics, and rate limiter info.\n\n## Setup\n\n1. **Configure Environment:** Copy `.env.example` to `.env` and fill in your values.\n2. **Deploy:** Run `docker-compose up -d` (webhook) or `docker-compose --profile polling up -d` (polling).\n3. **Link Business Account:** In Telegram Business settings → Chatbot → enter your bot username.\n4. **Test:** Send a message to your Telegram Business account. The bot should respond via AI.\n\n## Switching Between Modes\n\n```bash\n# Webhook → Polling\n# Set UPDATE_MODE=polling in .env\ndocker-compose down\ndocker-compose --profile polling up -d\n\n# Polling → Webhook\n# Set UPDATE_MODE=webhook and TELEGRAM_WEBHOOK_URL in .env\ndocker-compose --profile polling down\ndocker-compose up -d\n```\n\n## Technical Architecture\n\n**Processing Pipeline:**\n\n1. Update received via webhook (Nginx → PHP-FPM) or long polling (CLI).\n2. `UpdateHandler` routes update to appropriate handler method.\n3. `SafetyFilter` checks ignore lists and response probability.\n4. Admin/business owner role check determines processing path.\n5. For business messages: rate limit → AI generation with chat history → humanized delay → send.\n6. For commands: delegated to corresponding `CommandInterface` implementation.\n\n**Safety Systems:**\n\n- In-memory sliding-window rate limiting per `chat_id`.\n- User filtering by ID and name patterns.\n- Configurable response probability and humanized delays.\n- Max response length truncation.\n- Input validation and error handling.\n- Debug mode for detailed request logging.\n\n## License\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpotatoenergy%2Ftelegram-ai-replier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpotatoenergy%2Ftelegram-ai-replier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpotatoenergy%2Ftelegram-ai-replier/lists"}