honey-be/TELEGRAM_SETUP.md

Telegram Bot and Mini App Setup Guide

This guide explains how to set up a Telegram bot and mini app for the Honey project.

Step 1: Create a Telegram Bot

1. Open Telegram and search for @BotFather

2. Start a conversation with BotFather:

   /start
   

3. Create a new bot:

   /newbot
   

4. Follow the prompts:

   • Enter a name for your bot (e.g., "Honey Bot")
   • Enter a username for your bot (must end with bot, e.g., "honey_bot")

5. Save the Bot Token:

   • BotFather will provide you with a token like: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
   • IMPORTANT: Keep this token secret! It's used to authenticate your bot
   • Add this token to your backend environment variables as TELEGRAM_BOT_TOKEN

Step 2: Configure Bot Settings

1. Set bot description (optional):

   /setdescription
   

   Select your bot and enter a description.

2. Set bot commands (optional):

   /setcommands
   

   Select your bot and enter commands (e.g., /start - Start the bot)

3. Set bot photo (optional):

   /setuserpic
   

   Select your bot and upload a photo.

Step 3: Create a Mini App

1. Open BotFather and select your bot

2. Create a new mini app:

   /newapp
   

3. Follow the prompts:

   • Select your bot
   • Enter a title for your mini app (e.g., "Honey")
   • Enter a short name (e.g., "honey")
   • Enter a description
   • Upload an icon (512x512 PNG, max 100KB)
   • Upload a photo (640x360 JPG/PNG, max 5MB) - optional
   • Upload a GIF (640x360, max 1MB) - optional

4. Set the Mini App URL:

   • BotFather will ask for the Web App URL
   • For Railway deployment: Use your Railway frontend URL

     https://your-frontend.railway.app
     

   • For Inferno deployment: Use your domain

     https://your-domain.com
     

   • For local development: Use a tunnel service like ngrok

     https://your-ngrok-url.ngrok.io
     

5. Save the Mini App Link:

   • BotFather will provide you with a link like: https://t.me/your_bot/honey
   • This is the link users will use to open your mini app

Step 4: Configure Web App Settings

For Railway Deployment

1. Get your frontend URL from Railway:

   • Go to your frontend service in Railway
   • Go to "Settings" → "Networking"
   • Copy the generated domain (e.g., https://honey-fe-production.up.railway.app)

2. Update BotFather with this URL:

   /newapp
   

   Select your bot and update the Web App URL

For Inferno Deployment

1. Get your domain (e.g., https://honey.yourdomain.com)

2. Update BotFather with this URL:

   /newapp
   

   Select your bot and update the Web App URL

For Local Development

1. Use ngrok to create a tunnel:

   ngrok http 5173
   

2. Copy the HTTPS URL (e.g., https://abc123.ngrok.io)

3. Update BotFather with this URL:

   /newapp
   

   Select your bot and update the Web App URL

4. Update your frontend .env file:

   VITE_API_BASE_URL=https://your-backend-url.railway.app
   

Step 5: Test the Mini App

1. Open Telegram and search for your bot (e.g., @honey_bot)

2. Start the bot:

   /start
   

3. Open the mini app:

   • Click the button in the bot chat (if you added one)
   • Or use the link: https://t.me/your_bot/honey
   • Or use the menu button (if configured)

4. Verify authentication:

   • The mini app should load your frontend
   • The frontend should successfully authenticate with the backend
   • Check browser console for any errors

Step 6: Configure Bot Menu (Optional)

You can add a menu button to your bot that opens the mini app:

1. Open BotFather:

   /mybots
   

2. Select your bot:

   Bot Settings → Menu Button
   

3. Configure menu button:

   • Select "Configure Menu Button"
   • Enter button text (e.g., "Open Honey")
   • Enter the mini app URL or select from your apps

Step 7: Security Considerations

1. Keep Bot Token Secret:

   • Never commit the bot token to version control
   • Use environment variables or secret files (as configured in the backend)

2. Validate initData:

   • The backend automatically validates Telegram's initData signature
   • This ensures requests are coming from legitimate Telegram users

3. HTTPS Required:

   • Telegram mini apps require HTTPS
   • Use Railway's automatic HTTPS or configure SSL on Inferno

Step 8: Troubleshooting

Mini App Not Loading

• Check URL: Verify the Web App URL in BotFather matches your frontend URL
• Check HTTPS: Ensure your frontend is served over HTTPS
• Check CORS: Verify backend CORS configuration includes Telegram domains
• Check Console: Open browser developer tools and check for errors

Authentication Failing

• Check Bot Token: Verify TELEGRAM_BOT_TOKEN is correct in backend environment
• Check initData: Verify frontend is sending Authorization: tma <initData> header
• Check Backend Logs: Review backend logs for authentication errors

Bot Not Responding

• Check Bot Status: Verify bot is active in BotFather
• Check Commands: Verify bot commands are set correctly
• Check Token: Verify bot token is correct

Additional Resources

• Telegram Bot API Documentation
• Telegram Mini Apps Documentation
• BotFather Commands

Quick Reference

BotFather Commands

/newbot          - Create a new bot
/setdescription  - Set bot description
/setcommands     - Set bot commands
/newapp          - Create/update mini app
/mybots          - Manage your bots

Environment Variables

TELEGRAM_BOT_TOKEN=your_bot_token_here
FRONTEND_URL=https://your-frontend-url.com

Testing Locally

1. Start backend: mvn spring-boot:run or docker-compose up
2. Start frontend: npm run dev
3. Use ngrok: ngrok http 5173
4. Update BotFather with ngrok URL
5. Test mini app in Telegram