Bot Discord: aplikacja, token, intenty i bezpieczne przechowywanie tokenu

Każdy bot Discord potrzebuje aplikacji w Discord Developer Portal oraz tokenu, którym się loguje. Pokażemy, jak założyć aplikację, które intenty włączyć, jak zaprosić bota na serwer i jak przechowywać token, aby nigdy nie wyciekł.

Tworzenie aplikacji#

1. Otwórz Discord Developer Portal (otwiera się w nowym oknie) i zaloguj się.

2. Kliknij New Application.

3. Wpisz nazwę (na przykład MujBot), zaakceptuj warunki i kliknij Create.

   Otworzy się strona General Information. Możesz tu ustawić ikonę i opis.

4. Skopiuj Application ID. Nazywa się je także Client ID i będzie potrzebne do rejestracji poleceń slash. Nie jest tajne.

Token bota#

Token to hasło bota. Każdy, kto go ma, może sterować botem: wysyłać wiadomości, usuwać kanały i banować osoby na wszystkich serwerach, na których bot się znajduje.

1. W lewym menu aplikacji kliknij Bot.
2. W sekcji Token kliknij Reset Token i potwierdź. Discord może poprosić o hasło lub kod uwierzytelniania dwuskładnikowego.
3. Skopiuj token (Copy) i od razu go zapisz (zobacz „Przechowywanie tokenu”).

Token jest wyświetlany tylko raz. Jeśli go zgubisz, wygeneruj nowy przyciskiem Reset Token. Stary token przestaje wtedy działać.

Nie pomyl tokenu z czymś innym: krótki ciąg Client Secret na stronie OAuth2 nie jest tokenem bota. Token jest dłuższy i składa się z trzech części oddzielonych kropkami.

Privileged Gateway Intents#

Intenty mówią Discordowi, które zdarzenia ma wysyłać do bota. Większość jest dostępna swobodnie, ale trzy są uprzywilejowane i trzeba je włączyć na stronie Bot w sekcji Privileged Gateway Intents:

• Włącz tylko to, czego bot potrzebuje. Intent musi być włączony w Developer Portal i zażądany w kodzie (GatewayIntentBits w discord.js).
• Jeśli kod żąda intentu, który nie jest włączony w Developer Portal, Discord zamyka połączenie, a bot zgłasza Used disallowed intents.
• Bot na 100 lub więcej serwerach musi przejść weryfikację aplikacji, a Discord musi zatwierdzić jego uprzywilejowane intenty. Gdy aplikację widzi ponad 10 000 użytkowników, Discord wymaga wniosku i przeglądu, aby dalej korzystać z uprzywilejowanych intentów, a następnie odnawiania ich co roku.

Bez Message Content Intent bot widzi treść tylko tych wiadomości, w których został wspomniany, wiadomości prywatnych z nim oraz wiadomości, które sam wysłał.

Zapraszanie bota na serwer#

1. W lewym menu aplikacji kliknij Installation.

2. W sekcji Installation Contexts zostaw zaznaczone Guild Install (instalacja na serwerze). User Install jest potrzebne tylko dla poleceń, które użytkownicy dodają do własnego konta.

3. W sekcji Install Link wybierz Discord Provided Link.

4. W sekcji Default Install Settings przy Guild Install dodaj do Scopes pozycje applications.commands i bot.

   • bot – dodaje użytkownika bota na serwer.
   • applications.commands – pozwala botowi tworzyć na serwerze polecenia slash.

5. Po dodaniu bot pojawi się Permissions. Wybierz tylko uprawnienia, których bot potrzebuje (tabela poniżej), i zapisz zmiany.

6. Skopiuj link z Install Link i otwórz go w przeglądarce.

7. Wybierz Add to server, wskaż serwer i potwierdź przyciskiem Authorize.

   Bot pojawi się na liście członków serwera (offline, dopóki go nie uruchomisz).

Link możesz też utworzyć ręcznie na stronie OAuth2 w sekcji OAuth2 URL Generator: zaznacz bot i applications.commands, wybierz uprawnienia i skopiuj wygenerowany adres.

Przechowywanie tokenu#

Token należy do pliku .env, nie do kodu. Plik .env utwórz bezpośrednio na serwerze, aby nie trzeba było nigdzie przenosić tokenu:

1. W strefie klienta otwórz bota i przejdź do zakładki Pliki, do folderu głównego /.

2. Kliknij Nowy plik i nazwij go .env (z kropką na początku, bez rozszerzenia).

3. W edytorze wpisz:

   DISCORD_TOKEN=<TOKEN_BOTA>
   CLIENT_ID=<APPLICATION_ID>
   GUILD_ID=<ID_SERWERA>

   • DISCORD_TOKEN – token bota. Zamiast <TOKEN_BOTA> wstaw token z Developer Portal, bez cudzysłowów i bez spacji wokół =.
   • CLIENT_ID – Application ID ze strony General Information.
   • GUILD_ID – ID Twojego serwera Discord (w Discordzie włącz Ustawienia użytkownika › Zaawansowane › Tryb dewelopera, a potem kliknij prawym przyciskiem nazwę serwera › Kopiuj ID serwera).

4. Zapisz skrótem Ctrl+S.

Wczytywanie .env w kodzie#

Node.js sam nie wczytuje pliku .env; trzeba mu to polecić. Ponieważ na naszych serwerach nie można zmienić polecenia startowego, wczytaj .env bezpośrednio w kodzie. Najpewniejszym sposobem jest pakiet dotenv (zainstaluj go na komputerze poleceniem npm install dotenv):

const path = require('node:path');
require('dotenv').config({ path: path.join(__dirname, '.env'), quiet: true });

const token = process.env.DISCORD_TOKEN;

• require('dotenv').config({ … }) – wczytuje zmienne z pliku do process.env. Musi być na samej górze, przed kodem, który używa tokenu.
• path: path.join(__dirname, '.env') – szuka .env w tym samym folderze co index.js, niezależnie od tego, skąd bot jest uruchamiany.
• quiet: true – nie wypisuje przy starcie komunikatu o wczytaniu pliku.
• process.env.DISCORD_TOKEN – wartość z .env. Zawsze jest to tekst (string).

W modułach ES ("type": "module" w package.json) użyj import 'dotenv/config'; w pierwszej linii.

Od Node.js 20.12 możesz obejść się bez pakietu i użyć wbudowanej funkcji process.loadEnvFile():

process.loadEnvFile(require('node:path').join(__dirname, '.env'));

Jeśli plik .env nie istnieje, funkcja zgłasza błąd. Jak sprawdzić wersję Node.js, opisujemy w sekcji Wersja Node.js. Na komputerze możesz też uruchomić bota poleceniem node --env-file=.env index.js.

Plik .gitignore#

Jeśli trzymasz kod w Git (GitHub, GitLab), utwórz w projekcie plik .gitignore:

node_modules
.env

Git nigdy nie wyśle wtedy .env ani node_modules. Jeśli .env trafił już do repozytorium przez pomyłkę, samo usunięcie nie wystarczy (zostaje w historii). Od razu zresetuj token.

Inne dane poufne#

Do .env należą też inne hasła i klucze: hasło do bazy danych, klucze API innych usług, webhooki. Obowiązują te same zasady:

• w kodzie używaj tylko process.env.NAZWA, nigdy samej wartości,
• nigdy nie wypisuj ich do konsoli (konsolę może widzieć także członek współdzielonej usługi),
• jeśli wyciekną, od razu unieważnij je w usłudze, która je wydała.

Weryfikacja#

• Po uruchomieniu bot przechodzi na Discordzie w stan online, a w Konsoli nie pojawia się An invalid token was provided.
• Aby sprawdzić, czy token się wczytał, wypisz tylko jego długość, nigdy sam token: console.log('Długość tokenu:', process.env.DISCORD_TOKEN?.length);. Jeśli wypisze undefined, plik .env nie został wczytany.

Rozwiązywanie problemów#

An invalid token was provided.#

Token jest błędny, przestał działać po Reset Token albo w ogóle się nie wczytał. Sprawdź długość tokenu (zobacz Weryfikacja), nazwę zmiennej w .env i w kodzie (DISCORD_TOKEN) oraz to, czy w .env nie ma zbędnych cudzysłowów lub spacji. Jeśli nie masz pewności, wygeneruj nowy token i wpisz go ponownie.

Used disallowed intents#

Kod żąda uprzywilejowanego intentu, który nie jest włączony w Developer Portal. Na stronie Bot w sekcji Privileged Gateway Intents włącz ten intent albo usuń go z kodu.

process.env.DISCORD_TOKEN ma wartość undefined#

• dotenv jest wczytywany dopiero po kodzie, który używa tokenu. Umieść require('dotenv').config(…) w pierwszych liniach.
• Plik w rzeczywistości nazywa się .env.txt (Windows ukrywa rozszerzenia plików). Zmień jego nazwę na serwerze na .env.
• .env leży w innym folderze niż plik główny. Użyj path.join(__dirname, '.env').

Private application cannot have a default authorization link#

Na stronie Bot wyłączono Public Bot, ale na stronie Installation ustawiono Discord Provided Link. Prywatny bot nie może mieć domyślnego linku. Albo zostaw Public Bot włączone, albo w Install Link wybierz None i utwórz link w OAuth2 URL Generator.

Bot requires a code grant#

Na stronie Bot włączono Requires OAuth2 Code Grant. Jeśli nie jest Ci wyraźnie potrzebne, wyłącz je.

Nie widzę swojego serwera na liście podczas zapraszania bota#

Nie masz na tym serwerze uprawnienia Zarządzanie serwerem. Poproś właściciela serwera albo zaproś bota na własny serwer.

Dalsza lektura#

• Discord: Getting Started (aplikacja, token, instalacja) (otwiera się w nowym oknie)
• Discord: Gateway Intents (otwiera się w nowym oknie)
• discord.js Guide: Application Setup (otwiera się w nowym oknie)
• Node.js: --env-file i process.loadEnvFile (otwiera się w nowym oknie)