Skip to main content

Telegram Bot Troubleshooting

Common issues and solutions for the Loyalteez Telegram bot integration.

Setup Issues​

Bot Not Responding​

Symptoms:

  • Bot doesn't respond to commands
  • Messages sent to bot are ignored
  • Bot appears offline

Possible Causes:

  1. Bot not added to group as administrator
  2. Webhook URL not configured correctly
  3. Bot token invalid or expired
  4. Cloudflare Worker not deployed or misconfigured

Solutions:

1. Check Bot Permissions:

  • Open Telegram group
  • Go to group settings → Administrators
  • Ensure bot is listed as administrator
  • Bot needs admin permissions to respond to commands

2. Verify Webhook Configuration:

# Check webhook status
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

# Set webhook
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-worker.workers.dev"

3. Verify Bot Token:

  • Token should be in format: 123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
  • Get new token from @BotFather if needed
  • Update secret in Cloudflare Workers: wrangler secret put TELEGRAM_BOT_TOKEN

4. Check Worker Deployment:

  • Verify worker is deployed: wrangler deployments list
  • Check worker logs: wrangler tail
  • Verify environment variables are set correctly

/setup Command Not Working​

Symptoms:

  • /setup command doesn't respond
  • Error message: "Only group admins can run /setup"
  • Error message: "Group not set up"

Possible Causes:

  1. User running command is not an admin
  2. Bot doesn't have admin permissions
  3. Brand ID format incorrect
  4. Database connection issue

Solutions:

1. Verify Admin Status:

  • User must be group administrator
  • Bot must be group administrator
  • Check in group settings → Administrators

2. Verify Brand ID Format:

  • Brand ID should be wallet address: 0x1234567890abcdef1234567890abcdef12345678
  • Must be 42 characters (0x + 40 hex characters)
  • Copy from Partner Portal → Settings → Account

3. Check Database Configuration:

  • Verify Supabase credentials are set
  • Check telegram_group_configs table exists
  • Verify database connection in Cloudflare Worker logs

Commands Not Working After Setup​

Symptoms:

  • Commands return "Group not configured" error
  • /balance, /daily, etc. don't work
  • Setup was successful but commands fail

Possible Causes:

  1. Group configuration not saved correctly
  2. Brand ID mismatch
  3. Database query issue
  4. KV cache issue

Solutions:

1. Re-run Setup:

/setup 0xYOUR_BRAND_ID

2. Check Group Configuration:

  • Verify in Supabase: SELECT * FROM telegram_group_configs WHERE telegram_group_id = '<group_id>';
  • Ensure is_active = true
  • Verify brand_id matches your Brand ID

3. Clear KV Cache:

  • KV cache stores group configs with 1-hour TTL
  • Wait 1 hour or manually clear cache
  • Configuration changes take effect after cache expires

Command Issues​

/daily Not Working​

Symptoms:

  • /daily command doesn't respond
  • Error message: "Group not configured"
  • No reward given after check-in

Possible Causes:

  1. Group not set up
  2. Shared services API unavailable
  3. User identifier issue
  4. API rate limit

Solutions:

1. Verify Setup:

  • Run /config to check group configuration
  • Ensure group is connected to a brand

2. Check Shared Services:

  • Verify shared services URL is correct: https://services.loyalteez.app
  • Check shared services status
  • Verify API is responding

3. Check User Identifier:

  • User identifier format: telegram_{user_id}@loyalteez.app
  • Verify user ID is numeric (Telegram user IDs are integers)

4. Check API Rate Limits:

  • Wait a few minutes and try again
  • Check Cloudflare Worker logs for rate limit errors

/balance Shows Zero or Error​

Symptoms:

  • Balance shows 0 LTZ
  • Error message when checking balance
  • Balance not updating

Possible Causes:

  1. User hasn't earned any LTZ yet
  2. Wallet not created
  3. API connection issue
  4. Blockchain RPC issue

Solutions:

1. Verify User Has Earned LTZ:

  • User must earn LTZ first (via /daily, GM/GN, etc.)
  • Check Partner Portal → Analytics for user activity
  • Wallet is created automatically on first reward

2. Check API Connection:

  • Verify Loyalteez API URL: https://api.loyalteez.app
  • Check API status
  • Verify blockchain RPC is accessible

3. Wait for Blockchain Confirmation:

  • Transactions require blockchain confirmation
  • Wait a few minutes and check again
  • Verify transaction on block explorer

/streak Not Showing Milestones​

Symptoms:

  • Streak shows but no milestones
  • Milestone claim buttons not appearing
  • Error when claiming milestone

Possible Causes:

  1. No milestones configured
  2. Milestones already claimed
  3. Shared services API issue
  4. Milestone threshold not reached

Solutions:

1. Check Milestone Configuration:

  • Verify milestones are configured in Partner Portal
  • Check shared services milestone settings
  • Default milestones: 7, 30, 100 days

2. Verify Milestone Status:

  • Check if milestones are already claimed
  • Verify user has reached milestone threshold
  • Check shared services API response

3. Check Shared Services:

  • Verify shared services API is accessible
  • Check API logs for errors
  • Verify milestone endpoint is working

/leaderboard Empty or Not Loading​

Symptoms:

  • Leaderboard shows empty
  • Error loading leaderboard
  • Leaderboard not updating

Possible Causes:

  1. No users have earned LTZ
  2. Shared services API issue
  3. Metric or period filter issue
  4. Cache issue

Solutions:

1. Verify Users Have Earned LTZ:

  • Check Partner Portal → Analytics
  • Ensure users have activity
  • Verify LTZ distribution

2. Check Shared Services:

  • Verify leaderboard API is accessible
  • Check API response in browser console
  • Verify shared services URL is correct

3. Try Different Filters:

  • Try different metrics: ltz_earned, activity, streak
  • Try different periods: week, month, all
  • Check if data exists for selected filters

/perks Not Showing Perks​

Symptoms:

  • Perks list is empty
  • Error loading perks
  • Perk redemption fails

Possible Causes:

  1. No perks configured in Partner Portal
  2. Perks not active
  3. Shared services API issue
  4. Category filter issue

Solutions:

1. Check Perk Configuration:

  • Verify perks are created in Partner Portal
  • Ensure perks are active
  • Check perk availability dates

2. Check Shared Services:

  • Verify perks API is accessible
  • Check API response for errors
  • Verify shared services URL

3. Try Different Categories:

  • Use category="all" to show all perks
  • Check if perks exist in selected category
  • Verify category names match

Natural Participation Issues​

GM/GN Not Detecting​

Symptoms:

  • GM/GN messages not rewarded
  • No response to "gm" or "gn" messages
  • Natural participation not working

Possible Causes:

  1. Natural participation disabled
  2. User on cooldown
  3. Pattern matching issue
  4. Configuration issue

Solutions:

1. Check Configuration:

  • Run /config to check natural participation status
  • Verify naturalParticipation.enabled = true
  • Check reward amounts and cooldowns

2. Check Cooldown:

  • Default cooldown: 24 hours
  • User can only claim GM/GN once per cooldown period
  • Wait for cooldown to expire

3. Verify Patterns:

  • Supported patterns: gm, good morning, gn, good night, etc.
  • Pattern matching is case-insensitive
  • Must be in group messages (not DMs)

4. Check Bot Permissions:

  • Bot must be able to read messages
  • Verify bot has message reading permissions
  • Check group privacy settings

Configuration Issues​

/config Not Working​

Symptoms:

  • /config command doesn't respond
  • Configuration not saving
  • Settings not applying

Possible Causes:

  1. User not an admin
  2. Group not set up
  3. Database connection issue
  4. Configuration format invalid

Solutions:

1. Verify Admin Status:

  • User must be group administrator
  • Run /config as group admin

2. Verify Setup:

  • Group must be set up first (run /setup)
  • Check group configuration exists

3. Use Partner Portal:

  • Advanced configuration available in Partner Portal
  • Navigate to Integrations → Telegram
  • Configure settings in web interface

Deployment Issues​

Cloudflare Worker Not Deploying​

Symptoms:

  • Worker deployment fails
  • Errors during deployment
  • Worker not accessible

Possible Causes:

  1. Wrangler not authenticated
  2. Invalid wrangler.toml configuration
  3. Missing secrets
  4. Build errors

Solutions:

1. Authenticate Wrangler:

wrangler login
wrangler whoami

2. Check wrangler.toml:

  • Verify account_id is set
  • Check KV namespace IDs
  • Verify worker name

3. Set Required Secrets:

wrangler secret put TELEGRAM_BOT_TOKEN
wrangler secret put SUPABASE_PUBLISH_KEY
wrangler secret put SUPABASE_SECRET_KEY

4. Check Build Errors:

  • Review build output
  • Check for syntax errors
  • Verify dependencies are installed

Webhook Not Receiving Updates​

Symptoms:

  • Bot not receiving messages
  • Webhook shows errors
  • Updates not reaching worker

Possible Causes:

  1. Webhook URL incorrect
  2. SSL certificate issue
  3. Worker not responding
  4. Telegram API issue

Solutions:

1. Verify Webhook URL:

# Check webhook info
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

# Set webhook
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-worker.workers.dev"

2. Check SSL Certificate:

  • Webhook URL must use HTTPS
  • Certificate must be valid
  • Cloudflare Workers automatically provide SSL

3. Check Worker Response:

  • Worker must return 200 OK
  • Check worker logs: wrangler tail
  • Verify worker is handling requests

Database Issues​

Group Configuration Not Saving​

Symptoms:

  • /setup succeeds but config not persisted
  • Configuration resets after restart
  • Database errors in logs

Possible Causes:

  1. Database connection issue
  2. Table doesn't exist
  3. Permission issue
  4. Supabase credentials incorrect

Solutions:

1. Check Database Connection:

  • Verify Supabase URL and keys
  • Test connection with curl
  • Check Supabase dashboard

2. Verify Table Exists:

-- Check if table exists
SELECT * FROM telegram_group_configs LIMIT 1;

-- Create table if missing
CREATE TABLE telegram_group_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    telegram_group_id TEXT NOT NULL UNIQUE,
    brand_id TEXT NOT NULL,
    group_name TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    config_metadata JSONB DEFAULT '{}'::jsonb,
    setup_by TEXT,
    setup_at TIMESTAMPTZ DEFAULT NOW(),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

3. Check Permissions:

  • Verify API keys have write permissions
  • Check RLS policies allow inserts
  • Verify service role key is used for writes

Performance Issues​

Bot Responding Slowly​

Symptoms:

  • Commands take long to respond
  • Delayed message delivery
  • Timeout errors

Possible Causes:

  1. Worker cold start
  2. API latency
  3. Database query slow
  4. Rate limiting

Solutions:

1. Check Worker Performance:

  • Cloudflare Workers have fast cold starts
  • Check worker logs for slow operations
  • Optimize database queries

2. Check API Latency:

  • Verify shared services response times
  • Check blockchain RPC latency
  • Use CDN for static assets

3. Optimize Database Queries:

  • Add indexes to frequently queried columns
  • Use KV cache for hot data
  • Batch database operations

Common Error Messages​

"Group not configured"​

Meaning: Group hasn't been set up with /setup command.

Solution: Run /setup <brand_id> as group admin.

"Only group admins can run /setup"​

Meaning: User running command is not a group administrator.

Solution: User must be added as administrator in group settings.

"Failed to setup: [error message]"​

Meaning: Error saving group configuration.

Solution:

  • Check error message for details
  • Verify Brand ID is correct
  • Check database connection
  • Verify Supabase credentials

"An error occurred processing your command"​

Meaning: Generic error during command execution.

Solution:

  • Check Cloudflare Worker logs
  • Verify API connections
  • Check for rate limits
  • Review error details in logs

Debugging Tips​

Enable Logging​

Check Cloudflare Worker logs:

wrangler tail

Check Webhook Status​

curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

Verify Database​

Check group configuration in Supabase:

SELECT * FROM telegram_group_configs WHERE telegram_group_id = '<group_id>';

Test API Endpoints​

Test shared services:

curl "https://services.loyalteez.app/streak/status/<brand_id>/telegram_<user_id>@loyalteez.app"

Getting Help​

If you're still experiencing issues:

  1. Check Documentation:

  2. Review Logs:

    • Cloudflare Worker logs: wrangler tail
    • Supabase logs: Dashboard → Logs
    • Telegram Bot API: Check webhook status

  3. Contact Support:

Need help? [email protected]

Last updated on