Skip to main content

Telegram Bot Integration

Reward your Telegram community members with LTZ tokens for participation, engagement, daily check-ins, streaks, and much more.

White-Label Template

The Telegram bot repository (loyalteez-official-telegram-bot) is a white-label reference implementation - a template designed for developers to clone, customize, and deploy for their own brands. It's a sophisticated, multi-tenant solution that integrates with the Loyalteez Partner Portal.

This is a template/starter kit, not Loyalteez's production deployment. Clone it, modify it, brand it, and deploy it as your own.

Quick Start
  1. Add the bot to your group from Partner Portal → Integrations → Telegram
  2. Run /setup <brand_id> <security_key> in your Telegram group
  3. Your members can immediately use /daily, /balance, /streak, and more!

Features Overview​

FeatureDescription
Multi-GroupOne bot instance serves all Loyalteez brands
Natural ParticipationReward "gm/gn" messages with automatic detection
Daily Check-insAutomated daily rewards with streak bonuses
Streak SystemTrack consecutive daily activity with milestone bonuses
LeaderboardsMulti-metric rankings (LTZ earned, activity, claims)
Perk PurchasesUsers can browse and buy perks directly from Telegram
Manual RewardsAdmins can reward valuable contributions on-the-fly
AchievementsGamified milestones beyond LTZ
Shared ServicesIntegration with centralized streak, leaderboard, achievement, and perks services

Getting Started​

Step 1: Deploy the Bot​

The official Telegram bot is deployed as a Cloudflare Worker. If you're using the official bot, skip to Step 2. If deploying your own instance:

Prerequisites:

  • Cloudflare account with Workers access
  • Telegram Bot Token (from BotFather)
  • Supabase credentials
  • Wrangler CLI installed

Deployment:

# Clone the repository
git clone https://github.com/Alpha4-Labs/loyalteez-official-telegram-bot.git
cd loyalteez-official-telegram-bot

# Install dependencies
npm install

# Configure secrets
wrangler secret put TELEGRAM_BOT_TOKEN
wrangler secret put SUPABASE_PUBLISH_KEY
wrangler secret put SUPABASE_SECRET_KEY

# Create KV namespace
wrangler kv:namespace create "TELEGRAM_KV"
# Update wrangler.toml with the namespace ID

# Deploy
npm run deploy

Set Webhook:

curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-worker.workers.dev"

Step 2: Add Bot to Your Group​

  1. Create Bot Token (if deploying your own):

    • Open Telegram and search for @BotFather
    • Send /newbot
    • Choose a name and username
    • Copy the token

  2. Add Bot to Group:

    • Open your Telegram group
    • Click group name → Add Members
    • Search for your bot username
    • Add as administrator (required for commands)

Step 3: Connect Your Group to Loyalteez​

In your Telegram group, run:

/setup 0xYOUR_BRAND_ADDRESS YOUR_SECURITY_KEY
Where to find your Brand ID

Your Brand ID is your wallet address shown in Partner Portal → Settings → Account (/settings/account). It starts with 0x and is 42 characters long.

Default Configuration

When you run /setup, the bot automatically creates a default configuration with:

  • Daily check-in: 10 LTZ
  • Welcome bonus: 50 LTZ
  • Natural participation (GM/GN): Enabled with 25/15 LTZ rewards
  • 24-hour cooldown for GM/GN

These settings can be customized via /config or the Partner Portal.

Step 4: Configure Rewards​

After setup, visit the Telegram tab in Partner Portal to configure:

  • Event reward amounts
  • Streak bonuses and grace periods
  • Natural participation rewards
  • Perk settings

User Commands​

Core Commands​

CommandDescription
/daily or /checkinClaim daily check-in reward (resets at midnight UTC)
/balance or /ltzCheck your LTZ token balance
/streakView your current streak and claim milestone rewards
/helpView all available commands

Engagement Commands​

CommandDescription
/leaderboard or /lbView group rankings by various metrics
/perks or /rewardsBrowse available perks from your brand
/claim or /buyPurchase a perk directly from Telegram
/activityView your activity stats
/achievementsView your achievement progress

Admin Commands​

Setup & Configuration​

CommandDescription
/setup <brand_id> <security_key>Connect group to your Loyalteez brand (admin-only, requires Security Key)
/configView and modify bot configuration (admin-only)
/reward <@username or user_id> <amount>Manually reward a user (admin-only)

Setup Example:

/setup 0x1234567890abcdef1234567890abcdef12345678 YOUR_SECURITY_KEY_HERE

Reward Example:

/reward @username 100

or

/reward 987654321 100

Command Reference​

/daily or /checkin​

Daily check-in to maintain your streak and earn rewards.

Usage:

/daily

What it does:

  • Records your daily activity
  • Applies streak multiplier to rewards
  • Shows current streak status
  • Displays next milestone progress

Example Response:

✅ Daily check-in complete!

💰 Earned: 20 LTZ
🔥 Streak: 5 days (2.0x multiplier)

🎁 Unclaimed milestones available! Use /streak to claim.

/balance or /ltz​

View your on-chain LTZ token balance.

Usage:

/balance

What it does:

  • Queries your wallet balance from the blockchain
  • Shows balance in LTZ tokens
  • Displays wallet address

Example Response:

💰 Your Balance

25,430 LTZ

Wallet: 0x...

/streak​

View your streak status and claim milestone bonuses.

Usage:

/streak

What it does:

  • Shows current streak count
  • Displays longest streak
  • Shows current multiplier
  • Lists unclaimed milestones
  • Provides buttons to claim milestone bonuses

Example Response:

🔥 Streak Status

Current: 7 days
Longest: 7 days
Multiplier: 1.5x

🎁 Unclaimed Milestones:
   • 7 days: +100 LTZ
   • 30 days: +500 LTZ

Click below to claim!

Interactive Buttons:

  • [🎁 Claim 7-day bonus (+100 LTZ)]
  • [🎁 Claim 30-day bonus (+500 LTZ)]

/leaderboard or /lb​

View group rankings by various metrics.

Usage:

/leaderboard

What it does:

  • Shows top earners by selected metric
  • Provides interactive keyboard for filtering
  • Supports multiple metrics: LTZ earned, streaks, activity, claims
  • Supports multiple periods: This week, this month, all time

Metrics:

  • 💰 LTZ Earned
  • 🔥 Streaks
  • 📊 Activity
  • 🎯 Claims

Periods:

  • 📅 This Week
  • 📆 This Month
  • 🌟 All Time

Example Response:

🏆 Leaderboard - LTZ Earned (This Week)

1. @user1 - 5,240 LTZ
2. @user2 - 3,890 LTZ
3. @user3 - 2,150 LTZ
...

Interactive Buttons:

[💰 LTZ Earned] [🔥 Streaks]
[📊 Activity]   [🎯 Claims]
[📅 This Week]  [📆 This Month] [🌟 All Time]

/perks or /rewards​

Browse available perks from your brand.

Usage:

/perks

What it does:

  • Lists all available perks
  • Shows cost and availability
  • Provides inline buttons for quick redemption
  • Displays perk categories

Example Response:

🛍️ Available Perks

💰 Discount Code
   Cost: 500 LTZ
   Category: Discount
   
🎁 T-Shirt
   Cost: 2,000 LTZ
   Category: Merchandise

Interactive Buttons:

[🛒 Buy: Discount Code (500 LTZ)]
[🛒 Buy: T-Shirt (2000 LTZ)]

/claim or /buy​

Purchase a perk using LTZ tokens.

Usage:

/claim

or click a perk button from /perks

What it does:

  • Redeems perk using LTZ balance
  • Requires sufficient balance
  • Processes transaction on-chain
  • Confirms purchase

Example Response:

✅ Perk Purchased!

🎁 Discount Code
💰 Cost: 500 LTZ

Transaction: 0x...

/activity​

View your activity statistics.

Usage:

/activity

What it does:

  • Shows personal statistics
  • Displays LTZ earned, claims, streak, etc.
  • Provides activity overview

Example Response:

📊 Your Activity

💰 Total Earned: 5,240 LTZ
🎯 Perks Claimed: 3
🔥 Current Streak: 7 days
📈 Total Activity: 127 events

/achievements​

View your achievement progress.

Usage:

/achievements

What it does:

  • Lists unlocked achievements
  • Shows in-progress achievements with progress bars
  • Displays achievement rewards

Example Response:

🏆 Your Achievements

✅ Unlocked (3)
🏆 First Daily Check-in (+50 LTZ)
🏆 7-Day Streak (+100 LTZ)
🏆 First Perk (+25 LTZ)

📈 In Progress (2)
🎯 30-Day Streak
   [████░░░░░░] 15/30 (50%)
🎯 10 Perks Claimed
   [███░░░░░░░] 3/10 (30%)

/setup <brand_id> <security_key>​

Connect your Telegram group to a Loyalteez brand.

Requirements:

  • Admin permissions in the group
  • Valid Brand ID from Partner Portal
  • Security Key from Partner Portal → Settings → Account

Usage:

/setup 0x1234567890abcdef1234567890abcdef12345678 YOUR_SECURITY_KEY_HERE

What it does:

  • Stores group configuration in database
  • Links group to your brand
  • Enables all bot features
  • Sets up default configuration

Example Response:

✅ Group connected to Loyalteez!

Brand ID: 0x1234567890abcdef1234567890abcdef12345678

Use /config to customize settings.

/config​

View and modify bot configuration.

Requirements:

  • Admin permissions in the group
  • Group must be set up (run /setup first)

Usage:

/config

What it does:

  • Displays current configuration
  • Shows settings: daily reward, welcome bonus, natural participation, etc.
  • Allows customization (via Partner Portal for advanced settings)

Example Response:

⚙️ Current Configuration

Brand ID: 0x1234567890abcdef1234567890abcdef12345678
Daily Reward: 10 LTZ
Welcome Bonus: 50 LTZ
Natural Participation: ✅ Enabled

Use /config <setting> <value> to change settings.

/reward <target> <amount>​

Manually reward a user.

Requirements:

  • Admin permissions in the group
  • Group must be set up

Usage:

/reward @username 100

or

/reward 987654321 100

What it does:

  • Sends LTZ reward to specified user
  • Processes on-chain transaction
  • Confirms reward distribution

Example Response:

✅ Rewarded 100 LTZ to @username

Transaction: 0x...

Natural Participation (GM/GN Detection)​

The bot automatically detects and rewards natural engagement patterns like "gm" (good morning) and "gn" (good night) messages.

How It Works​

GM (Good Morning) Patterns:

  • Detects messages like: gm, good morning, morning all, gm everyone, etc.
  • Configurable cooldown (default: 24 hours)
  • Automatic streak tracking
  • Optional response messages

GN (Good Night) Patterns:

  • Detects messages like: gn, good night, night all, gn everyone, etc.
  • Similar configuration to GM

Detection Patterns:

  • Case-insensitive matching
  • Supports various formats: gm, good morning, morning all, etc.
  • Works with messages containing GM/GN anywhere in text

Example:

User: "gm everyone!"
Bot: (silently rewards user, optionally responds)

Configuration​

Natural participation can be configured in the group settings:

  • Enable/Disable: Toggle natural participation on/off
  • GM Reward: Amount of LTZ for GM messages (default: 25)
  • GN Reward: Amount of LTZ for GN messages (default: 15)
  • Cooldown: Hours between rewards (default: 24)
  • Response: Whether bot should respond to GM/GN messages

Default Configuration:

{
  "naturalParticipation": {
    "enabled": true,
    "gmReward": 25,
    "gnReward": 15,
    "gmCooldownHours": 24,
    "gnCooldownHours": 24,
    "gmResponseEnabled": false,
    "gnResponseEnabled": false
  }
}

Shared Services Integration​

The Telegram bot uses Loyalteez Shared Services for consistent behavior across platforms:

Streak Service​

Endpoint: GET /streak/status/:brandId/:userIdentifier

Used by:

  • /daily command
  • /streak command
  • Natural participation (GM/GN)

Features:

  • Cross-platform streak tracking
  • Milestone bonuses
  • Multiplier calculation

See Streak Service Documentation for details.

Leaderboard Service​

Endpoint: GET /leaderboard/:brandId

Used by:

  • /leaderboard command

Features:

  • Multi-metric rankings
  • Cross-platform leaderboards
  • Time-period filtering

See Leaderboard Service Documentation for details.

Achievement Service​

Endpoint: GET /achievements/:brandId/:userIdentifier

Used by:

  • /achievements command

Features:

  • Achievement progress tracking
  • Cross-platform achievements
  • Progress visualization

See Achievement Service Documentation for details.

Perks Service​

Endpoints:

  • GET /perks/:brandId
  • POST /perks/redeem

Used by:

  • /perks command
  • /claim command

Features:

  • Perk browsing
  • Perk redemption
  • Inventory management

See Perks Service Documentation for details.

User Identification​

Telegram users are identified using a platform-agnostic format:

telegram_{user_id}@loyalteez.app

Example:

This enables:

  • Cross-platform reward accumulation: Users can earn LTZ on multiple platforms
  • Unified leaderboards: Same user across platforms appears in combined rankings
  • Platform-agnostic streak tracking: Streaks persist across platforms

Database Schema​

The bot requires a telegram_group_configs table in Supabase:

CREATE TABLE telegram_group_configs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    telegram_group_id TEXT NOT NULL UNIQUE,
    brand_id TEXT NOT NULL,
    group_name TEXT,
    is_active BOOLEAN DEFAULT TRUE,
    config_metadata JSONB DEFAULT '{}'::jsonb,
    setup_by TEXT,
    setup_at TIMESTAMPTZ DEFAULT NOW(),
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE INDEX idx_telegram_group_configs_brand_id ON telegram_group_configs(brand_id);
CREATE INDEX idx_telegram_group_configs_telegram_group_id ON telegram_group_configs(telegram_group_id);

Config Metadata Structure:

{
  "naturalParticipation": {
    "enabled": true,
    "gmReward": 25,
    "gnReward": 15,
    "gmCooldownHours": 24,
    "gnCooldownHours": 24,
    "gmResponseEnabled": false,
    "gnResponseEnabled": false
  },
  "dailyReward": 10,
  "welcomeBonus": 50,
  "welcomeMessageEnabled": true
}

Architecture​

Cloudflare Worker Deployment​

The bot runs as a Cloudflare Worker, providing:

  • Serverless: No server management required
  • Global edge network: Low latency worldwide
  • Automatic scaling: Handles traffic spikes automatically
  • Cost-effective: Pay per request

Components​

1. Main Handler (src/index.js)

  • HTTP request handler
  • Webhook endpoint
  • CORS support
  • Health check endpoint

2. Command Handlers (src/commands/)

  • Individual command implementations
  • User and admin commands
  • Error handling
  • Response formatting

3. Services (src/services/)

  • Group configuration management
  • Natural participation detection
  • Shared services clients
  • Database interactions

4. Handlers (src/handlers/)

  • Message routing
  • Callback query handling
  • New member processing

Telegram vs Discord Parity​

The Telegram bot provides feature parity with the Discord bot:

FeatureDiscordTelegramNotes
Daily Check-in✅ /daily✅ /dailySame functionality
Balance Query✅ /balance✅ /balanceSame functionality
Streak System✅ /streak✅ /streakSame milestones
Leaderboard✅ /leaderboard✅ /leaderboardSame metrics
Perks Browsing✅ /perks✅ /perksSame perks
Perk Redemption✅ /perk-buy✅ /claimSame flow
Natural Participation✅ GM/GN✅ GM/GNSame patterns
Admin Setup✅ /setup connect✅ /setupSame purpose
Admin Config✅ /config events✅ /configSimplified UI
Manual Rewards✅ /reward @user✅ /rewardReply-to-target

Troubleshooting​

Bot Not Responding​

Check:

  1. Is the bot added to the group as admin?
  2. Is the webhook URL configured correctly?
  3. Are there any errors in Cloudflare Worker logs?

Fix:

# Check webhook status
curl "https://api.telegram.org/bot<TOKEN>/getWebhookInfo"

# Set webhook
curl -X POST "https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://your-worker.workers.dev"

Commands Not Working​

Check:

  1. Has /setup been run in the group?
  2. Is the bot an admin in the group?
  3. Is the Brand ID correct?

Fix:

  • Run /setup <brand_id> <security_key> again
  • Ensure bot has admin permissions
  • Verify Brand ID and Security Key in Partner Portal → Settings → Account

Natural Participation Not Working​

Check:

  1. Is natural participation enabled in config?
  2. Is the user on cooldown?
  3. Are GM/GN patterns being detected?

Fix:

  • Check group configuration via /config
  • Verify cooldown settings
  • Test with simple messages like "gm" or "gn"

Balance Not Showing​

Check:

  1. Has the user earned any LTZ?
  2. Is the wallet created?
  3. Is the API responding?

Fix:

  • User needs to earn LTZ first (via /daily, GM/GN, etc.)
  • Wallet is created automatically on first reward
  • Check API status

Support​

Your Telegram community now earns real rewards! 🎉

Last updated on