From 54e66f9eb0cb6a61c3af7c91346184631d086087 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 17 Feb 2026 18:43:27 +0000
Subject: [PATCH] feat: integrate telegram bot support

- Add comprehensive Telegram bot setup guide (docs/TELEGRAM_SETUP.md)
- Create quick start guide for rapid Telegram integration (TELEGRAM_QUICKSTART.md)
- Update config.json template to enable Telegram by default
- Update .env template with Telegram bot token configuration
- Add deploy workflow step to configure environment variables from GitHub secrets
- Support PICOCLAW_TELEGRAM_BOT_TOKEN secret for automated deployments

Features:
- Text messages, voice notes (auto-transcribed), images, documents
- Optional user whitelist via allow_from config
- Proxy support for restricted regions
- Commands: /start, /help, /show, /list

Enables:
1. Users to create bot via @BotFather
2. Add PICOCLAW_TELEGRAM_BOT_TOKEN to GitHub Secrets
3. Automated deployment with secrets injection
4. Manual configuration via SSH for direct deployments

https://claude.ai/code/session_019vXaqxGmkdCjM8m3jp6rYj
---
 .github/workflows/deploy-hostinger.yml |  34 ++++
 TELEGRAM_QUICKSTART.md                 |  93 +++++++++++
 deploy/hostinger/setup-server.sh       |  11 +-
 docs/TELEGRAM_SETUP.md                 | 205 +++++++++++++++++++++++++
 4 files changed, 340 insertions(+), 3 deletions(-)
 create mode 100644 TELEGRAM_QUICKSTART.md
 create mode 100644 docs/TELEGRAM_SETUP.md

diff --git a/.github/workflows/deploy-hostinger.yml b/.github/workflows/deploy-hostinger.yml
index de8346ef4..a32f77450 100644
--- a/.github/workflows/deploy-hostinger.yml
+++ b/.github/workflows/deploy-hostinger.yml
@@ -65,6 +65,40 @@ jobs:
             deploy/hostinger/docker-compose.production.yml \
             "${SSH_USER}@${{ secrets.HOSTINGER_HOST }}:${REMOTE_DIR}/docker-compose.yml"
 
+      - name: Configure environment variables
+        env:
+          SSHPASS: ${{ secrets.HOSTINGER_SSH_PASSWORD }}
+        run: |
+          SSH_PORT="${{ secrets.HOSTINGER_SSH_PORT }}"
+          SSH_PORT="${SSH_PORT:-22}"
+          SSH_USER="${{ secrets.HOSTINGER_SSH_USER }}"
+          SSH_USER="${SSH_USER:-root}"
+
+          sshpass -e ssh \
+            -o StrictHostKeyChecking=accept-new \
+            -o ConnectTimeout=15 \
+            -p "${SSH_PORT}" \
+            "${SSH_USER}@${{ secrets.HOSTINGER_HOST }}" <<'EOF'
+          # Update .env with secrets (keep existing values, only override if provided)
+          ENV_FILE="/opt/picoclaw/config/.env"
+
+          # Telegram Bot Token
+          if [ -n "${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}" ]; then
+            grep -q "PICOCLAW_CHANNELS_TELEGRAM_TOKEN" "$ENV_FILE" && \
+              sed -i "s|^PICOCLAW_CHANNELS_TELEGRAM_TOKEN=.*|PICOCLAW_CHANNELS_TELEGRAM_TOKEN=${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}|" "$ENV_FILE" || \
+              echo "PICOCLAW_CHANNELS_TELEGRAM_TOKEN=${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}" >> "$ENV_FILE"
+          fi
+
+          # Anthropic API Key
+          if [ -n "${{ secrets.ANTHROPIC_API_KEY }}" ]; then
+            grep -q "ANTHROPIC_API_KEY" "$ENV_FILE" && \
+              sed -i "s|^ANTHROPIC_API_KEY=.*|ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}|" "$ENV_FILE" || \
+              echo "ANTHROPIC_API_KEY=${{ secrets.ANTHROPIC_API_KEY }}" >> "$ENV_FILE"
+          fi
+
+          echo "Environment variables updated"
+          EOF
+
       - name: Build and restart Docker container
         env:
           SSHPASS: ${{ secrets.HOSTINGER_SSH_PASSWORD }}
diff --git a/TELEGRAM_QUICKSTART.md b/TELEGRAM_QUICKSTART.md
new file mode 100644
index 000000000..7d0970427
--- /dev/null
+++ b/TELEGRAM_QUICKSTART.md
@@ -0,0 +1,93 @@
+# 🤖 PicoClaw Telegram Bot - Quick Start
+
+**Get your PicoClaw AI assistant on Telegram in 3 minutes!**
+
+## ⚡ Quick Setup
+
+### 1️⃣ Get Your Bot Token
+
+1. Open Telegram → Search `@BotFather`
+2. Send `/newbot`
+3. Follow prompts (name + username ending in `_bot`)
+4. **Copy the token** 🔐
+
+### 2️⃣ Add to GitHub Secrets
+
+- Go to your repo: **Settings** → **Secrets and Variables** → **Actions**
+- Click **New repository secret**
+- Name: `PICOCLAW_TELEGRAM_BOT_TOKEN`
+- Value: Your token from step 1
+
+### 3️⃣ Deploy
+
+Push to main branch or trigger workflow:
+```bash
+git push origin main
+```
+
+The bot will be live in ~2 minutes ✨
+
+---
+
+## 🎯 Start Using
+
+Find your bot on Telegram (search username) and send:
+```
+/start
+Hello!
+```
+
+### Commands
+- `/start` - Begin
+- `/help` - Show help
+- `/show` - Agent info
+- `/list` - List agents
+
+### Features
+✨ Text messages
+🎤 Voice notes (auto-transcribed)
+📸 Images
+📄 Documents
+
+---
+
+## 🔧 Manual Setup (Without GitHub Actions)
+
+### SSH Setup
+```bash
+ssh root@YOUR_IP
+nano /opt/picoclaw/config/.env
+```
+
+Add:
+```
+PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
+PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_TOKEN_HERE
+```
+
+Restart:
+```bash
+docker compose -f /opt/picoclaw/docker-compose.yml restart picoclaw
+```
+
+---
+
+## 🛡️ Security
+
+- ⚠️ Never commit tokens to git
+- 🔐 Use GitHub Secrets
+- 👥 Optional: Whitelist users in `allow_from` config
+
+---
+
+## 📚 Full Guide
+
+See [docs/TELEGRAM_SETUP.md](docs/TELEGRAM_SETUP.md) for advanced options.
+
+---
+
+**Questions?** Check logs:
+```bash
+ssh root@YOUR_IP
+tail -f /opt/picoclaw/logs/picoclaw.log | grep -i telegram
+```
diff --git a/deploy/hostinger/setup-server.sh b/deploy/hostinger/setup-server.sh
index 6c959bdb1..2e14fa4bb 100755
--- a/deploy/hostinger/setup-server.sh
+++ b/deploy/hostinger/setup-server.sh
@@ -185,8 +185,12 @@ if [ ! -f "${PICOCLAW_HOME}/config/.env" ]; then
 # OPENROUTER_API_KEY=sk-or-v1-xxx
 # GEMINI_API_KEY=xxx
 
-# ── Chat Channel ─────────────────────────────────────
-# TELEGRAM_BOT_TOKEN=123456:ABC...
+# ── Telegram Bot ─────────────────────────────────────
+# Get token from @BotFather on Telegram
+PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
+PICOCLAW_CHANNELS_TELEGRAM_TOKEN=
+
+# ── Other Chat Channels ──────────────────────────────
 # DISCORD_BOT_TOKEN=xxx
 
 # ── Web Search (optional) ────────────────────────────
@@ -216,8 +220,9 @@ if [ ! -f "${PICOCLAW_HOME}/config/config.json" ]; then
   },
   "channels": {
     "telegram": {
-      "enabled": false,
+      "enabled": true,
       "token": "",
+      "proxy": "",
       "allow_from": []
     }
   },
diff --git a/docs/TELEGRAM_SETUP.md b/docs/TELEGRAM_SETUP.md
new file mode 100644
index 000000000..6437718bb
--- /dev/null
+++ b/docs/TELEGRAM_SETUP.md
@@ -0,0 +1,205 @@
+# PicoClaw Telegram Bot Setup Guide
+
+Complete step-by-step guide to set up PicoClaw as a Telegram bot.
+
+## Prerequisites
+
+- Telegram account
+- Running PicoClaw instance (deployed)
+- GitHub secrets configured (for automated deployment)
+
+## Step 1: Create a Telegram Bot with BotFather
+
+1. Open Telegram and search for **@BotFather**
+2. Start the chat and send `/start`
+3. Send `/newbot` to create a new bot
+4. Follow the prompts:
+   - **Name**: Give your bot a name (e.g., "PicoClaw AI")
+   - **Username**: Must be unique and end with `_bot` (e.g., `picoclaw_bot`)
+5. **Copy the token** provided (looks like `123456789:ABCdefGHIjklMNOpqrSTUvwxYZ`)
+   - ⚠️ **Keep this token secret!** Anyone with this token can control your bot.
+
+## Step 2: Configure PicoClaw
+
+### Option A: Using Environment Variables (Production)
+
+Add to your `.env` file or GitHub Secrets:
+
+```bash
+PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
+PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_BOT_TOKEN_HERE
+```
+
+### Option B: Using config.json (Development)
+
+Edit `config/config.json`:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN_HERE",
+      "proxy": "",
+      "allow_from": []
+    }
+  }
+}
+```
+
+### Optional: User Whitelist
+
+To restrict access to specific users, add their Telegram user IDs:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN_HERE",
+      "allow_from": ["123456789", "987654321"]
+    }
+  }
+}
+```
+
+To find your Telegram user ID:
+1. Send any message to your bot
+2. Check the logs: `cat /opt/picoclaw/logs/picoclaw.log | grep "user_id"`
+3. Your user ID will be in the output
+
+## Step 3: Deploy to Hostinger
+
+### For GitHub Actions Deployment
+
+1. Add the bot token to your GitHub repository secrets:
+   - Go to **Settings** → **Secrets and Variables** → **Actions**
+   - Click **New repository secret**
+   - **Name**: `PICOCLAW_TELEGRAM_BOT_TOKEN`
+   - **Value**: Your BotFather token
+
+2. Update `.github/workflows/deploy-hostinger.yml` to use the secret:
+   ```yaml
+   env:
+     PICOCLAW_CHANNELS_TELEGRAM_ENABLED: "true"
+     PICOCLAW_CHANNELS_TELEGRAM_TOKEN: ${{ secrets.PICOCLAW_TELEGRAM_BOT_TOKEN }}
+   ```
+
+### For Manual Deployment
+
+SSH into your server:
+```bash
+ssh root@YOUR_HOSTINGER_IP
+nano /opt/picoclaw/config/.env
+```
+
+Add:
+```
+PICOCLAW_CHANNELS_TELEGRAM_ENABLED=true
+PICOCLAW_CHANNELS_TELEGRAM_TOKEN=YOUR_BOT_TOKEN
+```
+
+Restart the container:
+```bash
+cd /opt/picoclaw && docker compose -f docker-compose.production.yml restart picoclaw
+```
+
+## Step 4: Start Using Your Bot
+
+1. Find your bot on Telegram (search by username: @your_bot_username)
+2. Send `/start` to initialize
+3. Start chatting!
+
+### Available Commands
+
+- `/start` - Initialize the bot
+- `/help` - Show available commands
+- `/show` - Show current agent info
+- `/list` - List available agents
+
+### Features
+
+✅ **Text Messages** - Ask questions, get AI responses
+✅ **Voice Messages** - Send voice notes (auto-transcribed)
+✅ **Images** - Send photos for analysis
+✅ **Documents** - Share files for processing
+✅ **Multi-agent** - Switch between different AI agents
+✅ **Thinking Indicator** - See when the AI is processing
+
+## Step 5: Verify It's Working
+
+Check the logs to confirm the bot is running:
+
+```bash
+ssh root@YOUR_HOSTINGER_IP
+tail -f /opt/picoclaw/logs/picoclaw.log | grep -i telegram
+```
+
+You should see:
+```
+[INFO] [telegram] Starting Telegram bot (polling mode)...
+[INFO] [telegram] Telegram bot connected
+```
+
+Send a test message to your bot and check:
+```bash
+tail -f /opt/picoclaw/logs/picoclaw.log | grep -i "Received message"
+```
+
+## Troubleshooting
+
+### Bot doesn't respond
+
+1. Check if Telegram is enabled:
+   ```bash
+   docker exec picoclaw cat /opt/picoclaw/config/.env | grep TELEGRAM
+   ```
+
+2. Verify the token is correct (no spaces, exact copy from BotFather)
+
+3. Check logs for errors:
+   ```bash
+   docker exec picoclaw tail -100 /opt/picoclaw/logs/picoclaw.log | grep -i telegram
+   ```
+
+### "Failed to create telegram bot"
+
+- Token is invalid or expired
+- Token is incomplete (missing characters)
+- Try creating a new bot with BotFather
+
+### "Message rejected by allowlist"
+
+- Your Telegram user ID is not in the whitelist
+- Check your actual ID by removing `allow_from` temporarily
+- Add your ID to the whitelist
+
+## Advanced: Using Proxy
+
+If you're in a region with restricted access to Telegram, configure a proxy:
+
+```json
+{
+  "channels": {
+    "telegram": {
+      "enabled": true,
+      "token": "YOUR_BOT_TOKEN_HERE",
+      "proxy": "socks5://user:pass@proxy-host:1080",
+      "allow_from": []
+    }
+  }
+}
+```
+
+## Security Notes
+
+⚠️ **Never commit your bot token to version control**
+⚠️ **Use GitHub Secrets for CI/CD deployments**
+⚠️ **Consider using user whitelists for sensitive deployments**
+⚠️ **Regularly rotate tokens if compromised**
+
+## Getting Help
+
+- Telegram Bot API Docs: https://core.telegram.org/bots
+- BotFather Commands: https://core.telegram.org/bots#botfather
+- PicoClaw Issues: https://github.com/sipeed/picoclaw/issues