--- title: "Run the AudD Discord bot (deploy the official template)" description: "Deploy AudD's official open-source Discord bot: clone the Go repo, configure your Discord and AudD tokens, run it, invite it to a server, and keep it up." slug: "/resources/integrations/discord-bot" section: "integrations" keywords: [audd, discord bot, deploy, song identification, voice channel, self-host] --- # Run the AudD Discord bot (deploy the official template) AudD maintains an open-source Discord bot in Go, [AudDMusic/DiscordBot](https://github.com/AudDMusic/DiscordBot). It identifies music from replied-to files and links, from a right-click menu action, and from live voice channels. This page is the operational path: clone it, configure two tokens, run it, invite it to a server, and keep it running on a small host. This is the deploy-the-template route. If you want to *build your own* bot from scratch — to understand the audio capture, customize the commands, or write it in Node — follow [Build a Discord bot that identifies songs in voice channels](/resources/recipes/discord-bot-song-id) instead. That recipe teaches the moving parts; this page just gets the official bot live. ## What you'll deploy A single Go binary that logs into Discord as your bot user and listens for a handful of triggers. When a trigger fires, it pulls the audio (from an attached file, a linked URL, or a live voice channel), sends it to AudD's recognition API, and replies in the channel with the artist, title, and a shareable link. The moving parts are: - **The binary** — built from the repo, runs as a long-lived process. - **`config.json`** — your Discord bot token, Discord application ID, and AudD `api_token`. - **A Discord application** — created in the Developer Portal, with the right intents and an invite link to your server. - **A host** — anywhere that keeps the process up: a small VPS, a container, or your own machine for testing. The recognition call is AudD's; everything else is Discord plumbing the bot already handles for you. ## Prerequisites - An API token from [dashboard.audd.io](https://dashboard.audd.io). The first 300 requests are free. Each recognition the bot performs spends one request. - A Discord application and bot token from the [Discord Developer Portal](https://discord.com/developers/applications). - The application's **Client ID** (also called the application ID). - **Go 1.21+** installed, to build the binary — or grab a precompiled binary from the repo's GitHub Actions artifacts if you'd rather not build. - `ffmpeg` available on the host — the bot shells out to it to handle audio. - A host that can keep a process running. ## Walkthrough ### Step 1: Create the Discord application In the [Discord Developer Portal](https://discord.com/developers/applications): 1. **New Application**, give it a name. 2. Open the **Bot** tab, **Add Bot**, and copy the **token**: this is your `DiscordToken`. Keep it secret; treat it like a password. 3. Still on the Bot tab, enable the **Message Content Intent**. The bot reads the content of messages it's asked to identify, so this privileged intent is required. 4. Copy the **Application ID** (Client ID) from the **General Information** tab: this is your `DiscordAppID`. > **The Message Content Intent is required.** Without it, the bot can't read > the message you reply to and won't see attached files or links. Enable it on > the Bot tab before you invite the bot anywhere. ### Step 2: Clone and configure Clone the repo and create the config file. The bot reads a `config.json` next to the binary. ```bash git clone https://github.com/AudDMusic/DiscordBot cd DiscordBot ``` Create `config.json` with your three values: ```json { "AudDToken": "your-api-token", "DiscordToken": "your-discord-bot-token", "DiscordAppID": "your-discord-application-id" } ``` - `AudDToken` — your AudD `api_token` from the dashboard. Every recognition the bot does authenticates with this. - `DiscordToken` — the bot token from the Developer Portal's Bot tab. - `DiscordAppID` — the application's Client ID, used to register the slash commands. The repo's example config carries a few extra keys for advanced use — a server bind address and a `SECRET_CALLBACK_TOKEN` used when wiring up stream callbacks. You don't need those for the basic identify-on-demand setup; the three keys above are enough to run the bot. ### Step 3: Build and run Build the binary and start it: ```bash go build -v ./... ./discordBot ``` On a clean start the bot logs in to Discord and registers its slash commands. Leave the process running — it's a daemon, not a one-shot. If you'd rather not build, download a precompiled binary from the repo's GitHub Actions artifacts, drop your `config.json` next to it, and run the binary directly. ### Step 4: Invite the bot to a server The bot has to be a member of your server before it can respond. Build an invite URL with your **Client ID** and the permissions it needs, then open it and pick a server you manage. ```text https://discord.com/api/oauth2/authorize ?client_id=YOUR_CLIENT_ID &scope=bot+applications.commands &permissions=3145728 ``` - `scope=bot+applications.commands` — both the bot membership and the slash commands. - The bot needs **Connect** and **Speak** voice permissions to join and record voice channels, plus the ability to read and send messages in the text channels where people will summon it. Adjust the `permissions` value in the portal's OAuth2 URL generator to match what you want it to do. ### Step 5: Use it Once the bot is in your server, it responds to several triggers: - **Reply with `!song`** to a message that has an audio or video attachment, or a link — the bot identifies the music in it and replies. - **Right-click a message → Apps → "Recognize This Song"** — the menu action, the same recognition without typing a command. - **`!song @mention`** or the **`/song-vc`** slash command — the bot joins the voice channel you're in, captures a few seconds, and identifies what's playing. - **`!listen`** or the **`/listen`** slash command — the bot stays in the voice channel and keeps identifying songs as they play. - **`!here`** — prints the text channel IDs the bot can see, useful when setting up where it should post. A successful identification posts the artist, title, and a shareable link. When nothing is recognized — a clip that's mostly speech, or silence — the bot says so rather than erroring. ## Hosting it The bot is one long-running process. Anything that keeps a process up works. ### A small VPS Build (or copy a precompiled binary) onto the box, put `config.json` next to it, and run it under a process supervisor so it restarts on crash or reboot. A minimal `systemd` unit: ```ini [Unit] Description=AudD Discord bot After=network-online.target [Service] WorkingDirectory=/opt/audd-discord ExecStart=/opt/audd-discord/discordBot Restart=always RestartSec=5 [Install] WantedBy=multi-user.target ``` ```bash sudo systemctl enable --now audd-discord journalctl -u audd-discord -f # tail the logs ``` Make sure `ffmpeg` is installed on the host (`apt install ffmpeg` on Debian / Ubuntu). ### A container Build the binary in one stage and run it on a small base image that already has `ffmpeg`. Mount or bake in the `config.json`, or supply the three values however your platform injects config. Keep one replica — running two copies of the same bot token causes Discord to fight over the gateway connection. > **Run exactly one instance per bot token.** Discord allows one gateway > connection per bot. A second copy of the same `DiscordToken` causes both to > disconnect and reconnect in a loop. Scale by sharding (a Discord concept), not > by starting a second unsharded process with the same token. ### Keeping it up - **Restart on failure.** `Restart=always` (systemd) or your platform's restart policy. The bot reconnects to Discord on its own after a transient gateway drop, but a hard crash needs the supervisor to bring it back. - **Watch the logs.** The process logs login, command registration, and recognition failures. Tail them when something looks wrong. - **Watch your AudD usage.** Every identification spends one request. A busy server with `!listen` running in several voice channels adds up — check usage on the dashboard if a bill surprises you. ## When recognition fails The bot surfaces the common failure modes in-channel, but it helps to know what each one means when you're reading logs: - **No match** — the audio was recognized-against but nothing matched (mostly speech, silence, or a track not in the database). Not an error; the bot replies that it couldn't identify the song. - **Authentication failure** — a bad or missing `AudDToken`. The bot can't recognize anything; fix the token in `config.json` and restart. - **Quota / subscription limits** — you've hit a request limit on your AudD account. Recognitions start failing until the limit resets or you raise it on the dashboard. - **Discord intent missing** — if the bot can't read message content, it sees empty messages and never finds a file or link. Re-check the Message Content Intent on the Bot tab. ## Going further - **Build your own instead.** To understand the audio capture, change the commands, or write it in another language, work through [Build a Discord bot that identifies songs in voice channels](/resources/recipes/discord-bot-song-id) — it builds the same idea from scratch in Node with `@audd/sdk`. - **Identify a whole DJ set, not one track.** The standard recognition the bot does returns one song per clip. To turn a continuous mix into a full tracklist, the enterprise endpoint returns every song — see [Turn a DJ set or mix into a tracklist](/resources/recipes/dj-set-tracklist). - **Understand which endpoint does what.** See [Standard, enterprise, or streams: how to choose](/resources/concepts/standard-vs-enterprise-vs-streams). --- **Related** - [Build a Discord bot that identifies songs in voice channels](/resources/recipes/discord-bot-song-id) - [Standard, enterprise, or streams: how to choose](/resources/concepts/standard-vs-enterprise-vs-streams) - [AudDMusic/DiscordBot on GitHub](https://github.com/AudDMusic/DiscordBot) - [API reference](https://docs.audd.io)