Your first bot in 5 minutes

1. Create the application

1. In the app, open Settings > Developer (in a browser: falafy.com.br/app/dev).
2. Pick a name and click Create application.
3. Copy the bot token and the client secret: they are shown only now.

2. Add the bot to a server

Under Install link, tick the bot and applications.commands scopes and the permissions (for example View channels and Send messages). Open the link, choose a server you manage and authorize. The bot joins with its own role holding only the chosen permissions (never Administrator).

3. Run the bot (plain Node)

You need Node 22 or newer and the ws package. Save as hello.mjs and run 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 } }),
      });
    }
  }
});

In the server, type /ping: the “pong” reply shows up only for you, marked as an ephemeral message.

4. The same with the SDK

The official SDK handles heartbeats, reconnecting with RESUME, rate limits and replies.

// 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' }]);

A complete example, with an embed and a “Roll again” button, lives in examples/hello-bot in the Falafy repository.

Next steps

• Register commands in a single server while testing (they apply instantly): see Interactions.
• Need message text? Turn on the MESSAGE_CONTENT intent in the portal: see Gateway and intents.