# Telegram Bot Testing Guide

## Why Telegram?
- ✅ **Completely FREE** - No costs at all
- ✅ **Instant setup** - 2 minutes to get started
- ✅ **Real API** - Test actual HTTP requests, not mocks
- ✅ **Immediate testing** - Use your own phone
- ✅ **No verification** - No business account needed

## Setup Steps (5 minutes)

### 1. Create a Telegram Bot

1. Open Telegram on your phone
2. Search for `@BotFather`
3. Send `/newbot` command
4. Choose a name for your bot (e.g., "My Campaign Tester")
5. Choose a username (e.g., "mycampaign_test_bot")
6. **Copy the bot token** (looks like: `1234567890:ABCdefGHIjklMNOpqrsTUVwxyz`)

### 2. Get Your Telegram User ID

**Option A: Quick way**
1. Search for `@userinfobot` on Telegram
2. Start a chat with it
3. It will reply with your user ID (e.g., `123456789`)

**Option B: Manual way**
1. Start a chat with your new bot (search for the username you created)
2. Send any message to it (e.g., "hello")
3. Open this URL in browser (replace `<YOUR_BOT_TOKEN>`):
   ```
   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
   ```
4. Find your user ID in the JSON response under `"from": {"id": 123456789}`

### 3. Configure Your App

Edit `backend/.env` or `docker-compose.yml`:

```env
WHATSAPP_PROVIDER=telegram
TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
```

### 4. Add Yourself as a Contact

In your app's Contacts page:
- **Phone**: Your Telegram user ID (e.g., `123456789`)
- **First Name**: Your name
- **Opted In**: ✅ Check this box
- Click "Create"

### 5. Create Campaign and Send

1. Create a template (e.g., "Hello {{first_name}}!")
2. Create a list and add your contact
3. Create a campaign with that template and list
4. Click "Send"
5. Trigger the worker:
   ```bash
   curl -X POST http://localhost:8000/api/workers/tick
   ```

6. **Check your Telegram** - you'll receive the message! 🎉

## What You'll See

### In Your App
- Campaign status: `sending` → `done`
- Recipient status: `pending` → `sent`
- Real Telegram message IDs
- Actual error messages if something fails

### On Your Phone
- Real message from your bot
- Variables replaced ({{first_name}} → your actual name)
- Instant delivery

## Testing Different Scenarios

### Test Opt-in Enforcement
1. Create contact with `opted_in = false`
2. Try sending with regular template (not WhatsApp approved)
3. View campaign → See error: "Contact not opted in"

### Test Multiple Contacts
1. Get Telegram IDs from friends/family
2. Add them as contacts (with permission!)
3. Send campaign to the list
4. Everyone receives the message

### Test Rate Limiting
- Set `MAX_MESSAGES_PER_MINUTE=2` in config
- Send to 10 contacts
- Watch messages sent slowly (respects rate limit)

## Troubleshooting

### "Failed to send Telegram message: 400 Bad Request"
- **Cause**: Invalid chat ID (user ID)
- **Fix**: Make sure user has started a chat with your bot first

### "Failed to send Telegram message: 401 Unauthorized"
- **Cause**: Invalid bot token
- **Fix**: Double-check the token from @BotFather

### "Contact not opted in"
- **Fix**: Check the "Opted In" checkbox when creating contact

## Switch Between Providers

```env
# For mock testing (no external calls)
WHATSAPP_PROVIDER=mock

# For Telegram testing (free, real API)
WHATSAPP_PROVIDER=telegram
TELEGRAM_BOT_TOKEN=your-token

# For production WhatsApp
WHATSAPP_PROVIDER=cloud
WHATSAPP_CLOUD_ACCESS_TOKEN=your-token
WHATSAPP_CLOUD_PHONE_NUMBER_ID=your-id
```

## Production Checklist

Once Telegram testing looks good:
1. ✅ All campaigns working
2. ✅ Error handling tested
3. ✅ Rate limiting working
4. ✅ Opt-in enforcement verified
5. ✅ DND list tested
6. → **Ready to switch to WhatsApp Cloud API!**

---

**Happy Testing! 🚀**