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

1. Add the bot to your server from Partner Portal → Integrations → Discord
2. Run /setup brand_id:YOUR_BRAND_ID in your Discord server
3. 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
Custom Boost Events	Configure tier-specific and first-boost rewards from monitoring_rules
Perk Purchases	Users can browse and buy perks directly from Discord
Manual Rewards	Admins can reward valuable contributions on-the-fly
Natural Participation	Automatic GM/GN detection, quality messages, and voice tracking
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

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

Discord integration settings in Partner Portal

Discord bot permission requirements

Step 2: Connect Your Server to Loyalteez

In your Discord server, run:

/setup connect 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.

Default Events Auto-Created

When you run /setup connect, the bot automatically creates all default events in the database with sensible defaults:

• GM/GN Check-ins (25/15 LTZ, 24h cooldown)
• Server Join Bonus (50 LTZ, one-time)
• Server Boost (500 LTZ)
• Voice Activity (25 LTZ)
• Daily Check-in (10 LTZ)
• And more...

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

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

DM Support

Some commands can be used in Direct Messages with the bot, while others require server context.

Works in DMs	Commands
✅ Yes	/balance, /link, /help
❌ No (server required)	All other commands

When users try to use server-required commands in DMs, they'll receive a helpful message explaining which commands work in DMs.

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 (works in DMs)
/help	View all available commands (works in DMs)

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

Permission System

The Loyalteez Discord bot features a granular permission system with four permission tiers, allowing you to assign different levels of access to your moderators and administrators.

Permission Tiers

Tier	Level	Description	Use Case
Full Admin	4	Complete control - can do everything	Server owners, trusted administrators
Event Manager	3	Create/edit events, change rewards, create drops	Community managers who handle events
Perk Manager	2	Create/edit/delete perks	Team members managing perk catalog
Viewer	1	View-only access to stats and audit logs	Analysts, read-only access

Default Permissions

• Users with Discord's "Manage Server" permission automatically get Full Admin access
• Custom admin roles can be assigned any permission level via /config admin-roles

Permission Hierarchy

Higher permission levels inherit all capabilities of lower levels:

• Full Admin can do everything (Event Manager + Perk Manager + Viewer)
• Event Manager can manage events and view analytics
• Perk Manager can manage perks and view analytics
• Viewer can only view analytics and export data

Configuring Admin Roles

Assign custom Discord roles with specific permission levels:

/config admin-roles role:@Moderator level:event_manager
/config admin-roles role:@CommunityManager level:perk_manager
/config admin-roles role:@Analyst level:viewer

View current admin roles:

/config admin-roles

Change a role's permission level:

/config admin-roles role:@Moderator level:full_admin

Remove an admin role:

/config admin-roles remove:@Moderator

Clear all custom admin roles:

/config admin-roles clear:true

Permission Level Options

Level	Value	Description
Full Admin	full_admin	Complete control (setup, config, everything)
Event Manager	event_manager	Create/edit events, change rewards
Perk Manager	perk_manager	Create/edit/delete perks
Viewer	viewer	View-only access

Examples:

# Add a moderator who can create events but not manage admin settings
/config admin-roles role:@Moderator level:event_manager

# Add a community manager who can manage perks
/config admin-roles role:@CommunityManager level:perk_manager

# Add an analyst with read-only access
/config admin-roles role:@Analyst level:viewer

Admin Channel Notifications

Configure a channel to receive real-time notifications about all reward attempts (success and failure):

/config admin-channel channel:#admin-logs

View current admin channel:

/config admin-channel

Clear admin channel (disable notifications):

/config admin-channel clear:true

Notifications include:

• ✅ Successful rewards with amount and event type
• ❌ Failed reward attempts with error messages
• Role bonuses applied
• User information and metadata

This provides a real-time audit log similar to /audit rewards, but delivered instantly to your admin channel.

Setup & Configuration

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

Perk Management

Create and manage perks directly from Discord without needing the Partner Portal.

Command	Description	Required Permission
/perk create	Create a new perk	Perk Manager+
/perk edit	Edit an existing perk	Perk Manager+
/perk delete	Delete a perk	Perk Manager+
/perk list	List all perks for this server	Any user

Create Perk Options:

/perk create name:"VIP Access" price:1000 description:"Exclusive VIP channel access" category:access max-supply:100 max-per-user:1

Option	Required	Description	Default
name	✅ Yes	Perk name	-
price	✅ Yes	Price in LTZ	-
description	❌ No	Perk description	-
category	❌ No	Category (access, discount, merch, experience, digital, custom)	custom
max-supply	❌ No	Total supply limit (0 = unlimited)	0 (unlimited)
max-per-user	❌ No	Max claims per user (0 = unlimited)	0 (unlimited)
image-url	❌ No	Image URL for the perk	-

Unlimited Supply

Setting max-supply or max-per-user to 0 means unlimited. This is consistent with how the Partner Portal handles these values.

Configuration Subcommands

Command	Description	Required Permission
/config	View current configuration	Viewer+
/config reward <event> <amount>	Set reward for specific event	Event Manager+
/config events	View/create/edit/delete events	Event Manager+ (create/edit), Viewer+ (list)
/config stacking MODE	Set role effect stacking	Full Admin
/config streaks	Configure streak settings	Full Admin
/config voice	Configure voice time rewards	Full Admin
/config third-party	Configure third-party bot integrations	Full Admin
/config sync-roles	Import Discord roles	Full Admin
/config role-bonus	Configure LTZ multipliers and bonuses for roles	Full Admin
/config admin-roles	Configure admin roles and permission levels	Full Admin
/config admin-channel	Configure admin notification channel	Full Admin
/config channels	Configure channel include/exclude	Full Admin
/config user	Enable/disable users	Full Admin
/config test-mode	Enable/disable test mode	Full Admin
/config daily-event	Configure daily check-in event	Event Manager+

Events CRUD Commands

Full event management directly from Discord (includes boost events, custom events, and all other event types):

/config events                               - List all events for this brand
/config events action:create name:EVENT reward:LTZ cooldown:HOURS max-claims:N
/config events action:edit name:EVENT reward:20 cooldown:48 max-claims:5
/config events action:toggle name:EVENT                  - Toggle current state (ON↔OFF)
/config events action:toggle name:EVENT enabled:true     - Explicitly enable
/config events action:toggle name:EVENT enabled:false    - Explicitly disable
/config events action:delete name:EVENT

Smart Toggle

Running /config events action:toggle name:EVENT without specifying enabled: will automatically invert the current state. If the event is currently ON, it will turn OFF, and vice versa. This makes it easy to quickly toggle events without needing to know their current state.

Understanding max-claims for Events

Important Distinction:

1. Regular Events (max-claims = max_claims_per_user):

   • This is a per-user limit - how many times a single user can claim this event
   • Example: max-claims:5 means each user can claim this event up to 5 times (subject to cooldown)
   • There is no total event limit - the event can be claimed by unlimited users, each up to their per-user limit

2. Reaction Drop Events (special case):

   • When you use an event in a reaction drop (/drop type:reaction), the event's max_claims_per_user is repurposed as the drop's total claim limit
   • Example: If an event has max-claims:50, when used in a reaction drop, the first 50 users can claim it (each user can only claim once per drop)
   • Reaction drop events are automatically created with event types like reaction_drop_xxxxx_xxxxx and are marked with 🎯 in the event list

3. Unlimited: Use 999999 or -1 for unlimited claims (both values are normalized to unlimited)

Current Limitation: The system currently only supports per-user limits for regular events. There is no separate "total event claims" limit field. For reaction drops, the per-user limit is repurposed as the total drop limit.

Examples:

# Create first boost event
/config events action:create name:first_boost reward:1000 cooldown:0 max-claims:1

# Create tier-specific boost event
/config events action:create name:tier_2_boost reward:500 cooldown:0

# Edit existing server boost event
/config events action:edit name:server_boost reward:600

# Toggle boost event (auto-inverts current state)
/config events action:toggle name:first_boost

# Explicitly enable or disable
/config events action:toggle name:first_boost enabled:true
/config events action:toggle name:server_boost enabled:false

Events are synced with the Partner Portal monitoring_rules table - changes made in Discord appear in Partner Portal and vice versa.

Role Bonus Commands

Configure LTZ bonuses for Discord roles. Role bonuses apply automatically to all rewards earned by users with that role.

/config role-bonus                           - List all role bonuses
/config role-bonus list:true                 - List all role bonuses (explicit)
/config role-bonus role:@Role multiplier:1.5 - Set 1.5x LTZ multiplier (50% bonus)
/config role-bonus role:@Role flat-bonus:25  - Set +25 LTZ flat bonus per reward
/config role-bonus role:@Role multiplier:2.0 flat-bonus:10  - Set both effects
/config role-bonus clear:@Role               - Remove all bonuses from role

Parameter Limits:

• multiplier: 1.0 to 5.0 (1.0 = no bonus, 2.0 = double rewards)
• flat-bonus: 0 to 1,000 LTZ

Examples:

# VIP role gets 50% bonus on all rewards
/config role-bonus role:@VIP multiplier:1.5

# Whale role gets +25 LTZ added to every reward
/config role-bonus role:@Whale flat-bonus:25

# Server boosters get 2x rewards plus 10 flat bonus
/config role-bonus role:@Server Booster multiplier:2.0 flat-bonus:10

# View all configured bonuses
/config role-bonus

# Remove bonuses from a role
/config role-bonus clear:@OldRole

Stacking with Multiple Roles

If a user has multiple roles with bonuses, effects are combined based on your server's stacking mode (multiplicative, additive, or highest only). Configure stacking with /config stacking MODE.

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	Required Permission
/drop event_id:ID type:button/reaction	Create a button or reaction-based drop for any event	Event Manager+
/drop event_id:ID type:reaction message_id:ID lifespan:2h	Attach a reaction drop to an existing message	Event Manager+
/reaction-drop	Create a reaction-based reward drop	Event Manager+
/reward user:@USER amount:NUMBER reason:TEXT	Manually reward a user	Configured reward roles

---

Analytics & Reporting

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

Server Statistics Dashboard

Command	Description	Required Permission
/stats	Weekly overview	Viewer+
/stats period:day	Daily stats	Viewer+
/stats period:month	Monthly stats	Viewer+
/stats breakdown:events	Event breakdown	Viewer+
/stats breakdown:users	User segments	Viewer+

The dashboard shows:

• Total active users
• LTZ distributed
• Event breakdown
• Top earners
• Growth trends

Audit Logging

Every admin action and significant event is logged:

Command	Description	Required Permission
/audit	Recent 25 events	Viewer+
/audit user:@user	Filter by user	Viewer+
/audit type:config	Filter by action type	Viewer+
/audit export:true	Export as CSV	Viewer+

Logged actions include:

• Configuration changes
• User enable/disable
• Reward distributions
• Setup changes

Data Export

Export data for external analysis:

Command	Description	Required Permission
/export type:rewards period:month	Reward history	Viewer+
/export type:audit period:week	Audit log	Viewer+
/export type:users	User database	Viewer+
/export type:config	Full config backup	Viewer+

---

KPI Tracking & Goals

Setting KPIs

Track performance against targets:

Command	Description	Required Permission
/kpi set metric:daily_active_users target:500 period:week	Set KPI target	Viewer+
/kpi list	View all KPIs	Viewer+
/kpi report	KPI performance report	Viewer+

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:

Command	Description	Required Permission
/goals set name:"Q1 Growth" type:users target:1000 deadline:2024-03-31	Set goal	Viewer+
/goals progress	View goal progress	Viewer+
/goals celebrate	Celebrate completed goals	Viewer+

Scheduled Reports

Automate analytics delivery:

Command	Description	Required Permission
/reports schedule frequency:weekly channel:#admin-stats day:monday	Schedule report	Viewer+
/reports preview	Preview report format	Viewer+
/reports disable	Disable scheduled reports	Viewer+

---

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

Command	Description	Required Permission
/achievements init	Create default achievement set	Event Manager+

Custom Achievements

Command	Description	Required Permission
/achievements create name:"Chatterbox" type:message_count threshold:1000 reward:500	Create achievement	Event Manager+
/achievements remove	Remove achievement	Event Manager+

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:

Command	Description	Required Permission
/game-night create game:"Among Us" duration:2 reward:50	Create game night	Event Manager+
/game-night active	View active game nights	Any user
/game-night join	Join active game night	Any user
/game-night end	End & distribute rewards	Event Manager+

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

1. Go to Integrations → Channels → Discord
2. Select your connected server
3. Click "Configure Role Rewards"
4. 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

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

Database-Driven Configuration

All Natural Participation events are stored in the monitoring_rules Supabase table. When you connect your server via /setup connect, default events are automatically created. Both the Discord bot and Partner Portal read/write from this same source - no hardcoded values.

If an event doesn't exist in monitoring_rules, it won't process. This ensures full configurability.

Features

Feature	Description	Initial Default	Configurable
GM Check-in	Reward users for saying "gm" or "good morning"	25 LTZ, 24h cooldown	✅
GN Check-in	Reward users for saying "gn" or "good night"	15 LTZ, 24h cooldown	✅
Quality Messages	Reward thoughtful, high-quality messages	10 LTZ (disabled)	✅
Popular Messages	Reward when messages reach reaction thresholds	25 LTZ (disabled)	✅
Auto-Welcome	Automatically reward new members on join	50 LTZ, one-time	✅
Server Boost	Special reward for Nitro boosters	500 LTZ	✅
Voice Activity	Reward for time in voice channels	25 LTZ	✅

All values are initial defaults. Fully configurable via /config events or Partner Portal.

---

Server Boost Events

The bot supports custom boost event types that you can configure in Partner Portal. Boost events are automatically detected when users boost your server or when the server tier increases.

Available Boost Event Types

You can create custom boost events with these event types in Partner Portal:

Event Type	Description	When It Triggers
server_boost	Default boost event (all boosts)	Every time someone boosts (default fallback)
first_boost	First boost reward	User's first time boosting the server
tier_1_boost	Tier 1 boost reward	When server reaches Tier 1 (2 boosts)
tier_2_boost	Tier 2 boost reward	When server reaches Tier 2 (7 boosts)
tier_3_boost	Tier 3 boost reward	When server reaches Tier 3 (14 boosts)
boost_tier_upgrade	Tier upgrade reward	When server tier increases (Tier 1→2 or 2→3)

Event Priority Order

The bot checks for boost events in this priority order:

1. Tier-specific (tier_1_boost, tier_2_boost, tier_3_boost) - If server is at that tier
2. First boost (first_boost) - If user hasn't boosted before
3. Tier upgrade (boost_tier_upgrade) - If server tier just increased
4. Generic (server_boost) - Default fallback if no custom events configured

Example: If you have both first_boost and tier_2_boost configured, and a user boosts for the first time when the server is at Tier 2:

• The bot will trigger tier_2_boost (higher priority)
• first_boost will trigger on their next boost (if you configure it for subsequent boosts)

Creating Custom Boost Events

You can configure boost events in two ways: via Discord commands or Partner Portal.

Option 1: Discord Commands (Recommended for Quick Setup)

Admins can create and manage boost events directly from Discord:

Create a boost event:

/config events action:create name:first_boost reward:1000 cooldown:0 max-claims:1
/config events action:create name:tier_2_boost reward:500 cooldown:0

Edit an existing boost event:

/config events action:edit name:first_boost reward:1500
/config events action:edit name:server_boost reward:600 cooldown:720

Toggle event on/off:

/config events action:toggle name:first_boost enabled:true
/config events action:toggle name:server_boost enabled:false

List all boost events:

/config events

Option 2: Partner Portal (Full Configuration)

For advanced configuration with channel constraints, detection methods, and metadata:

1. Go to Events → Create Event
2. Enter event details:
   • Event Name: "First Boost" or "Tier 2 Boost"
   • Event Type: first_boost or tier_2_boost (normalized automatically)
   • Reward: Set your desired LTZ amount
   • Max Claims: 1 for first boost, 999999 for recurring
   • Cooldown: 0 for one-time, or set cooldown for recurring boosts
   • Detection Method: Select "Discord"
   • Enable: Toggle ON

Both methods sync to the same monitoring_rules table - changes made in Discord appear in Partner Portal and vice versa.

Event Automatically Triggers

No additional configuration needed - the bot detects boosts and matches them to your configured events automatically based on priority order.

Example Configuration

Scenario: Reward first boost generously, then standard rewards for subsequent boosts

1. Create first_boost event:

   • Reward: 1,000 LTZ
   • Max Claims: 1
   • Cooldown: 0
   • Enabled: ✅

2. Create server_boost event (for subsequent boosts):

   • Reward: 500 LTZ
   • Max Claims: 999999
   • Cooldown: 0 (or 2,592,000 seconds = 30 days for monthly)
   • Enabled: ✅

Result:

• First boost: User gets 1,000 LTZ (from first_boost event)
• Subsequent boosts: User gets 500 LTZ (from server_boost event)

Tier-Specific Rewards Example

Scenario: Scale rewards based on server tier

1. Create tier_1_boost event:

   • Reward: 200 LTZ
   • Enabled: ✅

2. Create tier_2_boost event:

   • Reward: 500 LTZ
   • Enabled: ✅

3. Create tier_3_boost event:

   • Reward: 1,000 LTZ
   • Enabled: ✅

Result:

• When server is Tier 1: Boosters get 200 LTZ
• When server is Tier 2: Boosters get 500 LTZ
• When server is Tier 3: Boosters get 1,000 LTZ

First Boost Detection

The bot automatically tracks whether a user has boosted before:

• First boost: Triggers first_boost event (if configured)
• Subsequent boosts: Triggers server_boost or tier-specific events

First boost status is permanently stored in KV, so first_boost will only fire once per user, even across server restarts.

Tier Upgrade Events

When the server tier increases (e.g., from Tier 1 to Tier 2), the bot can trigger a boost_tier_upgrade event:

• Detected automatically via guildMemberUpdate event
• Includes new tier level in event data
• Useful for rewarding users when the server reaches milestone tiers

---

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
  }
}

How Natural Participation Works

When you connect your Discord server via /setup, natural participation features are automatically enabled:

1. Real-time Detection: Loyalteez monitors messages in your server for GM/GN patterns, quality content, and engagement
2. Automatic Rewards: When patterns are detected, rewards are automatically distributed to users
3. No Configuration Needed: Default settings work out of the box, but you can customize via /config

What Gets Detected:

• GM/GN messages (with 24-hour cooldown)
• Quality messages (100+ characters, thoughtful content)
• Voice channel activity
• Third-party bot level-ups (Mee6, Arcane, etc.)
• Server boosts

Verification: Run /test all in your Discord server to verify natural participation is working. You should see "Natural Participation: Active" in the diagnostic report.

---

Streak & Attendance System

Reward consistent engagement with streak bonuses.

How It Works

1. Users check in daily with /daily
2. Consecutive days build their streak counter
3. Streak multipliers increase rewards
4. 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 (1-72 hours, default: 24 hours) that allows users to miss time without losing their streak.

/config streaks grace-period:8    # 8 hour grace period
/config streaks grace-period:48   # 48 hour grace period

Shorter grace periods (e.g., 8 hours) encourage more frequent engagement while longer periods (48-72 hours) are more forgiving for casual communities.

---

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

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

---

Third-Party Bot Integration

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

Events Created as Configurable

When you enable a third-party bot via /config third-party enable:<bot>, the bot creates events in monitoring_rules with default settings (25 LTZ, no cooldown). These events are then fully configurable like any other event:

/config third-party enable:mee6    # Creates mee6_level_up event
/config events action:edit name:mee6_level_up reward:100 cooldown:1

This ensures third-party bot rewards are managed the same way as all other events.

Third-Party Commands

/config third-party                          - View status of all third-party integrations
/config third-party enable:<bot>             - Enable a bot and create its events
/config third-party disable:<bot>            - Disable a bot (events deactivated, not deleted)
/config third-party reward:<bot> amount:<N>  - Set reward amount (1-10,000 LTZ)

Examples:

# Enable Mee6 integration (creates mee6_level_up event)
/config third-party enable:mee6

# Set reward for Arcane level-ups
/config third-party reward:arcane amount:50

# Disable Tatsu integration
/config third-party disable:tatsu

# Check current status
/config third-party

Validation

The bot provides helpful error messages if you forget a required parameter:

• reward:mee6 without amount: → Shows "Missing amount!" with usage example
• amount:50 without reward: → Shows "Missing bot name!" with supported bot list

Supported Bots (15 Total)

Bot	Events Tracked
Mee6	Level-ups, leaderboard milestones
Arcane	Level-ups, daily streaks
Arcane Premium	Level-ups (premium features)
Tatsu	Level-ups, achievements
Carl-bot	Reaction roles, moderation rewards
The Engage	Engagement milestones, XP
Rumble Royale	Battle wins, tournament placements
Lurkr	Level-ups, role rewards
Atom (leveling.gg)	Level-ups, XP gains
Dyno	Level-ups, announcements
AmariBot	Level-ups, weekly rewards
ProBot	Level-ups, XP
UnbelievaBoat	Level-ups, economy rewards
Zira	Reaction roles
YAGPDB	Level-ups, reputation

Setup

1. Go to Partner Portal → Integrations → Discord → Third-Party Integrations
2. Enable desired integrations
3. Configure reward amounts per event type
4. 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 & Engagement Events

Create engaging events where users react to claim rewards. Drops can be attached to any message (including announcements you post) and linked to custom event types from your Partner Portal.

Enhanced /drop Command

The /drop command supports both button-based and reaction-based drops, with full integration to custom events configured in your Partner Portal.

Basic Usage

Button-based drop (default):

/drop event_id:announcement_engagement label:"Claim Reward" description:"Special announcement reward!"

Reaction-based drop (attach to existing message):

/drop event_id:announcement_engagement type:reaction message_id:123456789 emoji:🎉 lifespan:2h

Full Command Options

Parameter	Required	Description	Examples
event_id	✅ Yes	Event ID from Partner Portal (supports spaces: "Announcement Engagement" → announcement_engagement)	announcement_engagement, gm_checkin
type	❌ No	Drop type: button or reaction (default: button)	button, reaction
message_id	❌ No	Discord message ID to attach reaction drop to (for reaction drops)	123456789012345678
emoji	❌ No	Emoji for reaction drops (default: 🎉)	🎉, ✅, 💰
lifespan	❌ No	Drop lifespan: time units or permanent/0 (default: 24h)	1s, 5m, 2h, 24h, permanent
label	❌ No	Button label text (for button drops)	"Claim Reward"
description	❌ No	Description message above button/drop	"Special announcement reward!"

Lifespan Options

Drops can be configured with precise time-based lifespans or set to never expire:

Time-based (1 second to 168 hours):

• 1s - 1 second (great for testing)
• 5m - 5 minutes
• 2h - 2 hours
• 24h - 24 hours (default)
• 168h - 1 week (maximum timed)

Permanent (never expires):

• permanent - Drop never expires
• 0 - Drop never expires (alternative)
• unlimited - Drop never expires (alternative)
• forever - Drop never expires (alternative)

Note: Permanent drops remain active until manually deleted or max claims are reached.

Embedding Drops in Announcements

You can embed reaction drops directly into your announcements:

1. Post your announcement in Discord (e.g., @everyone Special surprise integrated into discord!)
2. Right-click the message → Copy Message ID
3. Run the drop command:

   /drop event_id:announcement_engagement type:reaction message_id:PASTE_MESSAGE_ID lifespan:2h emoji:🎉

4. Bot automatically adds the emoji reaction to your message
5. Users react with the emoji to claim rewards

Custom Event Integration

Reaction drops are fully integrated with custom events from your Partner Portal:

Example: Announcement Engagement Event

1. Create event in Partner Portal:

   • Name: Announcement Engagement
   • Event Type: announcement_engagement (normalized automatically)
   • Reward: 25 LTZ
   • Max Claims Per User: 50 (this becomes the drop's total claim limit - first 50 users can claim)
   • Cooldown: 1 hour
   Max Claims: Event-Level vs Drop-Level

   • Event-level max_claims_per_user: When used in a reaction drop, this value becomes the total number of users who can claim the drop (not per-user). For example, max_claims_per_user: 50 means the first 50 users who react can claim it.
   • Drop-level behavior: Each user can only claim a reaction drop once, regardless of the event's max_claims_per_user setting. The event's max_claims_per_user value controls how many total users can claim.

2. Use the event in Discord:

   /drop event_id:Announcement Engagement type:reaction message_id:123456789 lifespan:2h

   (Event name with spaces is automatically normalized: "Announcement Engagement" → announcement_engagement)

3. Event configuration is pulled from Partner Portal:

   • Reward amount comes from event config
   • Max Claims Note: The event's max_claims_per_user (per-user limit) is used as the drop's total claim limit (how many total users can claim). For example, if an event has max_claims_per_user: 50, the reaction drop will allow up to 50 total users to claim it, not 50 claims per user.
   • Cooldown periods respected
   • All claims tracked for analytics

Event Name Normalization

Event names with spaces are automatically normalized when stored:

• "Announcement Engagement" → announcement_engagement (database)
• Both formats work in the /drop command
• Lookups match normalized names automatically

How Reaction Drops Work

1. Admin creates drop → Bot creates drop record and (optionally) adds emoji to message
2. Users react with the specified emoji to the message
3. Worker validates:
   • ✅ Active drop exists for this message
   • ✅ Correct emoji used
   • ✅ User hasn't already claimed
   • ✅ Max claims not reached
   • ✅ Drop hasn't expired (if timed)
   • ✅ Event is enabled in Partner Portal
4. Reward distributed → User receives LTZ from event config
5. Feedback sent → ✅ emoji reaction confirms successful claim
6. DM notification → User receives a DM confirming the reward amount
7. Analytics tracked → Claim recorded in audit log for /stats

DM Notifications

When users successfully claim a reaction drop, they receive a Direct Message from the bot confirming the reward:

"🎉 You claimed 25 LTZ from a reaction drop in Server Name!"

This provides immediate feedback without cluttering the channel.

Channel-Based Custom Events

Events can be configured to trigger only in specific channels:

Example: Technical Discussion Event

• Event: technical_discussion
• Detection: Discord interaction
• Allowed Channels: dev-chat, bot-demo-channel
• Reward: 5 LTZ per message in these channels

Users posting in #dev-chat or #bot-demo-channel automatically receive rewards when the event is configured in Partner Portal with these channel constraints.

Configure in Partner Portal:

1. Go to Events → Select event
2. In Detection Methods, ensure Discord is selected
3. Enter channel names in Allowed Channels field (comma-separated)
4. Event only triggers in listed channels

---

Manual Rewards (/reward)

Allow trusted roles to reward users for valuable contributions.

Usage

/reward user:@Username event_id:helpful_contribution

Configuration

1. Allowed Roles: Configure which roles can use /reward in Partner Portal
2. Event Types: Restrict which events can be triggered manually
3. Cooldowns: Set per-user cooldowns to prevent abuse
4. 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. Leaderboards show proper Discord @mentions so you can easily see and interact with top performers.

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

Discord @Mentions

Leaderboard entries display users as clickable Discord mentions (e.g., @Username) rather than plain text usernames. This makes it easy to recognize, tag, or interact with top community members directly from the leaderboard.

---

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

Event-Level Channel Constraints

Restrict specific events to only trigger in designated channels. This is configured per-event in Partner Portal → Events → Event Details.

How to Configure:

1. Go to Events in Partner Portal
2. Click on an event to expand details
3. In Detection Methods section, ensure Discord is selected
4. Enter allowed channel names in the Allowed Channels field

Example:

Allowed Channels: feedback, support, tech-talk

Behavior:

• If channels are specified: Event only triggers when message/action occurs in listed channels
• If channels are empty: Event triggers in any channel (no restriction)
• Channel names are case-insensitive
• Use channel names without # prefix (e.g., feedback not #feedback)

Use Cases:

Event	Allowed Channels	Purpose
Bug Report	report-bugs, bugs	Only count bug reports from dedicated channels
Tech Discussion	tech-talk, dev-chat	Reward quality posts in technical channels
GM Check-in	gm-gn	Prevent GM spam in general channels
Product Feedback	feedback, suggestions	Direct feedback to appropriate channels

Import with Channels

When importing events from CSV or Markdown, include a channels column:

name,reward_amount,detection_method,channels
Bug Report,25,discord,report-bugs|bugs
Tech Discussion,5,discord,tech-talk|dev-chat

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

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

Wallet Resolution

When a user interacts with the bot:

1. Bot extracts Discord user ID
2. Generates deterministic email identifier
3. Loyalteez API resolves or creates wallet via Privy
4. 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

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

Preventing Abuse

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

Maximizing Engagement

1. Embed Drops in Announcements: Use /drop type:reaction message_id:... to attach rewards to your announcements for instant engagement
2. Channel-Specific Events: Configure events with channel constraints to reward quality participation in focused channels
3. Streak Incentives: Promote streak system to encourage daily visits
4. Role Rewards: Create aspirational roles with meaningful bonuses
5. Third-Party Sync: Reward existing bot engagement
6. Achievements: Initialize achievements to gamify participation
7. Game Nights: Schedule regular gaming events with bonus rewards
8. Permanent Drops: Create permanent reaction drops on important messages (rules, welcome, resources) that never expire

Analytics Best Practices

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

Technical Recommendations

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

---

Troubleshooting

Bot Not Responding

1. Check bot permissions with /setup check
2. Verify bot role is above managed roles
3. Check channel permissions specifically
4. Ensure /setup was completed successfully

Rewards Not Processing

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

Role Effects Not Applying

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

Stats Not Updating

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

Third-Party Bots Not Detecting

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

Server Not Showing in Partner Portal

1. Ensure /setup brand_id:... was run with correct address
2. Check Supabase discord_server_configs table
3. 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

1. Onboard members who understand the product
2. Encourage thoughtful technical discussion
3. Turn feedback and bug reports into product improvements
4. 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

1. Maximize active voice participation
2. Reward competitive and cooperative play
3. Build strong social connections
4. 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

Social Engagement

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

1. Drive product discovery and education
2. Reward brand ambassadors
3. Create exclusive deals for community
4. 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

1. Choose your template - Select the sample program closest to your community type
2. Customize rewards - Adjust LTZ amounts based on your budget and goals
3. Configure in Partner Portal - Set up events in Automation and channels in Integrations → Discord
4. Test with small group - Run a pilot with trusted members
5. 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

---

Additional Resources

• Partner Portal Guide
• Perk Market
• API Documentation