# 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