236 lines
6.1 KiB
Markdown
236 lines
6.1 KiB
Markdown
# 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
|
|
|