O que é a borboletinha cinza
A borboletinha cinza é um script open-source em Python que automatiza interações via WhatsApp Web. O nome vem do ícone do projeto, que é basicamente uma borboleta cinza. A ideia principal é criar bots que respondem mensagens automaticamente, enviam arquivos em massa e monitoram grupos inteiros sem precisar de intervenção humana. O funcionamento básico depende da biblioteca PyAutoGUI combinada com Selenium WebDriver. O script controla o navegador, simula cliques, digitação e movimentação do mouse como se fosse um operador humano do outro lado da tela. É automation de interface gráfica mesmo, não é API oficial do WhatsApp.
Borboletinha cinza na prática
Para rodar o projeto, você precisa ter Python 3.10 ou superior instalado, plus Selenium e PyAutoGUI. O código-cloning a partir do repositório oficial no GitHub e executar o instalador padrão. Durante a configuração inicial, o script pede os dados de login do WhatsApp Web, mas na verdade ele faz o scan do QR code via câmera do computador mesmo. Nada de sessões pré-cadastadas ou cookies exportados. O setup funciona assim: o bot abre o WhatsApp Web em uma aba dedicada do Chrome, aguarda o login manual com o QR code, e então carrega a configuração que você definiu em um arquivo YAML. Os comandos incluem enviar mensagens para contatos específicos, responder grupos com base em palavras-chave, enviar mídia (PDFs, imagens, áudios) e agendar disparos para horários determinados.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Aqui vai algo que ninguém conta nos tutoriais: o script quebra facilmente se você redimensionar a janela do navegador ou mudar a resolução da tela durante a execução. Ele usa coordenadas absolutas de pixel para clicar nos botões, então qualquer mudança visual quebra o mapeamento. Se você estiver usando uma tela externa desconectada ou alternando entre modo tela cheia e janela, recomendo travar a resolução antes de iniciar o bot. O download oficial fica no repositório GitHub do projeto, disponível gratuitamente. Basta acessar o link do repositório e baixar o arquivo ZIP ou clonar com git clone. Não existe versão paga ou comercial licenciada.
Um problema que eu encontrei pessoalmente e demorei pra resolver: quando o bot está enviando mensagens em sequência rápida, o WhatsApp começa a flagrar comportamento automatizado depois de cerca de 50 a 80 mensagens consecutivas. A conta entra em modo de verificação temporária e para de funcionar por horas. A solução prática é implementar um delay aleatório entre 8 e 25 segundos entre cada envio, além de limitar o batch para 40 mensagens por ciclo e adicionar um intervalo de 15 minutos entre ciclos. Isso aumenta o tempo total mas mantém a conta viva. Outro detalhe técnico importante: o script suporta múltiplos perfis do WhatsApp Web porque ele cria uma instância do Chrome por perfil. Você pode rodar até três bots simultâneos sem conflito, desde que cada um use uma profile directory separada. O consumo de memória RAM sobe para cerca de 800 MB por instância quando o bot está ativo monitorando grupos.
Vantagens reais: integração simples, documentação em português, comunidade ativa no Telegram com suporte gratuito, e funciona em Windows, Linux e macOS sem modificações. Desvantagens: a dependência do Selenium significa que qualquer atualização no WhatsApp Web pode quebrar seletores CSS e parar tudo até o autor do projeto atualizar. Já vi isso acontecer pelo menos três vezes em 2024, cada vez com um downtime de dois a cinco dias. Alternativas que valem considerar são ferramentas baseadas na API oficial do WhatsApp Business, que não sofrem com bloqueios por automação, mas cobram por mensagem enviada e exigem aprovação de número empresarial. Se o uso for pessoal ou institucional pequeno, a borboletinha cinza ainda faz sentido. Se o volume for alto, migre para a API oficial antes de ter problemas com a conta.
