Seu primeiro bot em 5 minutos

1. Crie a aplicação

1. No app, abra Configurações > Desenvolvedor (no navegador: falafy.com.br/app/dev).
2. Dê um nome e clique em Criar aplicação.
3. Copie o token do bot e o segredo do cliente: eles aparecem só agora.

2. Adicione o bot a um servidor

Em Link de instalação, marque os escopos bot e applications.commands e as permissões (por exemplo Ver canais e Enviar mensagens). Abra o link, escolha um servidor que você gerencia e autorize. O bot entra com um cargo próprio que tem só as permissões escolhidas (nunca Administrador).

3. Rode o bot (Node puro)

Precisa do Node 22 ou mais novo e do pacote ws. Salve como hello.mjs e rode FALAFY_TOKEN=... node hello.mjs.

// hello.mjs — Node 22+, sem SDK: npm i ws
import WebSocket from 'ws';

const TOKEN = process.env.FALAFY_TOKEN; // "Configurações > Desenvolvedor"
const API = 'https://falafy.com.br/api/v1';
const headers = { authorization: `Bot ${TOKEN}`, 'content-type': 'application/json' };
const api = (method, path, body) =>
  fetch(API + path, { method, headers, body: body && JSON.stringify(body) }).then((r) => (r.status === 204 ? null : r.json()));

const me = await api('GET', '/users/@me');
await api('PUT', `/applications/${me.id}/commands`, [{ name: 'ping', description: 'Responde pong' }]);

const { url } = await api('GET', '/gateway/bot');
const ws = new WebSocket(url);
ws.on('open', () => {
  ws.send(JSON.stringify({ op: 'IDENTIFY', token: `Bot ${TOKEN}`, intents: 1 | 512 })); // SERVERS | SERVER_MESSAGES
  setInterval(() => ws.send(JSON.stringify({ op: 'PING' })), 30_000);
});
ws.on('message', async (raw) => {
  const f = JSON.parse(raw);
  if (f.op === 'READY') console.log('online como', f.d.user.displayName);
  if (f.op === 'EVENT' && f.event.t === 'INTERACTION_CREATE') {
    const i = f.event.d;
    if (i.data?.name === 'ping') {
      // 64 = EPHEMERAL: só quem usou o comando vê
      await fetch(`${API}/interactions/${i.id}/${i.token}/callback`, {
        method: 'POST',
        headers: { 'content-type': 'application/json' },
        body: JSON.stringify({ type: 4, data: { content: 'pong', flags: 64 } }),
      });
    }
  }
});

No servidor, digite /ping: a resposta “pong” aparece só para você, marcada como mensagem efêmera.

4. O mesmo com o SDK

O SDK oficial cuida do heartbeat, da reconexão com RESUME, dos limites de taxa e das respostas.

// npm i @falafy/bot ws
import { Client, Intents } from '@falafy/bot';

const bot = new Client({ token: process.env.FALAFY_TOKEN, intents: Intents.SERVERS | Intents.SERVER_MESSAGES });
bot.command('ping', (i) => i.reply({ content: 'pong', ephemeral: true }));
await bot.login();
await bot.registerCommands([{ name: 'ping', description: 'Responde pong' }]);

Um exemplo completo, com embed e botão “Rolar de novo”, fica em examples/hello-bot no repositório do Falafy.

Próximos passos

• Registre comandos só em um servidor durante os testes (valem na hora): veja Interações.
• Quer ler o texto das mensagens? Ative a intent MESSAGE_CONTENT no portal: veja Gateway e intents.