Discord Bot Integration

Reward your Discord community members with LTZ tokens for participation, engagement, daily check-ins, voice time, streaks, and much more. The official Loyalteez Discord bot is a sophisticated, multi-server solution that integrates seamlessly with the Partner Portal.

Quick Start

Add the bot to your server from Partner Portal → Integrations → Discord
Run /setup brand_id:YOUR_BRAND_ID in your Discord server
Your members can immediately use /join, /daily, /balance, and more!

Features Overview

Feature	Description
Multi-Server	One bot instance serves all Loyalteez brands
Natural Participation	Reward "gm/gn" messages, quality posts, and popular messages
Daily Check-ins	Automated daily rewards with streak bonuses
Voice Rewards	Reward users for time spent in voice channels
Role-Based Multipliers	Configure roles to give bonus LTZ, cooldown reductions, etc.
Streak System	Track consecutive daily activity with milestone bonuses
Leaderboards	Multi-metric rankings (LTZ earned, activity, claims)
Third-Party Integration	Reward level-ups from Mee6, Arcane, Tatsu, Lurkr, and more
Reaction Drops	Create engagement events with reaction-based rewards
Perk Purchases	Users can browse and buy perks directly from Discord
Manual Rewards	Admins can reward valuable contributions on-the-fly
Gateway Relay	Optional Docker service for real-time event processing
Analytics Dashboard	Server stats, KPIs, and engagement metrics
Audit Logging	Complete trail of admin actions and events
User Segments	Auto-categorization of users (whales, at-risk, etc.)
KPI Tracking	Set and monitor performance targets
Internal Achievements	Gamified milestones beyond LTZ
Gaming Integration	Discord presence and Steam achievement rewards
Game Nights	Scheduled gaming events with bonus rewards
Test Mode	Safely test configurations before going live

Getting Started

Step 1: Add the Bot to Your Server

Go to Partner Portal → Integrations → Channels → Discord
Click "Add Loyalteez Bot to Discord"
Select your server and authorize the bot

Step 2: Connect Your Server to Loyalteez

In your Discord server, run:

/setup brand_id:0xYOUR_BRAND_ADDRESS

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.

Step 3: Configure Rewards

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

Event reward amounts
Streak bonuses and grace periods
Voice time rewards
Third-party bot integrations
Role-based multipliers

User Commands

Core Commands

Command	Description
`/join`	Claim one-time welcome bonus for joining
`/daily`	Claim daily check-in reward (resets at midnight UTC)
`/balance`	Check your LTZ token balance
`/help`	View all available commands

Engagement Commands

Command	Description
`/streak`	View your current streak and claim milestone rewards
`/voice`	Check your voice channel time and claim voice rewards
`/activity`	View your activity stats and claim message milestones
`/leaderboard`	View server rankings by various metrics
`/roles`	View available loyalty roles and their benefits

Perk Commands

Command	Description
`/perks`	Browse available perks from your brand
`/perk-buy`	Purchase a perk directly from Discord
`/buy-role`	Purchase a role-linked perk with LTZ

Admin Commands

Setup & Configuration

Command	Description
`/setup`	View setup wizard with permission checks
`/setup brand_id:ADDRESS`	Connect server to your Loyalteez brand
`/setup check`	Run permission audit
`/setup disconnect`	Disconnect server from Loyalteez
`/config`	View and modify bot configuration

Configuration Subcommands

/config                         - View current configuration
/config reward <event> <amount> - Set reward for specific event
/config stacking MODE           - Set role effect stacking (multiplicative/additive/highest)
/config streaks                 - Configure streak settings
/config voice                   - Configure voice time rewards
/config third-party             - Configure third-party bot integrations
/config events                  - View/configure active events
/config sync-roles              - Import Discord roles

Diagnostic Commands

Run diagnostics to verify your bot setup:

Command	Description
`/test all`	Full diagnostic suite
`/test connectivity`	Test service connections
`/test permissions`	Check bot permissions
`/test config`	Validate configuration
`/test reward event:EVENT`	Dry-run reward pipeline
`/test report`	Generate shareable diagnostic report

Channel Configuration

Control which channels trigger rewards:

/config channels                - View channel configuration
/config channels exclude:#channel       - Exclude channel from rewards
/config channels include-only:#channel  - Whitelist mode (ONLY these)
/config channels boost:#channel multiplier:1.5  - Boost channel rewards
/config channels clear:exclude  - Clear exclusions
/config channels clear:all      - Reset all channel settings

User Management

Manage individual users:

/config user                    - User management overview
/config user disable:@user reason:"Reason"  - Disable rewards for user
/config user enable:@user       - Re-enable user
/config user status:@user       - Check user status
/config user list-disabled      - List all disabled users

Test Mode

Safely test configuration changes:

/config test-mode enable:true   - Enable test mode
/config test-mode role:@Testers - Restrict testing to role
/config test-mode enable:false  - Disable test mode

Test mode behavior:

Only testers/admins receive rewards
All events logged with [TEST] flag
Does not count toward KPIs

Engagement Tools

Command	Description
`/drop event_id:ID label:TEXT`	Create a claim button for any event
`/reaction-drop`	Create a reaction-based reward event
`/reward user:@USER amount:NUMBER reason:TEXT`	Manually reward a user

Analytics & Reporting

The bot provides comprehensive analytics tools for admins to track engagement, measure KPIs, and export data.

Server Statistics Dashboard

/stats                    # Weekly overview
/stats period:day         # Daily stats
/stats period:month       # Monthly stats
/stats breakdown:events   # Event breakdown
/stats breakdown:users    # User segments

The dashboard shows:

Total active users
LTZ distributed
Event breakdown
Top earners
Growth trends

Audit Logging

Every admin action and significant event is logged:

/audit                    # Recent 25 events
/audit user:@user         # Filter by user
/audit type:config        # Filter by action type
/audit export:true        # Export as CSV

Logged actions include:

Configuration changes
User enable/disable
Reward distributions
Setup changes

Data Export

Export data for external analysis:

/export type:rewards period:month   # Reward history
/export type:audit period:week      # Audit log
/export type:users                  # User database
/export type:config                 # Full config backup

KPI Tracking & Goals

Setting KPIs

Track performance against targets:

/kpi set metric:daily_active_users target:500 period:week
/kpi set metric:streak_retention target:70 period:month
/kpi list                 # View all KPIs
/kpi report               # KPI performance report

Available KPI Metrics

Metric	Description
`daily_active_users`	Users who claimed rewards
`weekly_active_users`	WAU for engagement
`streak_retention`	% maintaining streaks
`new_user_conversion`	% new users who engage
`voice_participation`	% using voice channels
`reward_efficiency`	LTZ per active user
`churn_rate`	% gone inactive

Community Goals

Set server-wide goals for your community:

/goals set name:"Q1 Growth" type:users target:1000 deadline:2024-03-31
/goals progress           # View goal progress
/goals celebrate          # Celebrate completed goals

Scheduled Reports

Automate analytics delivery:

/reports schedule frequency:weekly channel:#admin-stats day:monday
/reports preview          # Preview report format
/reports disable          # Disable scheduled reports

User Segments

The bot automatically categorizes users into actionable segments:

/segments                 # View all segment summaries
/segments view segment:at_risk    # See users in segment

Automatic Segments

Segment	Criteria	Action
🐋 Whales	Top 10% by LTZ	VIP treatment
⚡ Power Users	High daily activity	Potential moderators
🆕 New Users	Joined < 7 days	Onboarding focus
⚠️ At Risk	Inactive 7+ days	Re-engagement needed
💤 Dormant	Inactive 30+ days	Win-back campaigns
🎤 Voice Regulars	5+ voice sessions/week	Voice event targets

Internal Achievements

Create achievements to gamify participation beyond LTZ rewards.

Initialize Default Achievements

/achievements init        # Create default achievement set

Custom Achievements

/achievements create name:"Chatterbox" type:message_count threshold:1000 reward:500

Achievement Types

Type	Trigger
`message_count`	Total messages sent
`voice_hours`	Total voice time
`streak_days`	Maximum streak reached
`events_claimed`	Total events claimed
`gm_count`	GM check-ins
`ltz_earned`	Total LTZ accumulated
`custom`	Admin-triggered

View Achievements

/achievements             # Your achievements
/achievements @user       # User's achievements
/achievements list        # All server achievements
/achievements leaderboard # Top achievers

Gaming Integration

Discord Presence Rewards

Reward users for playing specific games (detected via Discord Rich Presence):

/config gaming presence enable:true
/config gaming presence game:"Valorant" reward:10 min_minutes:30

Steam Integration

Users can link their Steam accounts for achievement-based rewards:

/link steam steam_id:76561198012345678

Configure Steam rewards (requires Steam API key):

/config gaming steam enable:true
/config gaming steam achievement game:730 reward:50

Game Nights

Create special gaming events with bonus rewards:

/game-night create game:"Among Us" duration:2 reward:50
/game-night active        # View active game nights
/game-night end           # End & distribute rewards

Game nights:

Track participants via Discord voice/presence
Distribute bonus LTZ to attendees
Create community event momentum

Role-Based Rewards System

Configure Discord roles to provide loyalty bonuses to your community members.

Effect Types

Effect	Description	Example
Multiplier	Multiply base rewards	1.5x = 50% bonus LTZ
Flat Bonus	Add fixed amount to rewards	+10 LTZ per claim
Cooldown Reduction	Reduce wait times	25% faster daily reset
Event Access	Unlock exclusive events	VIP-only drops
One-Time Bonus	Grant bonus on role assignment	100 LTZ welcome gift

Configuration in Partner Portal

Go to Integrations → Channels → Discord
Select your connected server
Click "Configure Role Rewards"
For each role:
- Select effect type and value
- Set priority (higher = applied first)
- Choose assignment method (manual, balance threshold, purchase)

Stacking Modes

Configure how multiple role effects combine:

Mode	Description
Multiplicative	Effects multiply (1.5x × 1.2x = 1.8x)
Additive	Effects add (+50% + 20% = +70%)
Highest Only	Only the best effect applies

Natural Participation (Gateway)

Natural Participation features enable rewards for organic community behavior without requiring slash commands. Users can earn LTZ simply by participating naturally in your server.

Gateway Required

Natural Participation features require the Gateway Relay service to be running. This is a lightweight Docker container that connects to Discord's real-time Gateway and forwards events to the Loyalteez bot.

Features

Feature	Description	Default Reward
GM Check-in	Reward users for saying "gm" or "good morning"	25 LTZ
GN Check-in	Reward users for saying "gn" or "good night"	15 LTZ
Quality Messages	Reward thoughtful, high-quality messages	10 LTZ
Popular Messages	Reward when messages reach reaction thresholds	25 LTZ
Auto-Welcome	Automatically reward new members on join	Uses join reward
Server Boost	Special reward for Nitro boosters	500 LTZ

GM/GN Check-in Patterns

The bot recognizes these natural patterns (case-insensitive):

Good Morning:

gm, GM
good morning
gm everyone, gm fam, gm frens
morning!
rise and shine

Good Night:

gn, GN
good night
gn everyone, gn fam
nighty night
sweet dreams, sleep well

Quality Message Scoring

Messages are scored based on:

Length (100+ characters)
Word count (20+ words)
Contains code (bonus points)
Contains helpful links (bonus points)
Multi-paragraph (bonus points)

Messages scoring above the threshold receive rewards (max 5 per day by default).

Configuration

Configure Natural Participation in Partner Portal → Integrations → Discord → Natural Participation:

{
  gmCheckin: {
    enabled: true,
    reward: 25,
    cooldownHours: 24,
    responseEnabled: false
  },
  gnCheckin: {
    enabled: true,
    separateCooldown: false,
    reward: 15
  },
  messageQuality: {
    enabled: false,
    minCharacters: 100,
    minWords: 20,
    rewardPerQualityMessage: 10,
    maxDailyRewards: 5
  },
  reactionRewards: {
    enabled: false,
    thresholdForPopular: 10,
    popularMessageReward: 25
  },
  welcomeAutomation: {
    enabled: false,
    autoRewardOnJoin: false
  }
}

Gateway Relay Setup

For detailed setup instructions, see the Gateway Relay README.

Quick start with Docker:

# Clone the repo
git clone https://github.com/Alpha4-Labs/loyalteez-official-discord-bot.git
cd loyalteez-official-discord-bot/gateway-relay

# Configure environment
cp env.example.txt .env
# Edit .env with your DISCORD_TOKEN and GATEWAY_SECRET

# Run with Docker Compose
docker-compose up -d

Streak & Attendance System

Reward consistent engagement with streak bonuses.

How It Works

Users check in daily with /daily
Consecutive days build their streak counter
Streak multipliers increase rewards
Milestone bonuses unlock at 7, 30, 100, 365 days

Default Streak Multipliers

Streak Days	Multiplier
3+ days	1.1x (10% bonus)
7+ days	1.25x (25% bonus)
14+ days	1.5x (50% bonus)
30+ days	2.0x (100% bonus)

Milestone Bonuses

Milestone	Bonus
7 days	50 LTZ
30 days	200 LTZ
100 days	1,000 LTZ
365 days	5,000 LTZ

Grace Period

Configure a grace period (default: 1 day) that allows users to miss a day without losing their streak.

Voice Channel Rewards

Reward users for time spent in voice channels.

Configuration

Setting	Description	Default
Minutes per reward	How often rewards are given	30 min
LTZ per reward	Amount per reward cycle	5 LTZ
Max daily rewards	Daily cap	10 (150 min)

How It Works

Bot tracks time spent in voice channels (not AFK)
Every X minutes, user earns Y LTZ
Users can check progress with /voice
Daily cap prevents abuse

Third-Party Bot Integration

Automatically reward users when they level up or achieve milestones in other popular bots.

Supported Bots

Bot	Events Tracked
Mee6	Level-ups, leaderboard milestones
Arcane	Level-ups, daily streaks
Tatsu	Level-ups, achievements
Carl-bot	Reaction roles, moderation rewards
The Engage	Engagement milestones
Rumble Royale	Battle wins, tournament placements
Lurkr	Level-ups, role rewards

Setup

Go to Partner Portal → Integrations → Discord → Third-Party Integrations
Enable desired integrations
Configure reward amounts per event type
The bot will automatically parse messages from these bots

Example: Mee6 Level-Up Rewards

// When Mee6 posts a level-up message:
// "🎉 @User just reached level 10!"

// Loyalteez bot detects this and rewards:
// Level 10 = 100 LTZ (10 LTZ per level by default)

Reaction Drops

Create engaging events where users react to claim rewards.

Creating a Reaction Drop

/reaction-drop emoji:🎉 duration:60 reward:50 max_claims:100

Parameter	Description
`emoji`	The reaction emoji to use
`duration`	How long the drop is active (seconds)
`reward`	LTZ amount per claim
`max_claims`	Maximum number of users who can claim

How It Works

Admin creates drop → Bot posts an embed
Users react with the specified emoji
First X users to react get the reward
Drop expires after duration or max claims

Manual Rewards (`/reward`)

Allow trusted roles to reward users for valuable contributions.

Usage

/reward user:@Username event_id:helpful_contribution

Configuration

Allowed Roles: Configure which roles can use /reward in Partner Portal
Event Types: Restrict which events can be triggered manually
Cooldowns: Set per-user cooldowns to prevent abuse
Public Recognition: Optionally post a public message when rewards are given

Example Events

Event ID	Description	Suggested Reward
`helpful_answer`	Helping community members	25 LTZ
`bug_report`	Reporting bugs	50 LTZ
`content_creation`	Creating guides/content	100 LTZ
`event_participation`	Attending community events	20 LTZ

Leaderboards

Display rankings across multiple metrics.

Metrics

Metric	Description
`ltz_earned`	Total LTZ earned in this server
`activity_score`	Combined engagement score
`claims_count`	Total successful claims
`streak_current`	Current daily streak
`voice_minutes`	Total voice channel time

Usage

/leaderboard metric:ltz_earned period:weekly

Parameter	Options
`metric`	ltz_earned, activity_score, claims_count, streak_current, voice_minutes
`period`	daily, weekly, monthly, all_time

Partner Portal Configuration

Discord Tab Location

Integrations → Channels → Discord

Available Settings

Event Rewards

Join bonus amount
Daily check-in amount
Message milestone rewards
Voice time rewards
Reaction rewards

Streak Settings

Enable/disable streaks
Grace period (days)
Streak multipliers (3/7/14/30 day thresholds)
Milestone bonuses (7/30/100/365 day amounts)

Voice Settings

Minutes per reward
LTZ per reward
Maximum daily rewards

Third-Party Integrations

Toggle each integration
Configure rewards per level-up
Set detection sensitivity

Role Configuration

Define role effects (multipliers, bonuses, etc.)
Set assignment methods
Configure stacking behavior

User Identification

Loyalteez maps Discord users to blockchain wallets deterministically:

discord_{USER_ID}@loyalteez.app

How It Works

Deterministic: Same Discord user always gets the same wallet
Cross-Server: Rewards from different servers accumulate
Perk Access: Users log into perks.loyalteez.app with Discord to spend LTZ

Wallet Resolution

When a user interacts with the bot:

Bot extracts Discord user ID
Generates deterministic email identifier
Loyalteez API resolves or creates wallet via Privy
Rewards are sent to this wallet

Database Schema

The bot uses Supabase for persistence. Key tables:

Core Tables

`discord_server_configs`

Stores server-to-brand linkages and configuration.

server_id      TEXT PRIMARY KEY
brand_id       TEXT NOT NULL
server_name    TEXT
is_active      BOOLEAN DEFAULT TRUE
config_metadata JSONB  -- Stores event configs, role settings, etc.

`discord_role_configs`

Stores role-based reward configurations.

server_id       TEXT
discord_role_id TEXT
effect_type     TEXT  -- multiplier, flat_bonus, cooldown_reduction, etc.
effect_value    NUMERIC
priority        INTEGER

`discord_user_stats`

Tracks per-user statistics.

server_id       TEXT
discord_user_id TEXT
messages_count  INTEGER
voice_minutes   INTEGER
reactions_count INTEGER
ltz_earned      BIGINT

`discord_user_streaks`

Tracks user streak data.

server_id        TEXT
discord_user_id  TEXT
current_streak   INTEGER
longest_streak   INTEGER
last_checkin     TIMESTAMPTZ

Admin & Analytics Tables

`discord_audit_log`

Comprehensive audit trail for all admin actions.

server_id       TEXT NOT NULL
brand_id        TEXT
actor_type      TEXT  -- 'admin', 'bot', 'system', 'user'
actor_id        TEXT  -- Discord user ID or 'system'
action          TEXT NOT NULL  -- Action type (e.g., 'config_update')
target_user_id  TEXT  -- Affected user, if applicable
details         JSONB -- Structured action details
before_state    JSONB -- State before change
after_state     JSONB -- State after change
is_test         BOOLEAN DEFAULT FALSE
created_at      TIMESTAMPTZ DEFAULT NOW()

`discord_kpi_configs`

KPI target configuration per server.

server_id     TEXT NOT NULL
metric        TEXT NOT NULL  -- e.g., 'daily_active_users'
target        NUMERIC NOT NULL
period        TEXT DEFAULT 'week'  -- 'day', 'week', 'month'
alert_threshold NUMERIC  -- Alert when below this %
is_active     BOOLEAN DEFAULT TRUE

`discord_kpi_snapshots`

Historical KPI data for trend analysis.

server_id     TEXT NOT NULL
metric        TEXT NOT NULL
value         NUMERIC NOT NULL
period_start  DATE NOT NULL
period_end    DATE NOT NULL
created_at    TIMESTAMPTZ DEFAULT NOW()

`discord_goals`

Community goals configuration.

server_id     TEXT NOT NULL
name          TEXT NOT NULL
type          TEXT NOT NULL  -- 'users', 'ltz', 'events', etc.
target        NUMERIC NOT NULL
current       NUMERIC DEFAULT 0
deadline      DATE
is_completed  BOOLEAN DEFAULT FALSE
celebrated    BOOLEAN DEFAULT FALSE

`discord_scheduled_reports`

Automated report scheduling.

server_id     TEXT NOT NULL PRIMARY KEY
channel_id    TEXT NOT NULL
frequency     TEXT DEFAULT 'weekly'  -- 'daily', 'weekly', 'monthly'
day_of_week   INTEGER  -- 0-6 for weekly reports
is_active     BOOLEAN DEFAULT TRUE
last_sent     TIMESTAMPTZ

Gaming Tables

`discord_gaming_configs`

Gaming integration settings.

server_id     TEXT NOT NULL PRIMARY KEY
presence_enabled BOOLEAN DEFAULT FALSE
steam_enabled BOOLEAN DEFAULT FALSE
game_configs  JSONB  -- Per-game settings

`discord_steam_links`

User Steam account links.

server_id       TEXT NOT NULL
discord_user_id TEXT NOT NULL
steam_id        TEXT NOT NULL
verified        BOOLEAN DEFAULT FALSE
linked_at       TIMESTAMPTZ DEFAULT NOW()

Achievement Tables

`discord_achievements`

Server achievement definitions.

server_id     TEXT NOT NULL
name          TEXT NOT NULL
description   TEXT
type          TEXT NOT NULL  -- 'message_count', 'voice_hours', etc.
threshold     INTEGER NOT NULL
reward        INTEGER DEFAULT 0  -- LTZ reward
icon          TEXT  -- Emoji
is_active     BOOLEAN DEFAULT TRUE

`discord_user_achievements`

User achievement progress.

server_id       TEXT NOT NULL
discord_user_id TEXT NOT NULL
achievement_id  UUID NOT NULL
progress        INTEGER DEFAULT 0
unlocked        BOOLEAN DEFAULT FALSE
unlocked_at     TIMESTAMPTZ

API Endpoints

The Discord bot exposes several endpoints for advanced integrations:

Webhook Endpoints

Endpoint	Method	Description
`/webhook/perk-claim`	POST	Process perk claims and assign Discord roles
`/webhook/message`	POST	Process forwarded bot messages

API Endpoints

Endpoint	Method	Description
`/api/sync-roles`	POST	Trigger role synchronization from Partner Portal
`/health`	GET	Health check endpoint

Best Practices

New Server Checklist

✅ Run /setup check to verify permissions
✅ Configure welcome bonus (/config reward discord_join 100)
✅ Enable daily rewards (/config reward daily_checkin 25)
✅ Enable streaks (/config streaks enable:true)
✅ Set up milestones and multipliers
✅ Exclude announcement/rules channels
✅ Initialize achievements (/achievements init)
✅ Set KPI targets (/kpi set metric:daily_active_users target:100)

Preventing Abuse

Use Test Mode: Enable test mode when configuring
Exclude Bot Channels: Remove reward triggers from bot-only channels
Daily Caps: Limit voice/message rewards per day
Role Gates: Require minimum account age or roles
User Management: Disable rewards for problematic accounts
Audit Monitoring: Review /audit regularly for suspicious activity

Maximizing Engagement

Announce Events: Use /drop for special occasions
Streak Incentives: Promote streak system to encourage daily visits
Role Rewards: Create aspirational roles with meaningful bonuses
Third-Party Sync: Reward existing bot engagement
Achievements: Initialize achievements to gamify participation
Game Nights: Schedule regular gaming events with bonus rewards

Analytics Best Practices

Set KPIs Early: Define success metrics before launch
Monitor Segments: Check /segments view segment:at_risk weekly
Schedule Reports: Use /reports schedule for automated insights
Export Data: Monthly exports for backup and analysis
Goal Tracking: Set community goals for motivation

Technical Recommendations

Permission Audit: Run /setup check after Discord changes
Regular Syncs: Use /config sync-roles if roles change
Test First: Enable test mode during configuration
Monitor Logs: Check audit logs for errors

Troubleshooting

Bot Not Responding

Check bot permissions with /setup check
Verify bot role is above managed roles
Check channel permissions specifically
Ensure /setup was completed successfully

Rewards Not Processing

Verify event is enabled (/config events)
Check if user is disabled (/config user status:@user)
Check if test mode is on (/config test-mode)
Check channel exclusions (/config channels)
Review audit log (/audit)
Verify brand has LTZ balance

Role Effects Not Applying

Verify Manage Roles permission
Ensure bot role is higher than target roles
Run /config sync-roles to refresh
Check role config with /roles

Stats Not Updating

Allow time for data aggregation
Check if test mode is filtering data
Verify audit logging is working (/audit)

Third-Party Bots Not Detecting

Verify bot is enabled (/config third-party)
Check channel permissions for bot messages
Ensure correct bot is configured

Server Not Showing in Partner Portal

Ensure /setup brand_id:... was run with correct address
Check Supabase discord_server_configs table
Verify RLS policies allow your brand to read data

Support

GitHub Issues: loyalteez-official-discord-bot
Partner Portal: Built-in support chat
API Docs: Event Handler API
Discord: Loyalteez Community

Sample Loyalty Programs

These sample programs provide structured templates for building your own Discord loyalty strategy. Each program demonstrates different approaches to incentivizing community participation.

Sample Program 1: Developer & Product Community

Philosophy: Reward real participation, not noise. Focus on onboarding, technical discussion, feedback, and habit formation.

Program Goals

Onboard members who understand the product
Encourage thoughtful technical discussion
Turn feedback and bug reports into product improvements
Reinforce habits that keep contributors coming back

Onboarding Events (One-Time)

Event	Reward	Channel	Description
Read #about-us	10 LTZ	`#about-us`	Verified view of about channel
Read #server-rules	10 LTZ	`#server-rules`	Acknowledged rules
First message in #lobby	10 LTZ	`#lobby`	Welcome participation

Implementation:

/config events onboarding_about:10 onboarding_rules:10 onboarding_lobby:10

Technical Contribution (Quality-Gated)

Event	Reward	Frequency	Channel
Thoughtful question or technical answer	5 LTZ	Weekly max	`#tech-talk`

Note: Quality-gated, not message count. Use /reward for admin validation.

Product Feedback

Event	Reward	Validation	Channel
Actionable feedback post	15 LTZ	Per accepted	`#feedback`
Valid bug report (repro steps)	25 LTZ	Per validated	`#report-bugs`

Topics: UX improvements, pricing feedback, missing features, flow issues.

Community Support

Event	Reward	Limit	Channel
Help another member	40 LTZ	Monthly	`#support`, `#live-tickets`

Validation: Confirmed by mod or ticket resolution.

Educational Engagement

Event	Reward	Channel
Watch video from tutorials	10 LTZ	`#edu-videos`, `#tutorials`
Share learning takeaway	10 LTZ	`#edu-videos`

Developer Contributions

Event	Reward	Channel
Code/architecture insight	20 LTZ	`#dev-chat`
Trigger GitHub activity	20 LTZ	`#github-log`

Habit Formation

Event	Reward	Requirement
7-day active streak	15 LTZ	Non-spam participation

Creative Contribution

Event	Reward	Channel	Bonus
Original visual/meme/diagram	10 LTZ	`#images-art`	+10 LTZ if reused by brand

VIP Tier (Unlock Required)

Event	Reward	Limit	Channel
Strategic discussion	20 LTZ	40 LTZ/month	`#vip-chat`

Access: Earn via cumulative actions.

Sample Monthly Budget

Category	Est. Triggers	LTZ/mo	USD Equiv
Onboarding	50 users	1,500	$1.50
Tech contributions	20 posts	100	$0.10
Feedback	10 posts	150	$0.15
Bug reports	5 reports	125	$0.13
Support help	10 helpers	400	$0.40
Education	30 completions	600	$0.60
Dev contributions	15 contributions	600	$0.60
Streaks	25 streaks	375	$0.38
Creative	15 posts	150	$0.15
Total		~4,000	~$4.00

Sample Program 2: Gaming Community

Philosophy: Reward active participation, competitive engagement, and community building. Focus on voice chat, events, and social interaction.

Program Goals

Maximize active voice participation
Reward competitive and cooperative play
Build strong social connections
Create engaging community events

Welcome & Daily

Event	Reward	Frequency
Server join bonus	100 LTZ	One-time
Daily check-in	25 LTZ	Daily
Daily check-in (with 7+ streak)	50 LTZ	Daily

Voice Channel Rewards

Event	Reward	Limit
30 minutes voice time	15 LTZ	10/day (5 hours)
Active game voice (playing together)	25 LTZ	5/day

Implementation:

/config voice minutes_per_reward:30 ltz_per_reward:15 max_daily:10

Level-Up Integration (Mee6/Arcane)

Level Range	Reward per Level
1-10	25 LTZ
11-25	50 LTZ
26-50	100 LTZ
51+	200 LTZ

Implementation:

/config third-party mee6:enabled ltz_per_level:25

Event Participation

Event	Reward	Channel
Tournament registration	50 LTZ	`#tournaments`
Tournament participation	100 LTZ	Per event
Tournament win	500 LTZ	Per win
Game night attendance	75 LTZ	`#game-nights`

Event	Reward	Frequency
LFG post (looking for group)	10 LTZ	3/day
Help new player	50 LTZ	5/week
Stream announcement	25 LTZ	1/day

Content Creation

Event	Reward	Channel
Gameplay clip	25 LTZ	`#clips`
Featured clip (selected by mods)	100 LTZ
Guide/tutorial	200 LTZ	`#guides`

Role-Based Multipliers

Role	Effect	How to Earn
Rookie	Base rewards	Join server
Regular	1.1x multiplier	1,000 LTZ earned
Veteran	1.25x multiplier	5,000 LTZ earned
Elite	1.5x multiplier	15,000 LTZ earned
Legend	2x multiplier	50,000 LTZ earned

Sample Perks

Perk	Cost	Description
Custom role color	500 LTZ	Choose your name color
Voice priority	1,000 LTZ	Priority speaker in events
Private voice channel (1 week)	2,500 LTZ	Temporary private channel
Game code giveaway entry	1,500 LTZ	Enter prize drawings
Exclusive emote access	3,000 LTZ	Use server custom emotes
VIP lounge access	10,000 LTZ	Permanent VIP channel access

Sample Monthly Budget (500 Active Members)

Category	Est. Triggers	LTZ/mo	USD Equiv
Join bonuses	100 new	10,000	$10.00
Daily check-ins	8,000	200,000	$200.00
Voice rewards	5,000	75,000	$75.00
Level-ups	500	25,000	$25.00
Events	200	15,000	$15.00
Content	100	5,000	$5.00
Total		~330,000	~$330

Sample Program 3: E-commerce Brand Community

Philosophy: Convert Discord engagement into purchase behavior. Reward brand advocacy, product knowledge, and cross-platform engagement.

Program Goals

Drive product discovery and education
Reward brand ambassadors
Create exclusive deals for community
Build repeat purchase habits

Welcome Flow

Event	Reward	Requirement
Server join	50 LTZ	`/join` command
Link account (email verification)	100 LTZ	Connect Discord to store account
Complete profile	25 LTZ	Add avatar, bio

Daily Engagement

Event	Reward	Notes
Daily visit	10 LTZ	Streak bonuses apply
Product question answered	25 LTZ	Help in `#product-help`
Style/review share	50 LTZ	`#customer-photos`

Product Knowledge

Event	Reward	Channel
Watch product video	15 LTZ	`#product-demos`
Complete product quiz	50 LTZ	Monthly quiz events
Attend launch event	100 LTZ	Product launches

Brand Advocacy

Event	Reward	Validation
UGC photo with product	75 LTZ	Mod approved
Product review (on-site)	100 LTZ	Verified purchase
Social media share	50 LTZ	Screenshot proof
Referral (friend joins)	150 LTZ	Friend completes onboarding

Feedback & Support

Event	Reward	Channel
Product feedback	50 LTZ	`#feedback`
Feature request	75 LTZ	`#suggestions`
Issue report	100 LTZ	`#support`

Flash Sales & Exclusives

Event	Reward	Access
Flash sale participation	25 LTZ	`#flash-sales`
Early access purchase	200 LTZ	Members only

Role-Based Perks

Role	Requirement	Benefits
Member	Join	Base access
Fan	500 LTZ	5% discount code
Advocate	2,500 LTZ	10% discount + early access
Ambassador	10,000 LTZ	15% discount + free shipping
VIP	25,000 LTZ	20% discount + exclusive products

Perks Catalog

Perk	Cost	Value
$5 store credit	5,000 LTZ	$5
Free shipping code	2,500 LTZ	~$8 value
Exclusive product access	7,500 LTZ	Limited items
Mystery box entry	3,000 LTZ	Giveaway entry
1-on-1 styling session	15,000 LTZ	Personal consultation
Brand ambassador kit	50,000 LTZ	Products + swag

Sample Monthly Budget (1,000 Members)

Category	Est. Triggers	LTZ/mo	USD Equiv
Welcome flow	50 new	8,750	$8.75
Daily engagement	15,000	150,000	$150.00
Product knowledge	200	7,000	$7.00
Brand advocacy	100	8,750	$8.75
Flash sales	500	12,500	$12.50
Total		~187,000	~$187

Implementing Your Program

Choose your template - Select the sample program closest to your community type
Customize rewards - Adjust LTZ amounts based on your budget and goals
Configure in Partner Portal - Set up events in Automation and channels in Integrations → Discord
Test with small group - Run a pilot with trusted members
Launch and iterate - Monitor engagement and adjust

Program Design Tips

Balance Quality vs. Quantity

Quality-gated rewards (mod approved) = higher LTZ, prevents spam
Automatic rewards (streaks, voice time) = lower LTZ, drives daily engagement
Mix both for a healthy program

Set Appropriate Caps

Daily caps prevent farming
Weekly caps encourage consistent participation
Monthly caps reward depth over volume

Create Clear Progression

Quick wins (< 500 LTZ) = First-day achievable
Medium goals (1,000-5,000 LTZ) = Weekly targets
Long-term rewards (10,000+ LTZ) = Monthly aspirations

Features Overview​

Getting Started​

Step 1: Add the Bot to Your Server​

Step 2: Connect Your Server to Loyalteez​

Step 3: Configure Rewards​

User Commands​

Core Commands​

Engagement Commands​

Perk Commands​

Admin Commands​

Setup & Configuration​

Configuration Subcommands​

Diagnostic Commands​

Channel Configuration​

User Management​

Test Mode​

Engagement Tools​

Analytics & Reporting​

Server Statistics Dashboard​

Audit Logging​

Data Export​

KPI Tracking & Goals​

Setting KPIs​

Available KPI Metrics​

Community Goals​

Scheduled Reports​

User Segments​

Automatic Segments​

Internal Achievements​

Initialize Default Achievements​

Custom Achievements​

Achievement Types​

View Achievements​

Gaming Integration​

Discord Presence Rewards​

Steam Integration​

Game Nights​

Role-Based Rewards System​

Effect Types​

Configuration in Partner Portal​

Stacking Modes​

Natural Participation (Gateway)​

Features​

GM/GN Check-in Patterns​

Quality Message Scoring​

Configuration​

Gateway Relay Setup​

Streak & Attendance System​

How It Works​

Default Streak Multipliers​

Milestone Bonuses​

Grace Period​

Voice Channel Rewards​

Configuration​

How It Works​

Third-Party Bot Integration​

Supported Bots​

Setup​

Example: Mee6 Level-Up Rewards​

Reaction Drops​

Creating a Reaction Drop​

How It Works​

Manual Rewards (/reward)​

Usage​

Configuration​

Example Events​

Leaderboards​

Metrics​

Usage​

Partner Portal Configuration​

Discord Tab Location​

Available Settings​

Event Rewards​

Streak Settings​

Voice Settings​

Third-Party Integrations​

Role Configuration​

User Identification​

How It Works​

Wallet Resolution​

Features Overview

Getting Started

Step 1: Add the Bot to Your Server

Step 2: Connect Your Server to Loyalteez

Step 3: Configure Rewards

User Commands

Core Commands

Engagement Commands

Perk Commands

Admin Commands

Setup & Configuration

Configuration Subcommands

Diagnostic Commands

Channel Configuration

User Management

Test Mode

Engagement Tools

Analytics & Reporting

Server Statistics Dashboard

Audit Logging

Data Export

KPI Tracking & Goals

Setting KPIs

Available KPI Metrics

Community Goals

Scheduled Reports

User Segments

Automatic Segments

Internal Achievements

Initialize Default Achievements

Custom Achievements

Achievement Types

View Achievements

Gaming Integration

Discord Presence Rewards

Steam Integration

Game Nights

Role-Based Rewards System

Effect Types

Configuration in Partner Portal

Stacking Modes

Natural Participation (Gateway)

Features

GM/GN Check-in Patterns

Quality Message Scoring

Configuration

Gateway Relay Setup

Streak & Attendance System

How It Works

Default Streak Multipliers

Milestone Bonuses

Grace Period

Voice Channel Rewards

Configuration

How It Works

Third-Party Bot Integration

Supported Bots

Setup

Example: Mee6 Level-Up Rewards

Reaction Drops

Creating a Reaction Drop

How It Works

Manual Rewards (`/reward`)

Usage

Configuration

Example Events

Leaderboards

Metrics

Usage

Partner Portal Configuration

Discord Tab Location

Available Settings

Event Rewards

Streak Settings

Voice Settings

Third-Party Integrations

Role Configuration

User Identification

How It Works

Wallet Resolution