sendio/TELEGRAM_TESTING.md

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:

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:

   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

# 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! 🚀