roa2web-service-auto/deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md

ROA2WEB Telegram Bot - Windows Deployment Troubleshooting Guide

This guide helps diagnose and fix common issues with Telegram bot integration on Windows Server deployments.

Problem: "Link invalid sau expirat" (Invalid or expired link)

When users generate a linking code in the web frontend but the Telegram bot says the code is invalid or expired, this indicates a communication problem between the backend and telegram bot services.

Root Cause

The backend cannot communicate with the Telegram bot's internal API to save the generated linking codes.

Diagnostic Steps

Run these PowerShell commands on the Windows Server (10.0.20.36) to diagnose:

1. Check Telegram Bot Service Status

# Check if service is running
Get-Service ROA2WEB-TelegramBot

# Expected output:
# Status   Name                    DisplayName
# ------   ----                    -----------
# Running  ROA2WEB-TelegramBot     ROA2WEB Telegram Bot Service

If service is not running, start it:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Start-TelegramBot.ps1

2. Check Internal API Port (8002)

# Check if port 8002 is listening
netstat -ano | findstr :8002

# Expected output (should show LISTENING):
# TCP    127.0.0.1:8002    0.0.0.0:0    LISTENING    <PID>

If port is not listening, the telegram bot service may not have started correctly. Check logs:

# View service logs
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50

# View error logs
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50

3. Test Internal API Health Endpoint

# Test if internal API responds
Invoke-WebRequest http://localhost:8002/internal/health

# Expected output:
# StatusCode        : 200
# StatusDescription : OK
# Content           : {"status":"healthy","timestamp":"2025-...","database_stats":{...}}

If this fails, the internal API is not running. Check telegram bot service logs.

4. Check Backend .env Configuration

# View backend .env file
notepad C:\inetpub\wwwroot\roa2web\backend\.env

# Look for this line:
# TELEGRAM_BOT_INTERNAL_API=http://localhost:8002

If the line is missing or incorrect, add/fix it:

TELEGRAM_BOT_INTERNAL_API=http://localhost:8002

Then restart backend service:

Restart-Service ROA2WEB-Backend

5. Check Telegram Bot .env Configuration

# View telegram bot .env file
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Verify these settings:
# TELEGRAM_BOT_TOKEN=<your_production_bot_token>
# BACKEND_URL=http://localhost:8000
# INTERNAL_API_PORT=8002
# INTERNAL_API_HOST=127.0.0.1

If TELEGRAM_BOT_TOKEN is wrong (e.g., still using DEV token), update it and restart:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

6. Test Full Linking Flow

# 1. Test backend can reach telegram bot internal API
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'

# Expected output:
# StatusCode: 201 (Created)
# Content: {"success":true,"code":"TEST1234","expires_at":"...","message":"..."}

# 2. Verify code was saved
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234"}'

# Expected output:
# StatusCode: 200 (OK)
# Content: {"valid":true,"oracle_username":"testuser","message":"Code is valid"}

If step 1 fails, there's a network/firewall issue blocking localhost:8002.

Solution Checklist

Fix the issue by following this checklist in order:

• Telegram bot service is running

  Get-Service ROA2WEB-TelegramBot
  # If stopped: cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts; .\Start-TelegramBot.ps1
  

• Internal API port 8002 is listening

  netstat -ano | findstr :8002
  # Should show LISTENING on 127.0.0.1:8002
  

• Internal API responds to health checks

  Invoke-WebRequest http://localhost:8002/internal/health
  # Should return 200 OK with status "healthy"
  

• Backend .env has TELEGRAM_BOT_INTERNAL_API configured

  notepad C:\inetpub\wwwroot\roa2web\backend\.env
  # Add: TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
  

• Backend service restarted after .env changes

  Restart-Service ROA2WEB-Backend
  

• Telegram bot .env has correct TELEGRAM_BOT_TOKEN

  notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
  # Should have ROA2WEBBot token, not ROA2WEBDEVBot token
  

• Test full linking flow from web frontend

  • Log in to web frontend (http://10.0.20.36)
  • Generate linking code
  • Send code to @ROA2WEBBot via /start CODE12345
  • Should receive success message from bot

Common Issues

Issue 1: Port 8002 Already in Use

Symptoms:

• Telegram bot service fails to start
• Logs show "Address already in use" or "Port 8002 is already allocated"

Solution:

# Find process using port 8002
netstat -ano | findstr :8002

# Kill the process (replace <PID> with actual process ID)
taskkill /PID <PID> /F

# Restart telegram bot service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

Issue 2: Firewall Blocking Localhost

Symptoms:

• Backend cannot reach http://localhost:8002
• Connection timeout errors in backend logs

Solution:

# Add firewall rule for port 8002 (localhost only)
New-NetFirewallRule -DisplayName "ROA2WEB Telegram Bot Internal API" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow -LocalAddress 127.0.0.1

Issue 3: Wrong Bot Token

Symptoms:

• Telegram bot service runs but doesn't respond to commands
• Logs show "Unauthorized" or "Invalid bot token"

Solution:

# Update .env with correct token from @BotFather
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Change TELEGRAM_BOT_TOKEN to production bot token:
# TELEGRAM_BOT_TOKEN=<production_bot_token>

# Restart service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

Issue 4: SQLite Database Locked

Symptoms:

• Telegram bot logs show "database is locked" errors
• Commands fail intermittently

Solution:

# Stop service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Stop-TelegramBot.ps1

# Wait 10 seconds for locks to release
Start-Sleep -Seconds 10

# Start service
.\Start-TelegramBot.ps1

Verification Steps

After fixing, verify the complete flow works:

1. Backend can save codes to telegram bot:

   Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
   

   Expected: 201 Created with success message

2. Telegram bot can verify codes:

   Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01"}'
   

   Expected: 200 OK with "valid":true

3. End-to-end test from web frontend:

   • Open web app: http://10.0.20.36
   • Login with Oracle credentials
   • Click "Link Telegram Account"
   • Copy the 8-character code
   • Send to @ROA2WEBBot: /start CODE12345
   • Should receive: "Contul tău Telegram a fost asociat cu succes!"

Getting Help

If issues persist after following this guide:

1. Collect diagnostic information:

   # Service status
   Get-Service ROA2WEB-TelegramBot | Format-List *
   
   # Port listening
   netstat -ano | findstr :8002
   
   # Recent logs (last 100 lines)
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 100
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
   
   # Backend logs
   Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 100
   

2. Check configuration files:

   # Backend .env (sanitize sensitive data before sharing!)
   Get-Content C:\inetpub\wwwroot\roa2web\backend\.env
   
   # Telegram bot .env (sanitize bot token before sharing!)
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\.env
   

3. Contact support with the collected diagnostic information.

---

Quick Reference Commands

Service Management

# Check status
Get-Service ROA2WEB-TelegramBot

# Start
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Start-TelegramBot.ps1

# Stop
.\Stop-TelegramBot.ps1

# Restart
.\Restart-TelegramBot.ps1

Monitoring

# Watch logs in real-time
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Wait -Tail 50

# Check health
Invoke-WebRequest http://localhost:8002/internal/health

# Check database stats
Invoke-WebRequest http://localhost:8002/internal/stats

Configuration

# Edit backend config
notepad C:\inetpub\wwwroot\roa2web\backend\.env

# Edit telegram bot config
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Restart after changes
Restart-Service ROA2WEB-Backend
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1