feat: add Telegram bot integration

[freddycodes23]

Description of the Change

Problem

PentAGI has no mobile-friendly access method. Users must use a browser to access the web UI,
which is cumbersome on mobile devices and requires managing SSL certificate warnings.
The env vars TELEGRAM_BOT_TOKEN, TELEGRAM_ENABLED, TELEGRAM_ALLOWED_USER_IDS and
TELEGRAM_POLLING exist in the installer but are never consumed by the application binary.

Solution

Implements a Telegram bot integration in a new pkg/telegram package that runs as a goroutine
alongside the existing HTTP server. Users whitelisted by Telegram user ID can create flows,
check status, and control agents directly from the Telegram mobile app using simple commands.

Closes #

---

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• 🚀 New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Configuration change
• 🧪 Test update
• 🛡️ Security update

---

Areas Affected

• Core Services (Frontend UI/Backend API)
• AI Agents (Researcher/Developer/Executor)
• Security Tools Integration
• Memory System (Vector Store/Knowledge Base)
• Monitoring Stack (Grafana/OpenTelemetry)
• Analytics Platform (Langfuse)
• External Integrations (LLM/Search APIs)
• Documentation
• Infrastructure/DevOps

---

Testing and Verification

Test Configuration

PentAGI Version: 2.0.0-2ec8ef3
Docker Version: 27.x
Host OS: Ubuntu 24.04.3 LTS
LLM Provider: DeepSeek, Gemini, Kimi
Enabled Features: Telegram polling

Test Steps

1. Add TELEGRAM_BOT_TOKEN, TELEGRAM_ENABLED=true, TELEGRAM_ALLOWED_USER_IDS,
   TELEGRAM_POLLING=true to .env
2. Add the four TELEGRAM_* vars to the environment: block in docker-compose.yml
3. Restart with docker compose up -d --force-recreate pentagi
4. Open Telegram, find @Fr22dybot, send /start
5. Send /help to verify command list appears
6. Send /new scan for open ports to verify flow creation
7. Send /flows to verify flow appears in list
8. Send /status <flow_id> to verify status response

Test Results

• Bot authorises successfully on startup and logs Telegram bot authorized as @Fr22dybot
• All commands respond within 2 seconds
• Non-whitelisted user IDs are blocked and logged
• Graceful shutdown stops polling cleanly when container stops

---

Security Considerations

• Bot only responds to Telegram user IDs listed in TELEGRAM_ALLOWED_USER_IDS —
  all other users are silently ignored and logged
• Bot token is loaded from environment variable, never hardcoded
• No new network ports are opened — bot uses outbound polling only
• User ID validation happens before any service call in auth.go

---

Performance Impact

• Bot runs as a single lightweight goroutine — negligible CPU and memory overhead
• Uses long-polling with 60s timeout — one persistent outbound connection to Telegram API
• No impact on existing HTTP server performance

---

Documentation Updates

• README.md updates — add Telegram setup section under Configuration
• API documentation updates
• Configuration documentation updates — document the four new env vars
• GraphQL schema updates
• Other

---

Deployment Notes

Four new environment variables must be set to enable the bot. If TELEGRAM_ENABLED is false
or unset, the bot goroutine does not start and there is zero overhead.

TELEGRAM_BOT_TOKEN=<token from @BotFather>
TELEGRAM_ENABLED=true
TELEGRAM_ALLOWED_USER_IDS=<comma-separated Telegram user IDs>
TELEGRAM_POLLING=true

These must also be added to the environment: block in docker-compose.yml:

- TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN:-}
- TELEGRAM_ENABLED=${TELEGRAM_ENABLED:-false}
- TELEGRAM_ALLOWED_USER_IDS=${TELEGRAM_ALLOWED_USER_IDS:-}
- TELEGRAM_POLLING=${TELEGRAM_POLLING:-true}

No database migrations required. No breaking changes to existing deployments.

---

Checklist

Code Quality

• My code follows the project's coding standards
• I have added/updated necessary documentation
• I have added tests to cover my changes
• All new and existing tests pass
• I have run go fmt and go vet (for Go code)
• I have run npm run lint (for TypeScript/JavaScript code)

Security

• I have considered security implications
• Changes maintain or improve the security model
• Sensitive information has been properly handled

Compatibility

• Changes are backward compatible
• Breaking changes are clearly marked and documented
• Dependencies are properly updated

Documentation

• Documentation is clear and complete
• Comments are added for non-obvious code
• API changes are documented

---

Additional Notes

This PR activates env vars (TELEGRAM_BOT_TOKEN etc.) that the PentAGI installer already
generates but the binary never consumed. The implementation uses the well-maintained
go-telegram-bot-api/telegram-bot-api/v5 library. Unit tests will be added in a follow-up
PR once the maintainers confirm the interface design aligns with internal service conventions.

[Copilot]

Pull request overview

Adds an initial Telegram bot implementation intended to let whitelisted Telegram users create/list/manage “flows” via bot commands.

Changes:

• Introduces pkg/telegram package with bot polling loop, authorization, command handling, and message formatting.
• Defines a FlowService interface and Flow DTO to decouple Telegram command handling from backend flow logic.
• Adds Markdown-formatted responses for /start, /help, /flows, /new, /status, and /stop.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 10 comments.

File	Description
pkg/telegram/bot.go	Bot creation, polling loop, authorization check, start/stop lifecycle
pkg/telegram/handler.go	Command routing and service calls; message reply helper
pkg/telegram/formatter.go	Markdown response formatting for help/welcome/flow outputs
pkg/telegram/auth.go	Allowlist-based authorization helper

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[freddycodes23]

@copilot apply changes based on the comments in this thread