Skip to main content

Telegram Bot Setup

Get the Loyalteez Telegram bot running in your group.

Step 1: Add Bot to Your Group​

  1. Open your Telegram group
  2. Click group name → Add Members
  3. Search for the bot username (e.g., @LoyalteezBot)
  4. Add as administrator (required for commands)
Admin Permission Required

The bot needs admin permission to:

  • Read messages for GM/GN detection
  • Respond to commands
  • Track activity

Step 2: Get Your Security Key​

  1. Go to Partner Portal → Settings → Security
  2. Click the copy icon next to your Security Key
  3. Copy the entire key (it's a long hex string)
Security Key Required

You must provide your Security Key when connecting your group. This authenticates your group and enables secure communication with the Loyalteez API.

Step 3: Start Secure Setup (DM Flow)​

Why DM-Based Setup?

Unlike Discord where admins can use private channels, Telegram groups don't have private admin-only spaces. To protect your Security Key from being exposed in public chat, the setup process uses a secure DM flow.

3a. Start a DM with the Bot​

  1. Find the bot in your group members list
  2. Click the bot's name → "Send Message"
  3. In the private chat, send:
/setup

3b. Provide Your Brand ID​

The bot will ask for your Brand ID. Send:

0xYOUR_BRAND_ADDRESS
Where to find your Brand ID

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

3c. Provide Your Security Key​

The bot will then ask for your Security Key. Send:

YOUR_SECURITY_KEY_HERE
Security Key Format

Your Security Key is a long hexadecimal string. Make sure you copy the entire key from Partner Portal → Settings → Security. If you don't have one, click "Regenerate" to create a new Security Key.

3d. Receive Activation Token​

After validating your credentials, the bot will respond with:

✅ Registration successful!

Your activation token: abc123xyz

Go to your Telegram group and use:
/activate abc123xyz

The token expires in 1 hour.

Copy this token - you'll need it for the next step.

Step 4: Activate in Your Group​

Return to your Telegram group and send:

/activate abc123xyz

(Replace abc123xyz with your actual token)

You should see:

✅ Community activated!

Your group is now connected to [Brand Name].
Members can start earning LTZ immediately!

Try /daily to get started.

Default Configuration​

When activation completes, the bot automatically creates default events:

  • telegram_daily_checkin: 10 LTZ, 24h cooldown
  • gm_checkin: 25 LTZ, 24h cooldown
  • gn_checkin: 15 LTZ, 24h cooldown
  • telegram_join: 50 LTZ, one-time
  • message_quality: 10 LTZ (disabled by default)
  • telegram_admin_reward: For manual rewards

These events are stored in monitoring_rules and can be fully customized via /config events or the Partner Portal.

Step 5: Verify Setup​

Test the daily check-in:

/daily

You should see:

✅ Daily check-in complete!

💰 Earned: 10 LTZ
🔥 Streak: 1 day

Step 6: Configure Events (Optional)​

View All Events​

/config events

Change Reward Amount​

/config reward telegram_daily_checkin 25

Configure Daily Event​

/config daily-event telegram_daily_checkin

Available Commands​

User Commands​

CommandDescription
/dailyDaily check-in for LTZ
/balanceCheck your LTZ balance
/streakView your current streak
/joinClaim welcome bonus (if not auto-claimed)
/helpShow available commands

Admin Commands​

CommandDescription
/setupStart secure setup flow (DM only)
/activate <token>Activate community in group
/configView/modify community settings
/statsView community analytics
/testRun diagnostic checks
/reward <user> <amount>Manually reward a user
/disconnectDeactivate community

Disconnecting a Community​

If you need to disconnect your group from Loyalteez:

/disconnect

The bot will ask for confirmation:

⚠️ Are you sure you want to disconnect this group?

This will:
- Stop all rewards
- Deactivate the community
- Require re-setup to restore

Type /disconnect confirm to proceed.

Then confirm with:

/disconnect confirm

Self-Hosted Deployment​

If you're deploying your own instance of the Telegram bot:

Prerequisites​

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

Get a Bot Token​

  1. Open Telegram and search for @BotFather
  2. Send /newbot
  3. Choose a name and username
  4. Copy the token

Deploy the Worker​

# 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
wrangler secret put ENCRYPTION_KEY
wrangler secret put TEST_API_KEY  # Optional: for E2E testing

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

Environment Variables​

VariableRequiredDescription
TELEGRAM_BOT_TOKENYesBot token from BotFather
SUPABASE_URLYesSupabase project URL
SUPABASE_PUBLISH_KEYYesSupabase anon key
SUPABASE_SECRET_KEYYesSupabase service role key
ENCRYPTION_KEYYesAES-256 key for security key encryption
SHARED_SERVICES_URLYesURL to Shared Services worker
LOYALTEEZ_API_URLYesURL to Event Handler
TEST_API_KEYNoAPI key for E2E test endpoint

Security Configuration​

Configure rate limiting via environment variables:

# wrangler.toml
[vars]
RATE_LIMIT_ENABLED = "true"
RATE_LIMIT_MODE = "soft"  # monitor | soft | full
RATE_LIMIT_USER_BURST = "30"
RATE_LIMIT_USER_SUSTAINED = "100"
RATE_LIMIT_COMMUNITY_BURST = "1000"
RATE_LIMIT_ADMIN_BURST = "10"
RATE_LIMIT_BAN_DURATION = "300"
MAX_SINGLE_REWARD = "10000"
MAX_DAILY_ADMIN_REWARD = "100000"
MAX_PAYLOAD_SIZE = "51200"

Database Requirements​

The bot requires these Supabase tables:

  1. brand_communities - Cross-platform community configurations
  2. monitoring_rules - Event configurations (shared with Discord)
  3. perk_collections - Perk data (shared with Discord)

See Shared Services - Community Service for schema details.

Troubleshooting Setup​

"Brand not found"​

  • Verify Brand ID is correct (42 characters, starts with 0x)
  • Ensure you have an active Partner Portal subscription

"Security Key Required" or "Security Key Validation Failed"​

  1. Get your Security Key from Partner Portal → Settings → Security
  2. Make sure you copied the entire Security Key (it's a long hex string)
  3. Verify the Security Key matches the Brand ID you're using
  4. If you don't have a Security Key, click "Regenerate" in Partner Portal
  5. Try /setup again in a DM with the bot

"Invalid activation token"​

  • Activation tokens expire after 1 hour
  • Start the setup flow again with /setup in a DM
  • Make sure you're using the token in the correct group

"Not an admin"​

  • Add the bot as a group administrator
  • Check group settings → Administrators

Bot not responding​

  • Verify webhook is set correctly
  • Check Cloudflare Worker logs
  • Ensure bot has admin permission in group

"Rate limited"​

If you're seeing rate limit messages:

  • Wait a few moments before trying again
  • The bot uses behavior-based rate limiting
  • Excessive rapid requests will temporarily restrict access

Next Steps​

Last updated on