Telegram Bot Integration

Coming Soon

The Telegram bot is in final testing. This documentation is available for preview, but the bot is not yet publicly available.

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

Quick Start

1. Add the bot to your group as admin
2. DM the bot with /setup to start the secure setup flow
3. Enter your Brand ID and Security Key in the private chat
4. Use the activation token in your group with /activate <token>
5. Your members can immediately use /daily, /balance, /streak, and more!

Features Overview

Feature	Description
Multi-Group	One bot instance serves all Loyalteez brands
Secure DM Setup	Security keys exchanged via private DM, not public chat
Natural Participation	Reward "gm/gn" messages with automatic detection
Daily Check-ins	Automated daily rewards with streak bonuses
Streak System	Track consecutive daily activity with milestone bonuses
Leaderboards	Multi-metric rankings (LTZ earned, activity, claims)
Perk Purchases	Users can browse and buy perks directly from Telegram
Manual Rewards	Admins can reward valuable contributions on-the-fly
Achievements	Gamified milestones beyond LTZ
Admin Configuration	Full /config command for event management
Rate Limiting	Intelligent behavior-based abuse prevention
Input Validation	Secure handling of all user inputs

---

Telegram vs Discord Feature Comparison

Telegram has core parity with Discord for all features that apply to the platform.

Feature	Discord	Telegram	Notes
Daily check-ins	✅	✅	Same functionality
Streak system	✅	✅	Same multipliers and milestones
GM/GN detection	✅	✅	Same patterns recognized
Quality message rewards	✅	✅	Same scoring
Leaderboards	✅	✅	Same metrics
Perks & redemption	✅	✅	Same perks catalog
Achievements	✅	✅	Same achievement types
Admin /config	✅	✅	Same event management
Manual rewards	✅	✅	Same functionality
Secure setup flow	✅	✅	DM-based for Telegram, private channel for Discord
Rate limiting	✅	✅	Behavior-based abuse prevention
Input validation	✅	✅	Secure input handling
HMAC authentication	✅	✅	Same security mechanism
Role-based bonuses	✅	❌	Telegram lacks roles
Voice activity tracking	✅	❌	Different architecture
Third-party bot integration	✅	❌	Discord ecosystem
Reaction drops	✅	❌	Discord components
Boost event rewards	✅	❌	Discord-specific

---

Architecture

The Telegram bot uses the same backend infrastructure as Discord:

Telegram Bot (Cloudflare Worker)
    ↓
Loyalteez APIs
    ├── Event Handler (api.loyalteez.app)
    ├── Shared Services (services.loyalteez.app)
    │   ├── Community Service (registration, config)
    │   ├── Streak Service
    │   ├── Leaderboard Service
    │   ├── Achievement Service
    │   └── Perks Service
    └── Pregeneration (register.loyalteez.app)

Shared Services Integration:

• Community registration and configuration managed centrally
• Security keys encrypted and stored securely (AES-256-GCM)
• Streak tracking synchronized with Discord
• Leaderboards work cross-platform
• Achievement progress is unified
• Perks catalog is shared

---

User Identification

Telegram users are identified using the pattern:

telegram_{USER_ID}@loyalteez.app

This creates a deterministic wallet for each Telegram user, just like Discord.

---

Next Steps

• Setup Guide - Get the bot running in your group
• Admin Guides - Configure your program
• Commands Reference - All available commands