Created base BE. Auth + /current endpoint
This commit is contained in:
AddictionGames
235
TELEGRAM_SETUP.md
Normal file
235
TELEGRAM_SETUP.md
Normal file
@@ -0,0 +1,235 @@
|
||||
# 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:
|
||||
```bash
|
||||
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:
|
||||
```env
|
||||
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](https://core.telegram.org/bots/api)
|
||||
- [Telegram Mini Apps Documentation](https://core.telegram.org/bots/webapps)
|
||||
- [BotFather Commands](https://core.telegram.org/bots/tools#botfather)
|
||||
|
||||
## 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
|
||||
|
||||
```env
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user