Skip to content

Home

Jump to bottom
LukeZ edited this page Feb 13, 2026 · 8 revisions

Caution

Top.gg webhooks currently only works for Legacy Webhooks since Top.gg revamped their webhooks system.

Welcome to the UpvoteEngine wiki!

UpvoteEngine handles top.gg votes and applies roles, either temporary or permanently, in your associated discord server.

Currently supported platforms

  • Top.gg
  • DBL (Discord Bot List)

There are more platforms planned, but not added yet (because every platform requires a completely new handler).

How to use the bot

Use the /app command to configure your application. This commands requires Manage Server perms by default.

Note, that you can have up to 25 applications per server, but can only have one server configured per application + source.

Commands

Command Description
/ping Responds with a pong
/app add Configure a new application connection for the server
/app edit Edit an application connection for the server
/app remove Remove an application connection the server
/app list List all application connections for the server
/app forwarding set Set the forwarding configuration for an added application
/app forwarding edit Edit a forwarding configuration
/app forwarding remove Remove a forwarding configuration
/app forwarding view View the forwarding configuration (Secret is sanitized, only the first 4 characters are shown)
/app ownership-verify Verify the ownership of an app

Always read the descriptions everywhere. Please.

Quick Start

UpvoteEngine works differently depending on which voting site you use:

  • Top.gg - Requires a setup by a bot owner, then server admins can configure rewards
  • Discord Bot List (DBL) - Server admins can set up everything directly

Setting Up Top.gg Vote Rewards

Step 1: Bot Owner Setup

If you own the bot, you need to connect UpvoteEngine on Top.gg first:

  1. Go to your bot's Top.gg dashboard: https://top.gg/bot/YOUR_BOT_ID/dashboard/integrations
  2. Find UpvoteEngine in the integrations list
  3. Click Connect
  4. Done! Server admins can now configure vote rewards

Step 2: Configure Your Server's Rewards

Once the bot owner has connected the integration, server admins can set up rewards:

  1. Use /app edit
  2. Select your bot
  3. Choose "topgg" as the source
  4. Pick a role to give voters
  5. Set how long the role lasts in hours (optional, 1 hour - 14 days)

That's it! Members who vote will now receive the role automatically.

Testing Your Setup

Top.gg lets you send test votes to make sure everything works:

  1. Visit your bot's integrations page on Top.gg
  2. Trigger a test vote
  3. If everything is configured correctly, you should get a DM from the bot

Setting Up DBL Rewards

DBL is simpler - no bot owner setup needed!

  1. Use /app create
  2. Select your bot
  3. Choose "dbl" as the source
  4. Pick a role to give voters (required)
  5. Set how long the role lasts in hours (optional, 1 hour - 14 days)

Done! Your server is ready to reward voters.

Managing Your Apps

View All Configured Bots

Use /app list to see all bots you've set up in your server.

Edit an Existing Configuration

Use /app edit to change the role or duration for any configured bot.

Remove a Bot Configuration

Use /app remove to stop rewarding votes for a bot. This will:

  • Stop assigning roles to new voters
  • Remove all vote history for that bot
  • Delete any webhook forwarding settings

Important

If you remove a Top.gg configuration, you'll also need to disconnect the integration on Top.gg's website.

Forwarding Webhooks (Advanced)

Want to send vote data to your own website or service? You can forward vote notifications!

Setting Up Forwarding

  1. Use /app forwarding set
  2. Select your bot and source
  3. Enter your webhook URL
  4. Optionally set a secret for security

Managing Forwarding

  • /app forwarding view - See your current forwarding setup
  • /app forwarding edit - Change the URL or secret
  • /app forwarding remove - Stop forwarding webhooks

Security Notes

For your protection, you cannot forward to:

  • localhost or private IP addresses
  • The UpvoteEngine service itself
  • Invalid or unsafe URLs

Who Can Configure Apps?

Top.gg Apps

You can configure a Top.gg app if you are:

  • The person who connected the integration on Top.gg
  • A verified bot owner (use /verify-app-ownership to verify)
  • The UpvoteEngine service owner

DBL Apps

Any server admin (with "Manage Server" permission) can configure DBL apps.

Limits

  • Maximum of 25 bot configurations per server
  • Role duration: 1 hour minimum, 14 days (336 hours) maximum

Common Questions

Q: Why can't I create a Top.gg app?

  • A: The bot owner must connect the UpvoteEngine integration on Top.gg first. If you see a setup message, share the integration link with your bot owner.

Q: What's the difference between /app create and /app edit?

  • A:
    • For Top.gg: Use /app edit to configure rewards (create only shows setup instructions)
    • For DBL: Use /app create for new setups, /app edit to change existing ones

Q: Can I have multiple servers for one bot?

  • A: No.

Q: What happens if I remove the role while someone has it?

  • A: The system will try to assign the configured role. If the role no longer exists, votes will still be recorded but the role won't be assigned.

Q: Do voters keep the role forever?

  • A: Only if you don't set a duration. If you set a duration (e.g., 24 hours), the role will be automatically removed after that time.

Need Help?

If something isn't working:

  1. Check that your bot is in the server
  2. Make sure the role you selected still exists
  3. Verify the bot has permission to assign that role (UpvoteEngine's role must be higher than the reward role)
  4. Try sending a test vote if available

Still stuck? Join the support server for help.

Clone this wiki locally