littleshop/BOT_REGISTRATION.md

# TeleBot Registration Guide

This guide covers setting up and registering Telegram bots with LittleShop.

## 📋 Overview

TeleBot integrates with LittleShop to provide:
- Product browsing via Telegram
- Order creation and checkout
- Payment processing notifications
- Order tracking and customer support

## 🤖 Bot Registration Workflow

### Automatic Registration (Recommended)

TeleBot automatically registers itself on first startup if not already registered:

**Startup Flow:**
1. TeleBot starts and checks for `BotManager:ApiKey` in configuration
2. If missing, queries LittleShop for existing bot by Telegram username
3. If bot exists, reuses existing BotKey
4. If bot doesn't exist, registers new bot and saves BotKey

**No manual intervention required** - just ensure the bot token is configured.

### Manual Registration (Alternative)

If you need to manually register a bot (for testing or troubleshooting):

## 🚀 Quick Start (First Time Setup)

### 1. Create Telegram Bot

**Use BotFather to create a new bot:**

```
1. Open Telegram and search for @BotFather
2. Send: /newbot
3. Enter bot name: "TeleShop"
4. Enter bot username: "Teleshopio_bot" (must be unique, ends in "bot")
5. BotFather responds with:
   - Bot Token: 8254383681:AAE_j4cUIP9ABVE4Pqrmtgjfmqq1yc4Ow5A
   - Bot Username: @Teleshopio_bot
   - Bot ID: 8254383681
```

**Save the bot token** - you'll need it for configuration.

### 2. Configure Bot Token in Gitea Secrets

**For CT109 Pre-Production:**

1. Navigate to Gitea repository: https://git.silverlabs.uk/Jamie/littleshop
2. Go to **Settings → Secrets**
3. Add new secret:
   - Name: `CT109_TELEGRAM_BOT_TOKEN`
   - Value: `8254383681:AAE_j4cUIP9ABVE4Pqrmtgjfmqq1yc4Ow5A`
4. Save

**For Production VPS:**

Add production bot token (use a different bot for production!):
- Name: `TELEGRAM_BOT_TOKEN`
- Value: `<your-production-bot-token>`

### 3. Deploy via CI/CD

Push code to trigger automatic deployment:

```bash
git push origin main
```

**CI/CD automatically:**
- Pulls bot token from Gitea secrets
- Starts TeleBot container with token
- TeleBot auto-registers with LittleShop on startup

### 4. Verify Bot Registration

**Check TeleBot logs:**
```bash
# SSH to CT109
ssh sysadmin@10.0.0.51

# View logs
docker logs telebot-service --tail 100 | grep -i "registration\|botkey"
```

**Expected output:**
```
[12:34:56 INF] Bot not registered yet, checking for existing bot by username...
[12:34:56 INF] Found existing bot: Teleshopio_bot (ID: guid)
[12:34:56 INF] Reusing existing BotKey: ********
[12:34:56 INF] Bot authenticated successfully
[12:34:57 INF] Bot started successfully: @Teleshopio_bot
```

**Or if new registration:**
```
[12:34:56 INF] Bot not registered yet, checking for existing bot by username...
[12:34:56 WRN] No existing bot found, registering new bot...
[12:34:56 INF] Bot registered successfully: Teleshopio_bot
[12:34:56 INF] Received BotKey: ********
[12:34:57 INF] Bot started successfully: @Teleshopio_bot
```

### 5. Test Bot

**Open Telegram and search for your bot:**
```
1. Search: @Teleshopio_bot
2. Click "Start"
3. Bot should respond with: "Welcome to TeleShop!"
```

## 🔧 Manual Bot Registration (API)

If automatic registration fails, use the API directly:

### Register New Bot

**Endpoint:** `POST /api/bots/register`

**Request:**
```bash
curl -X POST http://10.0.0.51:5100/api/bots/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Teleshopio_bot",
    "description": "TeleShop Telegram Bot for CT109",
    "type": 1,
    "version": "1.0.0",
    "personalityName": "Helpful Assistant",
    "initialSettings": {
      "platformType": "Telegram",
      "platformUsername": "Teleshopio_bot",
      "platformId": "8254383681"
    }
  }'
```

**Response:**
```json
{
  "botId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "botKey": "bot_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
  "name": "Teleshopio_bot",
  "settings": {
    "platformType": "Telegram",
    "platformUsername": "Teleshopio_bot",
    "platformId": "8254383681"
  }
}
```

**Save the `botKey`** - you'll need it for configuration.

### Find Existing Bot

**Endpoint:** `GET /api/bots/by-platform/{platformType}/{platformUsername}`

**Request:**
```bash
curl http://10.0.0.51:5100/api/bots/by-platform/1/Teleshopio_bot
```

**Platform Types:**
- `1` = Telegram
- `2` = Discord
- `3` = Slack

**Response:**
```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Teleshopio_bot",
  "botKey": "bot_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c",
  "status": "Active",
  "lastSeenAt": "2025-11-18T17:30:00Z"
}
```

### Authenticate Bot

**Endpoint:** `POST /api/bots/authenticate`

**Request:**
```bash
curl -X POST http://10.0.0.51:5100/api/bots/authenticate \
  -H "Content-Type: application/json" \
  -d '{
    "botKey": "bot_7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c"
  }'
```

**Response:**
```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "Teleshopio_bot",
  "isAuthenticated": true,
  "settings": {}
}
```

## ⚙️ Configuration

### TeleBot Configuration File

**File:** `TeleBot/TeleBot/appsettings.json`

```json
{
  "Telegram": {
    "BotToken": "8254383681:AAE_j4cUIP9ABVE4Pqrmtgjfmqq1yc4Ow5A"
  },
  "LittleShop": {
    "ApiUrl": "http://localhost:5000",
    "UseTor": false
  },
  "BotManager": {
    "ApiKey": ""  // Leave empty for auto-registration
  }
}
```

**Important:**
- `BotToken`: From BotFather
- `ApiUrl`: LittleShop API endpoint (use container name in Docker)
- `ApiKey`: Leave empty to trigger auto-registration

### Environment Variables (Docker)

**In CI/CD workflow (`.gitea/workflows/build-and-deploy.yml`):**

```bash
docker run -d \
  --name telebot-service \
  -e Telegram__BotToken=${{ secrets.CT109_TELEGRAM_BOT_TOKEN }} \
  -e LittleShop__ApiUrl=http://littleshop:5000 \
  -e LittleShop__UseTor=false \
  telebot:latest
```

**Manual deployment:**

```bash
docker run -d \
  --name telebot-service \
  -e Telegram__BotToken=YOUR_BOT_TOKEN \
  -e LittleShop__ApiUrl=http://littleshop:5000 \
  -e BotManager__ApiKey=YOUR_BOT_KEY \
  telebot:latest
```

## 🗄️ Database Schema

**Table:** `Bots`

```sql
CREATE TABLE "Bots" (
  "Id" TEXT PRIMARY KEY,
  "BotKey" TEXT NOT NULL UNIQUE,
  "Name" TEXT NOT NULL,
  "Description" TEXT NOT NULL,
  "Type" INTEGER NOT NULL,  -- 1=Telegram, 2=Discord, 3=Slack
  "Status" INTEGER NOT NULL,  -- 0=Inactive, 1=Active, 2=Suspended
  "Settings" TEXT NOT NULL,  -- JSON storage
  "CreatedAt" TEXT NOT NULL,
  "LastSeenAt" TEXT NULL,
  "LastConfigSyncAt" TEXT NULL,
  "IsActive" INTEGER NOT NULL,
  "Version" TEXT NOT NULL,
  "IpAddress" TEXT NOT NULL,
  "PlatformUsername" TEXT NOT NULL,
  "PlatformDisplayName" TEXT NOT NULL,
  "PlatformId" TEXT NOT NULL,
  "PersonalityName" TEXT NOT NULL
);
```

## 🧪 Testing Bot Registration

### Test Auto-Registration

```bash
# 1. Delete existing bot from database (optional - for testing fresh registration)
curl -X DELETE http://10.0.0.51:5100/api/bots/BOT_ID

# 2. Restart TeleBot container
docker restart telebot-service

# 3. Watch logs for registration
docker logs -f telebot-service

# Expected: Bot auto-registers and starts successfully
```

### Test Manual Registration

```bash
# 1. Register bot via API
BOT_RESPONSE=$(curl -X POST http://10.0.0.51:5100/api/bots/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TestBot",
    "description": "Test Bot",
    "type": 1,
    "version": "1.0.0",
    "personalityName": "Test",
    "initialSettings": {
      "platformType": "Telegram",
      "platformUsername": "TestBot",
      "platformId": "123456789"
    }
  }')

echo $BOT_RESPONSE

# 2. Extract BotKey
BOT_KEY=$(echo $BOT_RESPONSE | jq -r '.botKey')

# 3. Test authentication
curl -X POST http://10.0.0.51:5100/api/bots/authenticate \
  -H "Content-Type: application/json" \
  -d "{\"botKey\":\"$BOT_KEY\"}"
```

## 🛠️ Troubleshooting

### Bot Won't Start

**Symptom:** TeleBot container exits immediately

**Solutions:**

1. **Check bot token validity:**
   ```bash
   # Test token with Telegram API
   curl https://api.telegram.com/bot8254383681:AAE_j4cUIP9ABVE4Pqrmtgjfmqq1yc4Ow5A/getMe

   # Expected response:
   # {"ok":true,"result":{"id":8254383681,"username":"Teleshopio_bot",...}}
   ```

2. **Check LittleShop connectivity:**
   ```bash
   docker exec telebot-service curl http://littleshop:5000/api/version

   # Should return: {"version":"1.0.0",...}
   ```

3. **Check container logs:**
   ```bash
   docker logs telebot-service --tail 100
   ```

### Bot Registration Fails

**Symptom:** `Failed to register bot with LittleShop API`

**Solutions:**

1. **Verify LittleShop API is accessible:**
   ```bash
   curl http://10.0.0.51:5100/api/bots/register

   # Should return 400 (Bad Request - missing body), not 404
   ```

2. **Check network connectivity:**
   ```bash
   docker network inspect littleshop-network | grep telebot
   docker network inspect littleshop-network | grep littleshop

   # Both should appear in same network
   ```

3. **Test registration manually** (see Manual Bot Registration above)

### Multiple Bot Registrations

**Symptom:** Database has duplicate bot entries

**Solutions:**

1. **List all bots:**
   ```bash
   # Via API
   curl http://10.0.0.51:5100/api/bots

   # Or via database
   docker exec littleshop sqlite3 /app/data/littleshop-dev.db \
     "SELECT Id, Name, PlatformUsername, IsActive, CreatedAt FROM Bots;"
   ```

2. **Delete duplicate bots:**
   ```bash
   # Keep the most recent, delete others
   curl -X DELETE http://10.0.0.51:5100/api/bots/OLD_BOT_ID
   ```

3. **Prevent duplicates:**
   - Ensure `PlatformUsername` is unique
   - Use "Find Existing Bot" before registration

### Bot Doesn't Respond

**Symptom:** Bot online but doesn't respond to messages

**Solutions:**

1. **Check bot is authenticated:**
   ```bash
   docker logs telebot-service | grep authenticated

   # Should show: Bot authenticated successfully
   ```

2. **Verify webhook/polling is active:**
   ```bash
   docker logs telebot-service | grep "polling\|webhook"
   ```

3. **Test bot via Telegram:**
   - Send `/start` command
   - Check logs for incoming update

4. **Check LittleShop product catalog:**
   ```bash
   curl http://10.0.0.51:5100/api/catalog/products

   # If empty, add test products via Admin Panel
   ```

## 📊 Monitoring

### Bot Status

```bash
# Check bot last seen time
curl http://10.0.0.51:5100/api/bots | jq '.[] | {name, lastSeenAt}'

# Check bot activity logs
docker logs telebot-service | grep "activity\|heartbeat"
```

### Active Bots

```bash
# List all active bots
curl http://10.0.0.51:5100/api/bots | jq '.[] | select(.isActive == true)'
```

## 🔐 Security Best Practices

### Bot Token Security

**DO:**
- ✅ Store bot tokens in Gitea secrets
- ✅ Use different tokens for dev/staging/production
- ✅ Regenerate tokens if compromised
- ✅ Keep tokens in environment variables, not config files

**DON'T:**
- ❌ Commit bot tokens to git repository
- ❌ Share bot tokens in plain text
- ❌ Use production tokens in development
- ❌ Hardcode tokens in source code

### BotKey Management

**DO:**
- ✅ Store BotKey securely
- ✅ Regenerate if compromised
- ✅ Use HTTPS for API calls in production

**DON'T:**
- ❌ Log BotKey in plain text
- ❌ Expose BotKey in error messages
- ❌ Share BotKey between environments

## 🔗 Related Documentation

- [DEPLOYMENT.md](./DEPLOYMENT.md) - Deployment procedures
- [SILVERPAY_SETUP.md](./SILVERPAY_SETUP.md) - Payment integration
- [TeleBot/README.md](./TeleBot/README.md) - TeleBot architecture

## 💡 Tips

- **Use @BotFather commands:**
  - `/setdescription` - Set bot description
  - `/setabouttext` - Set about text
  - `/setuserpic` - Set bot profile picture
  - `/setcommands` - Set bot command list

- **Test in private chat first** before deploying to groups

- **Monitor bot activity** to detect issues early

- **Keep bot token secure** - treat it like a password