Como criar seu primeiro bot do Discord (do código ao ar)

Um bot do Discord é um programa que se conecta ao Discord com um token e reage a eventos: um comando digitado, uma mensagem, a entrada de um membro. Ele não vive dentro do Discord. Roda no seu computador ou num servidor, e por isso só fica online enquanto esse processo estiver rodando.

Criar o primeiro bot tem duas partes: configurar o app no Portal de Desenvolvedores e escrever o código. Este guia cobre as duas e termina com o bot no ar, usando JavaScript com discord.js v14, a biblioteca mais usada para isso.

O que você precisa antes de começar?#

• Node.js em versão atual. O guia oficial do discord.js recomenda a versão LTS ativa do Node.js; o calendário oficial mostra qual é. Confira a sua com node --version.
• Uma conta no Discord e um servidor seu para testar. Para convidar um bot, você precisa da permissão Gerenciar Servidor nele.
• Um editor de texto e um terminal.

Como criar o app e o token no Portal?#

1. Abra o Portal de Desenvolvedores do Discord e clique em New Application. Dê um nome e confirme.
2. Na página do app, copie o Application ID (aba General Information). Esse é o seu CLIENT_ID.
3. Abra a aba Bot e clique em Reset Token. Copie o token na hora, porque ele só aparece uma vez. Se perder, gere outro.
4. Não confunda o token com o client secret, que é uma string mais curta e não serve para o bot.

O token é a senha do bot: quem o tem controla o bot. Nunca o coloque no código nem em um repositório. O artigo token do bot do Discord explica como guardá-lo e o que fazer se ele vazar.

Para o GUILD_ID, ative o Modo Desenvolvedor em Configurações do usuário, Avançado. Depois clique com o botão direito no ícone do seu servidor e escolha a opção de copiar o ID (o passo a passo está no suporte do Discord).

Como convidar o bot para o servidor?#

No Portal, abra OAuth2 e use o gerador de URL:

1. Marque os escopos bot e applications.commands.
2. Escolha as permissões que o bot precisa. Para o /ping deste guia, nenhuma é necessária.
3. Copie a URL gerada, abra no navegador e escolha o servidor de teste.

O bot aparece na lista de membros como offline. Ele só fica online quando o código estiver rodando.

Como montar o projeto?#

Crie a pasta, instale a biblioteca e habilite módulos ES no package.json:

mkdir meu-bot && cd meu-bot
npm init -y
npm pkg set type=module
npm install discord.js

Crie um arquivo .env ao lado do package.json e adicione .env ao .gitignore:

DISCORD_TOKEN=cole_o_token_aqui
CLIENT_ID=id_da_aplicacao
GUILD_ID=id_do_servidor_de_teste

O Node.js lê esse arquivo com a flag --env-file, sem pacote extra, como mostra a documentação do Node.js.

Como escrever o código do bot?#

Crie o index.js. O bot usa só o intent Guilds, suficiente para slash commands, e responde ao /ping:

import { Client, Events, GatewayIntentBits } from "discord.js";

const client = new Client({ intents: [GatewayIntentBits.Guilds] });

client.once(Events.ClientReady, (readyClient) => {
  console.log(`Online como ${readyClient.user.tag}`);
});

client.on(Events.InteractionCreate, async (interaction) => {
  if (!interaction.isChatInputCommand()) return;

  if (interaction.commandName === "ping") {
    await interaction.reply("Pong!");
  }
});

client.login(process.env.DISCORD_TOKEN);

A estrutura é a do guia oficial do discord.js: cria o cliente, avisa quando conecta, escuta interações e faz login com o token.

Como registrar e testar o slash command?#

Escrever o if do /ping não cria o comando no Discord. Você precisa enviar a definição dele à API uma vez, e de novo sempre que ela mudar. Crie o deploy-commands.js:

import { REST, Routes, SlashCommandBuilder } from "discord.js";

const commands = [
  new SlashCommandBuilder().setName("ping").setDescription("Responde com Pong!"),
].map((command) => command.toJSON());

const rest = new REST().setToken(process.env.DISCORD_TOKEN);

await rest.put(
  Routes.applicationGuildCommands(process.env.CLIENT_ID, process.env.GUILD_ID),
  { body: commands },
);
console.log(`${commands.length} comando(s) registrado(s).`);

Para testar, registre os comandos só no seu servidor. O guia do discord.js lembra que há um limite diário de criação de comandos, então não registre a cada inicialização do bot. Quando os comandos estiverem prontos, troque a rota por Routes.applicationCommands(process.env.CLIENT_ID) para valerem em todos os servidores.

Como testar o bot localmente?#

Registre o comando e ligue o bot:

node --env-file=.env deploy-commands.js
node --env-file=.env index.js

O terminal deve mostrar Online como NomeDoBot, e o bot fica online no servidor. Digite /ping e confira a resposta Pong!.

Quais erros aparecem no primeiro bot?#

• Error [TokenInvalid]: An invalid token was provided.: o token está vazio ou errado. Confirme que .env está na pasta certa, que você passou --env-file=.env e que não copiou o client secret.
• O comando não aparece no Discord: você não rodou o deploy-commands.js, ou o GUILD_ID é de outro servidor, ou o convite não teve o escopo applications.commands.
• Integration requires code grant (em guias antigos, Bot requires a code grant): desligue a opção Requires OAuth2 Code Grant na aba Bot do Portal.
• Used disallowed intents: o código pede um intent privilegiado que não está ativo na aba Bot do Portal.
• O bot cai quando você fecha o terminal: é o esperado. O processo precisa rodar numa máquina que não desliga.

Se o bot está online, mas não responde, veja bot do Discord não responde.

Como deixar o bot no ar o tempo todo?#

Seu computador serve para desenvolver, mas o bot sai do ar quando o computador desliga ou perde a internet. Há dois caminhos para manter um bot no ar 24 horas:

• VPS: você instala o Node.js, configura um supervisor como pm2 ou systemd e cuida de atualizações e firewall. O passo a passo está em como deixar um bot online 24/7.
• Plataforma de hospedagem de bots: você envia o código e define as variáveis de ambiente; o ambiente Node.js já existe.

Para estimar a memória do seu bot, veja quanta RAM um bot precisa. O processo de hospedagem completo está em como hospedar um bot discord.js.

Como fazer isso na Square Cloud#

Na Square Cloud, o bot roda num container isolado e sempre ligado, com reinício automático (ligado por padrão no deploy pelo painel) quando o processo encerra com erro. Você faz o deploy por ZIP no painel, pela CLI, pelo GitHub ou pela extensão do VS Code.

1. Compacte o projeto com index.js e package.json na raiz do ZIP, sem o .env e sem node_modules (no start, a plataforma roda npm install).
2. Envie pelo painel. O arquivo squarecloud.app é opcional: o painel o gera com o runtime, a memória e o arquivo principal, ou você pode escrevê-lo na raiz do projeto.
3. Escolha o runtime Node.js e o index.js como arquivo principal. Cada aplicação de fundo, como um bot, usa no mínimo 256 MB do pool de RAM do plano.
4. Defina DISCORD_TOKEN nas variáveis de ambiente da aplicação. A mudança vale no próximo reinício.
5. Rode o deploy-commands.js uma vez no seu computador, como antes, e acompanhe os logs em tempo real até aparecer Online como ....

Os planos são pagos: o Hobby, de R$ 12,49 por mês, inclui 1 GB de RAM e 1 vCPU. Veja os detalhes em hospedagem de bots Discord na Square Cloud.