Bot de comandos para grupo de WhatsApp (!menu, !regras) com a API não oficial

Um bot de comandos para grupo de WhatsApp é um webhook que lê cada mensagem do grupo, reconhece textos que começam com um prefixo — !menu, !regras, !horario — e responde no próprio grupo enviando para o id [email protected]. Com a API não oficial da WAME isso é possível porque a instância participa do grupo como um aparelho comum: vê as mensagens, responde, cita e, se for administradora, modera.

O guia de automação de grupos cobre a parte administrativa — criar grupo, aprovar entrada, restringir quem posta. Aqui o foco é outro: o bot conversando com os membros. Parser de comandos, boas-vindas, resposta quando é mencionado e, principalmente, como não transformar o grupo num lugar insuportável.

Por que só a API não oficial faz isso

A Cloud API oficial da Meta trabalha com conversas individuais e com um modelo de grupos muito mais limitado. Um bot que vive dentro de um grupo comum de WhatsApp — o grupo da turma, da comunidade de clientes, do condomínio — depende da conexão como aparelho, que é o que a API não oficial oferece. Você conecta o número por QR Code ou código de pareamento, adiciona esse número ao grupo e pronto: o bot está lá.

A estrutura do bot

Todo bot de comandos tem as mesmas peças:

1. Receber a mensagem pelo webhook.
2. Filtrar: só mensagens de grupo, só texto, nunca as do próprio bot.
3. Interpretar: o texto começa com o prefixo? Qual comando? Quais argumentos?
4. Controlar ritmo: esse usuário já pediu isso agora? O grupo está recebendo resposta demais?
5. Responder, de preferência citando a mensagem original.

Receber e filtrar

O webhook no formato meta entrega a mensagem no envelope padrão. O from, o id e o text.body você já conhece do chatbot com OpenAI. Em grupo, o envelope segue a Cloud API: from é quem enviou dentro do grupo e o grupo vem em group_id (o JID terminado em @g.us). Em conversa individual, group_id simplesmente não aparece. Isolamos essa leitura numa função:

function extrair(body) {
  const msg = body?.entry?.[0]?.changes?.[0]?.value?.messages?.[0];
  if (!msg || msg.type !== 'text') return null;

  const grupo = msg.group_id;        // ex.: "[email protected]" — só existe em grupo
  const autor = msg.from;            // em grupo, from é quem mandou
  if (!grupo) return null;           // este bot só atua em grupos

  return { grupo, autor, id: msg.id, texto: msg.text.body.trim() };
}

Duas guardas que evitam dor de cabeça:

• Ignore as mensagens enviadas pelo próprio número. Se o seu webhook de mensagens enviadas estiver ativo, o bot pode ler a própria resposta e entrar em loop.
• Ignore o que não é texto. Figurinha, áudio e foto não são comando.

O parser de comandos

Um dicionário de comandos mantém o código organizado e facilita adicionar novos:

const PREFIXO = '!';

const comandos = {
  menu: () =>
    '*Comandos disponíveis*\n' +
    '!regras — regras do grupo\n' +
    '!horario — horário de atendimento\n' +
    '!link — link de convite\n' +
    '!suporte — falar com a equipe no privado',

  regras: () =>
    '*Regras do grupo*\n' +
    '1. Sem divulgação de outros produtos\n' +
    '2. Dúvidas técnicas, sempre com print\n' +
    '3. Respeito acima de tudo',

  horario: () => 'Atendemos de segunda a sexta, das 9h às 18h.',

  link: async ({ grupo }) => {
    const r = await fetch(`${BASE}/groups/${encodeURIComponent(grupo)}/invite`);
    const dados = await r.json();
    return `Convite do grupo: ${JSON.stringify(dados)}`; // formate conforme a resposta em /docs
  },
};

function interpretar(texto) {
  if (!texto.startsWith(PREFIXO)) return null;
  const [nome, ...args] = texto.slice(PREFIXO.length).split(/\s+/);
  return { nome: nome.toLowerCase(), args };
}

Comando desconhecido não recebe resposta. Parece contraintuitivo, mas responder "comando inválido" a cada ! digitado por engano é exatamente o tipo de ruído que faz os membros silenciarem o grupo.

Responder citando a mensagem

Em grupo, responder "solto" confunde: com cinco pessoas usando o bot ao mesmo tempo, ninguém sabe qual resposta é de quem. A resposta citada resolve — POST /{key}/message/{id}/text, com o id da mensagem recebida e o to apontando para o grupo:

curl -X POST "https://us.api-wa.me/SUA_KEY/message/ID_DA_MENSAGEM/text" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "[email protected]",
    "text": "Atendemos de segunda a sexta, das 9h às 18h."
  }'

Mais sobre esse recurso em como responder mensagem citada pela API.

Anti-flood: o que separa bot útil de bot irritante

Esta é a parte que a maioria dos tutoriais pula. Um grupo com 200 pessoas e um bot sem freio vira um spam de !menu em minutos. Três controles simples:

const ultimoUso = new Map();     // `${grupo}:${autor}` -> timestamp
const respostasGrupo = new Map(); // grupo -> [timestamps]

const COOLDOWN_USUARIO = 30_000; // 30s por pessoa
const MAX_POR_MINUTO = 6;        // respostas do bot por grupo por minuto

function podeResponder({ grupo, autor }) {
  const agora = Date.now();

  const chave = `${grupo}:${autor}`;
  if (agora - (ultimoUso.get(chave) ?? 0) < COOLDOWN_USUARIO) return false;

  const recentes = (respostasGrupo.get(grupo) ?? []).filter((t) => agora - t < 60_000);
  if (recentes.length >= MAX_POR_MINUTO) return false;

  ultimoUso.set(chave, agora);
  respostasGrupo.set(grupo, [...recentes, agora]);
  return true;
}

• Cooldown por usuário: a mesma pessoa não dispara o bot várias vezes seguidas.
• Teto por grupo: mesmo com muita gente pedindo, o bot não domina a conversa.
• Silêncio quando estoura: não responda "aguarde 30 segundos" — isso também é mensagem.

Os valores são pontos de partida; ajuste ao tamanho e ao ritmo do grupo. Em produção, guarde esses contadores no Redis se houver mais de um processo.

Juntando tudo

import express from 'express';
const BASE = 'https://us.api-wa.me/SUA_KEY';
const app = express();
app.use(express.json());

app.post('/webhook/wame', async (req, res) => {
  res.sendStatus(200);

  const msg = extrair(req.body);
  if (!msg) return;

  const cmd = interpretar(msg.texto);
  if (!cmd || !comandos[cmd.nome]) return;
  if (!podeResponder(msg)) return;

  const resposta = await comandos[cmd.nome]({ ...msg, args: cmd.args });

  await fetch(`${BASE}/message/${encodeURIComponent(msg.id)}/text`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ to: msg.grupo, text: resposta }),
  });
});

app.listen(3000);

Boas-vindas sem poluir o grupo

Quando alguém entra, o webhook recebe o evento de participante do grupo. A tentação é mandar um "Bem-vindo, fulano!" no grupo a cada entrada — e num grupo que recebe 30 pessoas por dia, isso vira metade do histórico.

Duas alternativas melhores:

• Boas-vindas no privado: uma mensagem direta para quem entrou, com as regras e o !menu. O grupo continua limpo.
• Boas-vindas agrupadas: acumule as entradas e mande uma única mensagem a cada algumas horas: "Bem-vindos aos 12 novos membros de hoje! Digitem !regras".

Responder quando mencionado

Muitos membros não lembram dos comandos, mas marcam o bot: "@Bot qual o horário?". Tratar a menção como um !menu implícito ajuda. O evento de mensagem informa os números mencionados (veja o campo na documentação); se o número do bot estiver entre eles, responda com o menu citando a mensagem. Com o mesmo anti-flood, claro.

Comandos de moderação (só para admins)

Se o número do bot for administrador, dá para criar comandos restritos, como !fechar (só admins postam) e !abrir:

# Somente admins enviam mensagens
curl -X PATCH "https://us.api-wa.me/SUA_KEY/groups/ID_DO_GRUPO?setting=announcement"

# Todos voltam a poder enviar
curl -X PATCH "https://us.api-wa.me/SUA_KEY/groups/ID_DO_GRUPO?setting=not_announcement"

Confira no seu banco se o autor do comando é um dos administradores antes de executar. Não confie no texto: qualquer membro pode digitar !fechar.

Bot em grupo e risco de bloqueio

Um bot que responde quando é chamado, dentro de grupos onde foi adicionado de propósito, é uso legítimo — e é o tipo de uso em que a taxa de bloqueio da API não oficial fica muito baixa. A WAME ajuda por trás: cada instância tem identidade de dispositivo própria e coerente com o país do número, o envio segue um ritmo humano e há limites de volume e de destinatários novos.

O que gera problema é outra coisa: usar o número para entrar em grupos de terceiros e divulgar, ou responder a cada mensagem do grupo. Isso é spam, e a WAME não apoia. Vale lembrar também que a camada não oficial não é afiliada nem endossada pelo WhatsApp ou pela Meta, e o uso é de responsabilidade de quem opera o número.

Se o seu grupo cresceu e virou comunidade, veja como criar e gerenciar uma comunidade pela API. E se o grupo é um produto pago, o guia do grupo VIP com entrada e saída automáticas mostra como ligar o acesso ao pagamento.

Conclusão

Um bot de comandos para grupo é um parser, um dicionário de respostas e — o mais importante — um freio. Com a API não oficial da WAME você recebe as mensagens do grupo no webhook, responde citando com POST /{key}/message/{id}/text e, se o número for admin, modera com PATCH /{key}/groups/{id}. O resto é disciplina: responder só a comandos conhecidos, com cooldown por pessoa, teto por grupo e boas-vindas que não poluem. Assim o bot vira ferramenta que os membros usam, não barulho que eles silenciam. Todos os endpoints estão na documentação.