projects/pi-telegram-247/SETUP.md

# Setup Guide

## Step 1: Create Telegram Bot

1. Open Telegram and message [@BotFather](https://t.me/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

```bash
# 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