falafy
PT
Baixar grátis

API pública v1

Seu primeiro bot em 5 minutos

Do zero ao /ping respondendo “pong” só para você, em Node puro e com uma única dependência: o pacote ws.

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. E o SDK?

O SDK oficial em TypeScript (@falafy/bot) ainda não foi publicado no npm. Até lá, use o exemplo acima, que só depende do ws. Quando sair, ele vai cuidar do heartbeat, da reconexão com RESUME, dos limites de taxa e das respostas.

Um exemplo completo com botão “Rolar de novo”, ideias prontas e um prompt para criar o bot com IA ficam em Bots 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.