140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# 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! 🚀**
|