Discord Bot Integration

Reward your Discord community members with LTZ tokens for participation, events, and engagement.

Choose Your Integration Level

There are two ways to integrate Loyalteez with Discord:

Method	Best For	Complexity	Features
Standard (Serverless)	AMAs, Events, Daily Check-ins	🟢 Easy	Slash Commands, Reward Buttons ("Drops"), Daily Habit Loops
Advanced (Gateway)	Message counting, Voice time, Roles	🔴 Expert	Passive tracking, Auto-moderation rewards

---

Option 1: Standard Serverless Bot (Recommended)

This bot runs on Cloudflare Workers (free tier usually sufficient) and requires no 24/7 server management. It uses Interactive Buttons to let users claim rewards and handles blockchain transaction delays automatically.

Features

• Slash Commands: /join, /daily, /balance
• Reward Drops: Admins can generate claim buttons for any custom event.
• Daily Habit Config: Admins can bind /daily to any event ID dynamically.
• Deferred Responses: Handles long-running blockchain transactions without timing out.

Installation

We provide a ready-to-deploy template.

1. Clone the Repository:

   git clone https://github.com/Alpha4-Labs/discord-loyalty-bot.git
   cd discord-loyalty-bot

2. Configure: Copy wrangler.example.toml to wrangler.toml and add your credentials.

   • Important: You must add your Discord Server ID to the Partner Portal -> Settings -> Profile -> Authentication Methods to authorize the bot.

3. Deploy:

   npm install
   npm run deploy

4. Register Commands:

   node scripts/register-commands.js

Using "Drops" for Events (No-Code)

This is the most powerful feature for community engagement. You can create events in the Partner Portal and drop them into Discord without writing code.

1. Create Event: Go to Partner Portal -> Settings -> Events.
2. Configure:
   • Click "Create Custom Event".
   • Select "Discord Bot Interaction" as the detection method.
   • Set your reward (e.g., 50 LTZ).
3. Get Command: Expand the event in the list to see your generated command:

   /drop event_id:custom_123... label:"Claim Reward"

4. Deploy: Paste the command into your Discord channel. Users click to claim!

Configuring Daily Rewards

You can create a "Daily Check-in" habit loop easily:

1. Create a Custom Event in the Portal (e.g., "Daily Bonus", Reward: 10 LTZ, Cooldown: 24h).
2. Copy the Event ID (e.g., custom_daily_bonus).
3. In Discord (as Admin), run:

   /daily-config event_id:custom_daily_bonus

4. Now, whenever users type /daily, they claim this specific reward.

---

Option 2: Advanced Gateway Bot (Node.js)

If you need to reward users for passive actions (like "sending 100 messages" or "staying in voice chat for 1 hour"), you need a bot that stays online 24/7 to listen to all events.

Setup

1. Initialize Project:

   npm init -y
   npm install discord.js axios dotenv

2. Create Bot Code:

const { Client, GatewayIntentBits } = require('discord.js');
const axios = require('axios');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
    GatewayIntentBits.GuildVoiceStates,
  ],
});

const LOYALTEEZ_API = 'https://api.loyalteez.app/loyalteez-api/manual-event';
const BRAND_ID = process.env.BRAND_ID;

// Track event function
async function trackEvent(userId, username, eventType) {
  try {
    await axios.post(LOYALTEEZ_API, {
      brandId: BRAND_ID,
      eventType: eventType,
      userEmail: `discord_${userId}@loyalteez.app`, // Deterministic mapping
      metadata: {
        platform: 'discord',
        username: username
      }
    });
    console.log(`Reward sent to ${username}`);
  } catch (error) {
    console.error('Reward failed:', error.message);
  }
}

// Example: Reward for messages containing "help"
client.on('messageCreate', async (message) => {
  if (message.author.bot) return;
  
  if (message.content.includes('help')) {
    await trackEvent(message.author.id, message.author.username, 'helpful_message');
    message.reply('You earned points for helping!');
  }
});

client.login(process.env.DISCORD_TOKEN);

Deployment

You must host this bot on a VPS (like Railway, Heroku, or DigitalOcean). It cannot run on Cloudflare Workers.

---

User Identification

Loyalteez maps Discord users to wallets using a deterministic email format:

[email protected]

• Deterministic: The same Discord user always gets the same wallet.
• Cross-Server: Rewards from different servers go to the same user account.
• Claiming: Users log in to the Perk Marketplace using "Login with Discord" to spend their points.

Best Practices

1. Use Cooldowns: Configure cooldowns in the Partner Portal to prevent spam (e.g., "Daily Check-in" = 24 hours).
2. Gate Channels: For VIP rewards, put the /drop in a private channel visible only to specific roles.
3. Whitelist Server ID: Always ensure your Discord Server ID is added to your Brand Profile in the Partner Portal, or rewards will fail.

Support

• Repo Issues: GitHub Issues
• API Docs: Event Handler API