Howli Documentation & Setup Guide

Complete guide to setting up and using Howli for your Discord server

Quick Start Guide

Step 1: Invite Howli to Your Server

To add Howli to your Discord server, you'll need the Manage Server permission. Click the button below to begin the authorization process:

Add Howli to Server

Note: Make sure you select the correct server from the dropdown menu during authorization.

Step 2: Verify Bot Permissions

After inviting Howli, verify that the bot has the necessary permissions in your server settings:

  • Ban Members - Required for trap channel functionality
  • Manage Roles - Needed for role replacement features
  • Manage Messages - Required for auto-delete functionality
  • View Channels - Allows the bot to monitor configured channels
  • Send Messages - For welcome messages and notifications
  • Embed Links - For formatted log messages

Important: Howli's role must be positioned higher than any roles it needs to manage in your server's role hierarchy.

Step 3: Access the Dashboard

Log in to the Howli dashboard using your Discord account:

  1. Click "Login with Discord" at the top of this page
  2. Authorize the dashboard to access your Discord information
  3. You'll be redirected to your server management dashboard
  4. Select the server you want to configure

Step 4: Basic Configuration

Configure the essential features for your server:

  • Mod Log Channel: Set up a channel where Howli will log all moderation actions
  • Trap Channel: Designate channels that will trigger automatic bans when posted in
  • Ban Message: Customize the message users see when banned

All configuration changes take effect immediately - no bot restart required!

Features Guide

Trap Channel Management

Trap channels are honeypot channels designed to catch and automatically ban bad actors, spammers, and raiders.

All tiers: 1 trap channel per server

How It Works:

  1. Create a channel that appears attractive to spam bots or raiders (e.g., "free-nitro", "admin-verification")
  2. Configure this channel as a trap channel in your dashboard
  3. Hide the channel from legitimate members using Discord's permission system
  4. When someone posts in the trap channel, Howli automatically bans them
  5. The action is logged in your mod log channel with full details

Best Practices:

  • Use enticing names like "admin-chat", "mod-verification", or "free-rewards"
  • Remove view permissions for @everyone and only show to suspicious accounts
  • Set a custom ban message explaining why they were banned
  • Monitor your mod log regularly to review trap channel bans

Configuration Options:

  • Strategic Placement: Position your trap channel to catch the most bad actors
  • Custom Ban Messages: Tailor the ban message for the trap channel
  • Ban Duration: Set temporary bans that auto-expire after a specified time
  • Whitelist Roles: Exempt certain roles (like moderators) from trap channel bans

Auto-Delete Messages

Automatically remove messages after a specified time period to keep channels clean and organized.

Free: 2 channels, 7+ days minimum • Premium: Unlimited channels, 1 hour to 365 days

Use Cases:

  • Announcement Channels: Auto-delete old announcements after 30 days
  • Event Coordination: Remove past event details to avoid confusion
  • Temporary Channels: Keep channels focused on current topics
  • Bot Commands: Auto-cleanup bot command channels

Configuration:

  • Set retention period: 1-365 days
  • Configure per-channel or apply to multiple channels
  • Exclude pinned messages from deletion (optional)
  • Exempt specific roles from auto-deletion

How It Works:

Howli checks configured channels every hour and deletes messages older than your specified retention period. Deletion is logged in your mod log channel for transparency.

Role Management & Replacement Premium

Automatically manage role assignments and prevent role conflicts with intelligent role replacement rules.

Premium Feature: Role replacement and automation requires a Premium subscription. View pricing or use /claimtrial for a free 7-day trial!

Features:

  • Role Replacement: When a user gains Role A, automatically remove Role B
  • Role Progression: Create upgrade paths (Member → Trusted → VIP)
  • Conflict Prevention: Prevent incompatible roles from being assigned together

Example Scenarios:

  • When user gets "Verified" role, remove "Unverified" role
  • When user gets "Premium" role, remove "Free" role
  • When user gets "Muted" role, remove all chat-related roles

Setup:

  1. Go to Role Settings in your dashboard
  2. Click "Add Role Replacement Rule"
  3. Select the trigger role (role that causes the replacement)
  4. Select role(s) to be removed when trigger role is assigned
  5. Save and test with a test account

Welcome Messages Premium

Send customized welcome messages to users when they receive specific roles.

Premium Feature: Welcome role messages require a Premium subscription. View pricing or use /claimtrial for a free 7-day trial!

Supported Placeholders:

  • {username} - User's display name
  • {mention} - Mentions the user
  • {server} - Server name
  • {role} - Name of the role they received
  • {membercount} - Total server member count

Example Messages:

Welcome {mention}! You've been assigned the {role} role. Enjoy your time in {server}!

Congratulations {username}! You're now a trusted member with access to exclusive channels.

Configuration Tips:

  • Keep messages concise and informative
  • Include links to relevant channels or rules
  • Use embeds for professional-looking messages
  • Set up different messages for different role tiers

Moderation Logs

Comprehensive logging of all moderation actions performed by Howli.

Logged Actions:

  • Trap channel bans (with reason and channel)
  • Auto-deleted messages (count and channel)
  • Role changes (added/removed roles)
  • Configuration changes (who changed what)
  • Welcome message triggers

Log Format:

Each log entry includes:

  • Timestamp (with timezone)
  • Action type and description
  • User involved (ID and mention)
  • Responsible moderator (if applicable)
  • Additional context (channel, reason, etc.)

Best Practices:

  • Create a dedicated, staff-only log channel
  • Disable @everyone permissions in the log channel
  • Review logs regularly for unusual activity
  • Use Discord's search to find specific log entries

Permission Requirements

Required Bot Permissions

Permission Required For Why It's Needed
Ban Members Trap Channels Allows Howli to automatically ban users who post in trap channels
Manage Roles Role Management Enables role replacement and automatic role assignments
Manage Messages Auto-Delete Required to delete old messages in configured channels
View Channels All Features Allows bot to see and monitor configured channels
Send Messages Logs & Welcome Sends log entries and welcome messages
Embed Links Logs Creates formatted, easy-to-read log entries
Read Message History Auto-Delete Reads message timestamps for auto-deletion feature

Important Notes:

  • Role Hierarchy: Howli can only ban users and manage roles below its own role position
  • Channel Permissions: Ensure Howli has access to all channels it needs to monitor
  • Administrator: While not required, Administrator permission simplifies setup
  • Testing: Test all features with a secondary account before deploying to production

Advanced Configuration

Dashboard Configuration

Access all configuration options through the web dashboard at howli dashboard.

Server Selection

Your dashboard displays all servers where you have "Manage Server" permission and Howli is installed. Click on a server card to access its configuration page.

Configuration Sections

  • General Settings: Basic server info, subscription status, and primary channels
  • Trap Channels: Configure honeypot channels and ban settings
  • Auto-Delete: Set up message retention rules per channel
  • Role Management: Create role replacement rules and hierarchies
  • Welcome Messages: Customize role-specific welcome messages
  • Mod Logs: Configure log channel and log verbosity

Exporting Configuration

You can export your server's configuration as JSON for backup purposes or to replicate settings across multiple servers.

Multi-Server Management

If you manage multiple servers, Howli makes it easy to configure each one independently:

  • Each server has its own separate configuration
  • Switch between servers using the dashboard dropdown
  • Copy configurations between servers using export/import
  • View aggregate statistics across all your servers

Best Practices

Security

  • Regularly review your trap channel ban logs for patterns
  • Keep Howli's role position high in your role hierarchy
  • Use role whitelists to prevent accidental mod bans
  • Enable 2FA for all accounts with Howli configuration access
  • Regularly audit who has "Manage Server" permission

Performance

  • Don't set auto-delete retention periods too short (min 1 day recommended)
  • Position your trap channel strategically for maximum effectiveness
  • Use specific channels for auto-delete rather than server-wide
  • Review and clean up unused configuration regularly

User Experience

  • Make ban messages clear and informative
  • Include appeal information in ban messages
  • Keep welcome messages friendly and concise
  • Test all features with secondary accounts first
  • Inform your mod team about Howli's automated actions

Moderation Team

  • Create a dedicated mod-only channel for Howli logs
  • Train your team on how Howli works and its features
  • Establish clear guidelines for trap channel setup
  • Review automated bans weekly to ensure accuracy
  • Use Howli's logs as part of mod accountability

Troubleshooting

Howli isn't banning users in trap channels

Possible causes:

  • Check if Howli has "Ban Members" permission
  • Verify Howli's role is higher than the target user's highest role
  • Ensure the trap channel is correctly configured in the dashboard
  • Check if the user has a whitelisted role
  • Verify Howli can see the trap channel (View Channel permission)

Auto-delete isn't working

Possible causes:

  • Verify Howli has "Manage Messages" and "Read Message History" permissions
  • Check that the channel is correctly configured with a retention period
  • Auto-delete runs hourly - wait at least 1 hour after setup
  • Pinned messages are never deleted (this is intentional)
  • Messages from whitelisted roles won't be deleted

Role replacement isn't triggering

Possible causes:

  • Ensure Howli has "Manage Roles" permission
  • Verify Howli's role is higher than all roles it needs to manage
  • Check that the rule is correctly configured (trigger role → remove role)
  • Test with a secondary account to verify the rule
  • Check mod logs to see if there were any errors

Dashboard not showing my servers

Possible causes:

  • Ensure you have "Manage Server" permission in the target server
  • Verify Howli is actually in the server (check member list)
  • Try logging out and back in to refresh your server list
  • Check if the server has Howli properly configured
  • Ensure the subscription is active for the server

Getting Help

If you're still experiencing issues:

  • Check the Feedback page to submit a support request
  • Review the mod log channel for error messages
  • Ensure your Discord and Howli subscriptions are up to date
  • Try removing and re-adding Howli to reset permissions

Additional Resources

View Changelog Submit Feedback Privacy Policy Terms of Service