projects/pi-telegram-247/SETUP.md

Setup Guide

Step 1: Create Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot
3. Choose a name for your bot
4. Choose a username (must end in bot)
5. Copy the bot token (format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11)

Step 2: Get LLM API Key

Anthropic (Recommended)

1. Go to https://console.anthropic.com
2. Create account / sign in
3. Go to API Keys
4. Create new key

OpenAI

1. Go to https://platform.openai.com
2. Create account / sign in
3. Go to API Keys
4. Create new key

Step 3: Deploy to Render

Option A: One-Click Deploy

1. Fork this repo to your GitHub
2. Log in to Render
3. New → Background Worker
4. Connect your forked repo
5. Render will auto-detect render.yaml
6. Add environment variables:
   • TELEGRAM_BOT_TOKEN - Your bot token
   • ANTHROPIC_API_KEY - Your API key
7. Create Service

Option B: Manual Setup

1. Create new Background Worker on Render
2. Connect GitHub repo
3. Settings:
   • Runtime: Docker
   • Dockerfile: ./Dockerfile
4. Add environment variables as above
5. Add 10GB disk mount at /data
6. Deploy

Step 4: Connect Telegram

After deployment:

1. In Render logs, look for the pairing code
2. Open Telegram and find your bot
3. Send /start
4. The bot will show connection status

Step 5: Using the Bot

Basic Chat

Just send any message to the bot.

Commands

• /start - Show help
• /new - Start fresh session
• /stop - Abort current response
• /status - Show bot status

Media Support

• Send photos → Bot analyzes them
• Send documents → Bot reads them
• Send voice → Bot processes them

Troubleshooting

Bot not responding

1. Check Render logs for errors
2. Verify bot token is correct
3. Ensure API key is valid

Session errors

1. Check /data disk is mounted
2. Verify disk has space

Rate limiting

• Pi handles this automatically
• Responses may be delayed during high load

Local Development

# Clone repo
git clone https://github.com/yourusername/pi-telegram-247.git
cd pi-telegram-247

# Setup
./scripts/setup.sh

# Configure
cp .env.example .env
# Edit .env with your keys

# Run
./scripts/run.sh

Architecture Notes

• Pi runs in RPC mode (headless)
• Telegram extension handles bot connection
• Sessions persist in /data/pi-sessions/
• Config stored in /data/pi-config/
• Long polling (no webhooks needed)

Cost Estimate

• Render Starter: ~$7/month
• Pi API usage: Depends on usage
  • Claude Sonnet 4: ~$3/M input, $15/M output
  • Typical usage: $5-20/month