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:

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:

# 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:

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:

{
  "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:

curl http://10.0.0.51:5100/api/bots/by-platform/1/Teleshopio_bot

Platform Types:

• 1 = Telegram
• 2 = Discord
• 3 = Slack

Response:

{
  "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:

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

Response:

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

⚙️ Configuration

TeleBot Configuration File

File: TeleBot/TeleBot/appsettings.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):

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:

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

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

# 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

# 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:

   # 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:

   docker exec telebot-service curl http://littleshop:5000/api/version
   
   # Should return: {"version":"1.0.0",...}
   

3. Check container logs:

   docker logs telebot-service --tail 100
   

Bot Registration Fails

Symptom: Failed to register bot with LittleShop API

Solutions:

1. Verify LittleShop API is accessible:

   curl http://10.0.0.51:5100/api/bots/register
   
   # Should return 400 (Bad Request - missing body), not 404
   

2. Check network connectivity:

   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:

   # 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:

   # 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:

   docker logs telebot-service | grep authenticated
   
   # Should show: Bot authenticated successfully
   

2. Verify webhook/polling is active:

   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:

   curl http://10.0.0.51:5100/api/catalog/products
   
   # If empty, add test products via Admin Panel
   

📊 Monitoring

Bot Status

# 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

# 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 procedures
• SILVERPAY_SETUP.md - Payment integration
• 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