stickbot

A self-hosted Discord bot for managing and sharing custom stickers. Upload images and videos, tag them for quick searching, and share stickers in any server or DM. Includes permission management for sharing with friends.

Usage

Adding Stickers

You can add new stickers with the /addsticker command. You'll need to give it a unique title and a list of space-separated tags, as well as the file itself.

Most image/video formats are supported. E.g., jpeg, png, gif, webp, .mp4, .mkv, .ts, etc.

Example:

/addsticker title:apu spills his tendies tags:pepe sad crying floor tripped url:https://i.kym-cdn.com/entries/icons/original/000/037/319/cover1.jpg

Availability: Any Server, Any DM.

Note

You're required to provide either a direct link to the file with the url option, or provide the file itself with the file option.

Listing Stickers

You can use the /liststickers command to view a list of all your stickers. The command allows you to narrow down the list with the query option. You can also change the order of the stickers with the order option. By default they are sorted from most to least recently used.

Examples:

/liststickers

/liststickers query:funny

/liststickers query:funny info:True

/liststickers query:cat order:Most Used

Availability: Any Server, Any DM.

Tip

You can view sticker titles and tags by setting the info option to True. Now when you pick one of the stickers from the list, the bot will also return its title and tags.

Sending Stickers

You don't have to use /liststickers unless you want to preview the sticker before you send it. If you already know the title of the sticker you want to send, the /sticker command is quicker to use.

The /sticker command only has one option, query, and it is required. The query option is what you'll use to narrow down the list of suggestions. Once the sticker you're looking for shows up on the list, click on it or navigate to it with your keyboard and press enter.

Example:

/sticker query:funny dog

The query in the example would narrow down the suggestions to stickers whose titles or tags contain both the words "funny" and "dog"

Availability: Any Server, Any DM.

Important

Even if you know the exact title of the sticker you're looking for, you still need to pick it from the suggestion list! That is because the bot doesn't use the title to find the stickers, it uses unique IDs. When you choose one of the suggestions, what you're sending to the bot is that sticker's ID, not its title.

Tip

The query option works with tags as well, not just titles!

Tip

The query option also works with prefixes, e.g., searching for "fun" will match both "fun" and "funny"!

Editing Stickers

While you can't edit the stickers themselves, you can edit their title, tags, and description.

To edit a sticker you use the /editsticker command. The command only has one required option, query. Read the Important alert in the previous section if you don't know how the option works.

After selecting a sticker from the query dropdown, you can edit titles and/or tags with their respective options.

Availability: Any Server, Any DM.

Tip

After selecting a sticker to edit with the query option, the title and tags options will suggest you their original values, so you don't have to type everything again.

Note

If you need to replace a sticker's file, you can grab its title and tags with the help of /liststickers info:True, then delete the sticker and add a new one with the old title and tags.

Deleting Stickers

You can delete stickers with the /deletesticker command. Its only option is query, use it to find the sticker you want and delete it.

Availability: Any Server, Any DM.

Adding Users

Out of the box, only you, the owner, are allowed to use any command. If you wish to allow someone else to use the bot, you need to use the /adduser command. The command only has two required options: id and username. You can find a user's ID by right-clicking their name on Discord¹. The username option doesn't have to match their actual username.

If you're granting the user most/all permissions, it might be faster to set the grant-all option to True. You can still override individual permissions when using the grant-all option.

There are also six other options that correspond to the user's permissions: add-sticker, edit-sticker, delete-sticker, add-user, edit-user, delete-user. The values for each of these options defaults to False (unless you set grant-all to True), so you only need to set them to True if you wish to grant the user that permission.

Examples:

/adduser id:315430983126210624 username:chris add-sticker:True edit-sticker:True

/adduser id:315430983126210625 username:greg grant-all:True edit-user:False delete-user:False

Availability: Your Server Only

Note

If only wish to give the user permission to list/send stickers, you don't need to grant any permission. Adding them with all permissions set to False (default) will suffice.

Important

Users will still need to add the app to their account to be able to use any of the commands. They can do that from the bot's profile on Discord.

Important

Users will only be able to use permission commands like this one if you invite them to your server².

Editing User Permissions

You can edit an existing user's permission with the /edituser command. Its only required option is id, the user's ID. It's also got the same optional options as the /adduser command, and it's those options you're gonna use to edit permissions. You only need to use the options you wish to edit, other permissions will be unaffected.

Example:

/edituser id:315430983126210624 edit-sticker:False delete-sticker:False

Availability: Your Server Only

Tip

/edituser also supports the grant-all option.

Warning

grant-all can only grant permissions! Setting it to False when editing will not revoke permissions! If you wish to revoke a user's existing permissions, you need to explicitly set them to False here.

Deleting Users

You can delete users from the app with the /deleteuser command. Like the /edituser command, its only option is id.

Availability: Your Server Only

Important

Deleting a user from the app is the only way to keep them from being able to list/send stickers, setting all their permissions to False will still allow them to send stickers!

Note

While anyone might be able to add the bot to their account, they won't be able to use any of the commands unless you explicitly let them with /adduser.

Listing Users

You don't have to keep track of every user you add to the app. /manageusers allows you to quickly edit permissions or delete users from your app. To delete a user, click on the "Edit" button next to their name and type DELETE in the "Delete User" field.

Availability: Your Server Only

Note

Only the owner and users with permission to add, edit and delete users can use this command.

Requirements

• NodeJS v18+.
• Recent version of FFMPEG. Download and extract the full GPL version (not shared) compatible with your setup. E.g., if you're running Windows on an Intel or AMD CPU, download the win64 GPL zip file.
• If you plan on self-hosting, you'll need to be reachable. If you're not behind CGNAT all you'll need to do is forward port ASSETS_SERVER_PORT on your router (read step 5.vi. of the installation section for more). If you are, however, you'll need to use a service like Cloudflare Tunnels to work around that limitation. You can check if port forwarding worked here, just enter the value of ASSETS_SERVER_PORT in "Port Number" and click check. If you can't find a way of being reachable, users won't be able to see your stickers.

Note

If you have a dynamic IP address, you'll want to look into DDNS services like the ones offered by DuckDNS, No-IP or Cloudflare. The app will not respond to IP changes on its own.

Caution

If you don't set up a reverse proxy or use a service like Cloudflare Tunnels, your public IP will be exposed to anyone you send stickers to! This isn't necessarily a problem if you plan on sharing stickers only with people you trust.

Creating a Discord App

Before using the bot, you'll need to create a Discord App to deploy the commands to.

To do this, go to the Discord Developer Portal, sign in, click "New Application" at the top right, give your app a name, and create the app.

You can find the Application ID in the General Information tab, and the bot token in the Bot tab. You'll need these values during installation.

Setup

1. Download the latest version of the project and extract it.
2. Run npm install to install all necessary dependencies.
3. Rename the .env.example file to .env
4. Enable Developer Mode on Discord. You'll need it to be able to grab your Server ID and User IDs later.
5. Open .env in any text editor and fill out every variable marked Required:
   1. Set BOT_TOKEN and APPLICATION_ID to the values you found in the Developer Portal.
   2. Create a Discord server and copy its ID by right-clicking on it in the server list and clicking Copy Server ID¹. Paste the ID after GUILD_ID=. You may use an existing server for this².
   3. Decide where you want the sticker database, the media files themselves, and the app's logs to be saved. Set the variables in the Storage section of the .env file to the absolute paths you decide on. For example, I have mine configured like this: DB_DIR_PATH="C:/Users/Lucas/stickbot/db", ASSETS_DIR_PATH="C:/Users/Lucas/stickbot/assets", LOG_DIR_PATH="C:/Users/Lucas/stickbot/logs"³.
   4. Set the FFMPEG_PATH and FFPROBE_PATH variables to the absolute path to the ffmpeg.exe and ffprobe.exe executables that can be found in the bin folder after you extract the ffmpeg zip. For example: FFMPEG_PATH=C:\Lucas\ffmpeg\bin\ffmpeg.exe.
   5. ASSETS_SERVER_PORT is set to 4675 by default. You don't need to alter it unless that port is already in use for you.
   6. If you go the port forwarding route, set ASSETS_SERVER_HOSTNAME to http://<YOUR PUBLIC IP>:<ASSETS_SERVER_PORT>. E.g., http://41.120.142.24:4675⁴. If you plan on using a custom domain for serving the stickers, ASSETS_SERVER_HOSTNAME should be set to your domain. E.g., https://my-sticker-bot.net/

Note

Paths containing spaces need to be wrapped in double quotes (" ") both in the .env and CLI!

Adding the Bot

After installing, you'll need to add the bot to the guild you created.

Go to the Installation tab of the Developer Portal, copy the Install Link and follow it.

Choose "Add to Server", pick the server you created earlier from the list, and authorize it.

You can follow this same link again to add the bot to your account, so you can use it in DMs or other servers.

Deploying the Commands

After adding the bot to your server, you'll need to deploy the commands to Discord. To do so, run npm run deploy:prod. You may need to restart/reload Discord, and possibly wait up to an hour for the commands to become available for the first time, though it usually takes seconds. You only need to run this command once, unless instructed otherwise!

Running

Run npm run start:prod

If everything worked, you should see INFO: BOT connected in the console.

Running Commands

You'll need to run some commands to setup and start the app. If you're unfamilar with running CLI commands:

1. On Windows, open The Terminal, PowerShell, or Command Prompt from the Start Menu. On Mac, find the Terminal in the Launchpad and open it. You should know what you're doing if you're on Linux.
2. Navigate to the app's root folder with the cd command. E.g. cd "C:\Lucas\stickbot". This is where all npm commands mentioned in the instructions need to be run in.

Footnotes

1. You'll need to enable Developer Mode in Discord to do this. ↩ ↩²

2. Permission management commands (e.g. /adduser) will only be available in this guild. ↩ ↩²

3. If your paths contain spaces you'll need to wrap them in double quotes like "path/to/something"!
   You don't need to create the folders, they'll be created for you, and they don't need to share parent folders, I just did that to keep things tidy. ↩

4. To be clear, you need to use your public IP address, not your local one.
   The IP address/hostname you set ASSETS_SERVER_HOSTNAME to will be visible to whoever you send stickers to! ↩