Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/coah80/yoink/llms.txt

Use this file to discover all available pages before exploring further.

Yoink ships a standalone Discord bot binary that connects to your existing Yoink server. Once running, guild members can use /yoink, /convert, and /compress slash commands without ever leaving Discord. Files under 25 MB are attached directly to the reply; larger files get a temporary download link that expires in five minutes. The bot also bundles moderation, leveling, welcome messages, and reaction role systems — all backed by a local SQLite database.

​
How it works

The bot is a separate Go binary (yoink-bot) that communicates with your Yoink API over HTTP using a shared secret. When a user runs a slash command, the bot:
  1. Defers the interaction so Discord shows a “thinking…” indicator.
  2. Calls the Yoink API to start an async job.
  3. Polls the job status and updates the Discord embed with live progress.
  4. On completion, either attaches the file directly (≤ 25 MB) or posts a download link.

​
Setup

1

Create a Discord application

Go to discord.com/developers/applications and create a new application. Under Bot, click Add Bot.Copy the Bot Token and the Application ID (found on the General Information page) — you will need both.
2

Enable privileged intents

Still on the Bot settings page, scroll to Privileged Gateway Intents and enable:
  • Server Members Intent
  • Message Content Intent
These are required for the leveling system and welcome messages to function.
3

Set environment variables

Create a .env file or export variables in your shell:
DISCORD_TOKEN=your_bot_token_here
DISCORD_APP_ID=your_application_id_here
YOINK_API_URL=https://yoink.example.com
YOINK_PUBLIC_URL=https://yoink.example.com
BOT_SECRET=a_long_random_shared_secret
BOT_SECRET must match the BOT_SECRET environment variable set on your Yoink server. Requests without the correct secret are rejected by the API.
4

Build the bot binary

From the root of the Yoink repository:
make bot
This produces ./yoink-bot in the project root.
5

Run the bot

./yoink-bot
On startup the bot registers all slash commands globally and logs each one:
Bot logged in as YoinkBot#1234
Registered command: /yoink
Registered command: /convert
Registered command: /compress
...
6

Invite the bot to your server

Go to OAuth2 → URL Generator in the developer portal. Select the bot and applications.commands scopes, then grant at minimum:
  • Read Messages / View Channels
  • Send Messages
  • Attach Files
  • Embed Links
  • Manage Roles (for reaction roles and auto-role)
  • Kick Members / Ban Members (for moderation commands)
  • Moderate Members (for timeout command)
Copy the generated URL and open it in your browser to add the bot to your server.

​
Environment variables reference

VariableRequiredDefaultDescription
DISCORD_TOKEN✅—Discord bot token
DISCORD_APP_ID✅—Discord application ID
YOINK_API_URL—http://localhost:3003Internal URL of your Yoink server
YOINK_PUBLIC_URL—Same as YOINK_API_URLPublic-facing URL used in download links
BOT_SECRET✅—Shared secret matching the server’s BOT_SECRET

​
Slash commands

​
/yoink

Downloads media from any URL supported by Yoink and delivers it in the channel. 
/yoink url:<url> [format:<format>] [resume_from:<n>]
OptionDescription
urlThe media URL to download (required)
formatOutput format: mp4 (default), mp3, gif, compressed
resume_fromFor playlists, start downloading from this video number (min: 1)
Delivery behaviour:

File ≤ 25 MB

The file is downloaded to the bot and attached directly to the Discord message — no links needed.

File > 25 MB

The bot posts a temporary download link using your YOINK_PUBLIC_URL. The link expires in 5 minutes.

Auto-compress

If the downloaded file exceeds 25 MB, the bot automatically triggers compression targeting 24 MB before responding. If compression also fails, it falls back to a download link.

Playlists

Playlist downloads are zipped on the server. The bot posts a ZIP download link (expires in 5 minutes) along with the video count and any failures.

​
/convert

Converts an attached Discord file to a different format. 
/convert file:<attachment> format:<format>
OptionDescription
fileA file attached to the slash command (required)
formatTarget format: mp4, webm, mkv, mov, mp3, m4a, opus, wav, flac (required)
The converted file follows the same ≤ 25 MB / link fallback logic as /yoink.

​
/compress

Compresses a video to fit within a target file size. 
/compress file:<attachment> [target_mb:<n>] [preset:<preset>]
OptionDescription
fileA video file attached to the slash command (required)
target_mbTarget size in megabytes (1–500, default: 25)
presetfast, balanced (default), or quality
Use preset:balanced for the best trade-off between speed and quality. Choose preset:quality when file size is less important than visual fidelity.

​
Additional bot features

Beyond media commands, yoink-bot includes a full-featured guild management suite:
Commands: /ban, /kick, /timeout, /warn, /history, /modlog, /note, /purge, /lock, /unlockAll moderation actions are logged to a configurable mod-log channel. Run /setup to configure it interactively.
Members earn XP by sending messages. Commands: /level, /leaderboard, /setlevel, /xpsettingsLevel roles (Newcomer → Regular → Active → Veteran → Legend) can be created automatically by the /setup wizard.
Sends a customizable welcome message when a new member joins. Configure the channel and message text via /welcome or the /setup wizard.
Assign roles to members automatically when they react to a specific message. Managed with /reactionrole.
Run /setup (admin only) for a guided, step-by-step configuration flow covering mod log channel, welcome channel, auto-role, and level roles — with options to select existing channels/roles or have the bot create them for you.

​
Discord gateway intents

The bot requests the following privileged and non-privileged intents:
IntentPurpose
GuildsCore guild and channel information
GuildMessagesReceive messages for XP tracking
MessageContentRead message text for XP and moderation
GuildMembersWelcome messages and auto-role on member join
GuildMessageReactionsReaction role add/remove events

Build docs developers (and LLMs) love

Get started for freeTalk to us