Novo código da ravena completamente desenvolvido utilizando LLMs como Claude 3.7, 4.6 Sonnet e Gemini 2.5, 3.1 Pro. Esta versão remove o suporte para o wwebjs e foca em uma API REST com o backend em whatsmeow, tudo via docker, sem perrengues!.
RavenaBot é um bot para WhatsApp que vem sendo desenvolvido desde 2021, apenas como uma brincadeira/hobby. Começou como um bot da twitch (pra aprender um pouco da API deles com python) e depois foi integrado ao WhatsApp (pra aprender sobre nodejs) - virando um spaghetti code absurdo, aí veio a ideia de refazer todo o código do zero, mas com uma ajudinha especial dos LLM (pra ver o estado atual de criação de código assistido por IA). O foco deste bot é a utilização do mesmo em grupos, onde ele pode notificar status das lives, responder comandos com utilidades (!clima, !gpt, ..,), criar comandos personalizados do grupo (como nightbot, StreamElements, etc.).
Após muitas versões e adaptações, chegamos na versão atual - tudo concentrado em um docker compose simples de usar e escalável.
Tudo isso aqui vem pronto e você não precisa configurar nada externo (utiliza binários pré-instalados como ffmpeg, imagemagick).
- Figurinhas (Stickers): Criação e conversão de figurinhas estáticas e animadas.
- Downloaders: Baixar vídeos e áudios do YouTube, TikTok, Instagram e mais (!download)
- Jogos de Chat: Pescaria, Pinto, Slots, Anagrama
- Utilidades: Gerador de QRCodes (pixs, wifi, URL), clima, notícias, lembretes
- Gestão de Grupos: Mensagens de boas-vindas, comandos personalizados, filtros de links, imagens NSFW e mais
- Conversão de Arquivos: Áudio (MP3/Opus), Vídeo para GIF e manipulação básica de imagens.
Se você quiser estas funcionalidades no bot, terá que hospedar estes serviços você mesmo e informar a URL nas configurações.
- Inteligência Artificial: Integração com Ollama, LM Studio ou AnythingLLM (Comandos de chat, OCR e resumos). Dica: Pra pouco uso, é melhor usar uma IA grátis na nuvem como o Gemini Flash.
- Voz e Transcrição: Suporte a Whisper API (Transcrição automática) e AllTalk/XTTS (Sintetização de vozes personalizadas).
- Jogos: Stop, Tarô e outros jogos usam LLM para funcionar
Pra essas coisas, você vai precisar de cadastrar nos sites e informar sua chave de API (são grátis).
- Plataformas: Telegram e Discord (praticamente zero testes).
- IA na Nuvem: OpenAI, Google Gemini, Anthropic e Groq.
- Monitoramento e Social: Twitch (avisos de live), Last.fm, Giphy e NASA.
- Games: Riot Games (LoL/WR), Steam e PSN.
- Utilidades: IMDb e Rastreio de Correios.
- Consulta de Veículos: O comando de consulta de placas (!placa) requer uma API paga específica (apiplacas).
A stack é composta por 5 containers:
- ravena-ai: O "cérebro" do bot. Aplicação Node.js que processa a lógica, comandos, jogos e integrações - a ravena que você já conhece.
- whatsgoapi: A ponte REST API desenvolvida em Go (whatsmeow). Responsável pela conexão direta com o WhatsApp, garantindo velocidade e estabilidade sem delays.
- rembg: Serviço de inteligência artificial especializado em remoção de fundo de imagens. Utilizado pelos comandos
!removebge!stickerbgpara gerar PNGs e figurinhas transparentes de alta qualidade instantaneamente. - postgres: Banco de dados PostgreSQL utilizado para gerenciar as sessões da API e persistência de dados.
- minio: Storage de objetos (S3 compatible) para armazenamento e cache de mídias (imagens, vídeos, áudios).
- health-check: Monitora a saúde dos serviços e reinicia os containers automaticamente em caso de falha.
- Básico de Mídia - Stickers, stickers sem fundo, baixa vídeos/música do youtube, baixa gifs, imagens, converte formatos, muda volume e mais!
- Sistema modular de Comandos - Comandos fixos implementados por arquivo que todos podem ajudar a expandir + Interpretador comandos personalizados que podem ser cirados em tempo real dentro dos grupos
- Plataformas de Streaming - Monitoramento de Twitch, Kick e YouTube com notificações customizáveis dentro dos grupos
- Jogos - Roleta russa, pescaria, pokemon, geoguesser... Tudo isso no chat do grupo
- Zoeira - Comandos de zueira pra entreter os memrbos
- Interações no Grupo - Mensagens de boas vindas, despedidas, resumo de conversas, interações inteligentes
- Integração com LLMs - Código pronto pra utilizar APIs OpenRouter, Gemini, ChatGPT e locais com o LMStudio
- StableDiffusion - Gera imagens via sdwebui e envia direto no whats, rodando local sem pagar APIs
- Filtros de Mensagens - Apaga mensagens com palavras específicas, links e também detecta conteúdo 18+
- Sistema de Convites - O bot processa links de convites e possui comandos para que o administrador coloque o bot nos grupos de forma remota
- Painel de Controle Web - Possui um painel de controle web (!g-painel) para configurar as opções do grupo
- Multiplas instâncias - Múltiplos bots rodam com o mesmo código, compartilhando a base de dados
- Gerenciamento de Grupos: Ferramentas para administradores
- Sistema de Convites: Controle quem pode adicionar o bot a grupos
- Interações Automáticas: O bot pode interagir aleatoriamente com mensagens
Se você quer interagir com o bot e testar ele, eu disponibilizo o mesmo gratuitamente em alguns números, você pode conferir o status dos bots aqui neste link Telegram Bot: Também dou suporte para o Telegram (mas não muito), rodando o bot ravenosabot e o grupo da comunidade.
Se você não entende nada de programação ou nunca rodou aplicativos via código fonte, o melhor mesmo é chamar seu amigo da TI pra dar aquele help.
Requisito único: Docker e Docker Compose instalados na máquina.
git clone --recurse-submodules https://github.com/moothz/ravena-ai.git
cd ravena-aiSe tiver feito o clone sem o recurse-submodules, inicialize dentro da pasta do projeto manualmente:
git submodule update --init --recursivemake setupIsso cria o .env a partir do .env.example e preenche automaticamente GLOBAL_API_KEY, POSTGRES_PASSWORD e MINIO_SECRET_KEY com valores aleatórios seguros.
Abra o .env e preencha pelo menos:
| Variável | O que é |
|---|---|
SUPER_ADMINS |
Seu número do WhatsApp no formato [email protected] |
BOTAPI_USER / BOTAPI_PASSWORD |
Credenciais para o painel web de gerenciamento |
DL_FOLDER |
Caminho no host para armazenar downloads (YouTube, Stickers, Imagens, etc). Use uma pasta com bastante espaço, por exemplo /mnt/hd-externo/downloads |
BOT_DOMAIN |
URL pública do bot (opcional, só necessário se quiser links externos funcionando) |
O resto é opcional — configure apenas as APIs que você quiser usar (Twitch, Gemini, OpenAI, etc).
cp bots.json.example bots.jsonEdite o bots.json e adicione cada instância de bot que você quer rodar:
[
{
"enabled": true,
"nome": "meu-bot",
"managementUser": "ravuser",
"managementPW": "ravpw",
"numero": "5511999999999",
"customPrefix": "!",
"ignorePV": false,
"ignoreInvites": true
}
]💡 Dica: Editou o
bots.json?make restart-bot # ou: docker compose restart ravena-ai
Editou o
.env?make up # ou: docker compose up -d
Editou o código fonte (ex: functions)?
make ravena-ai
cp service-providers.json.example service-providers.jsonEste arquivo define as URLs das APIs self-hosted e externos (Whisper, Ollama, AllTalk, Gemini, OpenAI, etc). Se você não usa nenhuma, pode usar um vazio assim:
{
"llm": [],
"whisper": [],
"comfyui": [],
"sdwebui": [],
"alltalk": []
}[
{ "type": "whisper", "url": "http://meu-servidor:5000" },
{ "type": "alltalk", "url": "http://meu-servidor:7851" }
]Assim como o
bots.json, bastamake restart-botpara recarregar após edições.
make up-buildIsso constrói as imagens e sobe todos os serviços (ravena-ai, whatsgoapi, postgres, minio, health-check).
Acesse o painel da ravenabot para escanear o QR Code ou gerar um código de pareamento, conforme o nome do seu bot definido no bots.json
URL de exemplo:
http://localhost:5000/qrcode/meu-bot
O login e senha são os valores definidos em managementUser e managementPW no bots.josn.
# Inicialização e Configuração
make setup # Configuração inicial (gera .env e segredos)
make up-build # Build das imagens e sobe tudo
make up # Sobe os containers sem rebuild
make down # Para e remove os containers
# Gerenciamento e Update
make ravena-ai # Lint + Build + Restart (ideal para quando editar o código)
make restart-bot # Reinicia apenas o container do bot (recarrega bots.json)
make restart-api # Reinicia apenas o container da API (whatsgoapi)
make restart # Reinicia todos os serviços
# Monitoramento e Manutenção
make logs # Logs de todos os containers
make logs-bot # Logs apenas do bot
make logs-botapi # Logs apenas do whatsgoapi
make ps # Status dos containers
make update-allm # Atualiza comandos na base do AnythingLLM
make clean # Limpa containers parados e imagens órfãsConfigure as chaves no .env conforme precisar:
- Giphy — Busca de GIFs (
GIPHY_API_KEY) - OMDB — Informações de filmes (
OMDB_API_KEY) - Unsplash — Busca de imagens (
UNSPLASH_API_KEY) - Last.fm — Perfis e histórico musical (
LASTFM_APIKEY) - Riot Games — Estatísticas de LoL/WR (
RIOT_GAMES) - Twitch — Notificações de live (
TWITCH_CLIENT_ID+TWITCH_CLIENT_SECRET) - Gemini — IA na nuvem grátis (
GEMINI_API_KEY) - OpenRouter — Acesso a múltiplos LLMs (
OPENROUTER_API_KEY)
O bot possui um harness de testes que permite executar comandos dentro do container Docker sem precisar de uma conexão WhatsApp real. Ideal para desenvolvimento rápido.
# 1. Edite o código localmente
vim src/functions/MeuComando.js
# 2. Copie o arquivo alterado para o container e rode os testes
make test-quick FILE=src/functions/MeuComando.js
# 3. Para rodar apenas os testes (sem copiar arquivos)
make testEdite o arquivo run-testes.js na raiz do projeto:
const { msgTexto, msgMedia, msgComQuote, msgCustom } = require("./src/testing/helpers");
const TestRunner = require("./src/testing/TestRunner");
const GROUP_ID = "[email protected]"; // ID de um grupo real no banco
async function main() {
const runner = new TestRunner({ groupId: GROUP_ID, author: "[email protected]" });
// Mensagem de texto simples
runner.run("!ping", () => msgTexto("!ping"));
// Mensagem com mídia (carrega arquivo do disco)
runner.run("!s - imagem", () =>
msgMedia("!s", "./data/test-image.png", { type: "image" })
);
// Mensagem que responde outra (quoted)
runner.run("!resumo com quoted", async () => {
const quoted = msgTexto("Texto longo que precisa ser resumido.");
return msgComQuote("!resumo", quoted);
});
// Objeto totalmente customizado
runner.run("!help no privado", () =>
msgCustom({ content: "!help", type: "text", group: null })
);
await runner.runAll();
}
main().catch(console.error);| Helper | Descrição |
|---|---|
msgTexto(texto, opts?) |
Mensagem de texto simples |
msgMedia(legenda, arquivo, opts?) |
Mensagem com imagem/áudio/vídeo carregado do disco |
msgComQuote(texto, quoted, opts?) |
Mensagem que responde (cita) outra |
msgCustom(overrides) |
Objeto message totalmente customizado |
Coloque os arquivos na pasta data/ com estes nomes:
data/test-image.pngedata/test-image.jpgdata/test-audio.mp3data/test-video.mp4
docker compose exec ravena-ai node -e "
const DB = require('./src/utils/Database');
DB.getInstance({ disableBackup: true }).getGroups()
.then(gs => gs.forEach(g => console.log(g.name, '→', g.id)))
.catch(console.error);
"- Leituras: normais — acessa o banco de dados real do container
- Escritas: bloqueadas — nenhum dado é alterado no banco
- APIs externas: ativas — comandos como
!yt,!ia,!imgfazem requests reais - Saída do processo: automática — o runner fecha as conexões e encerra ao final
Para contribuir com o bot e adicionar um novo comando fixo, crie um arquivo .js na pasta src/functions/.
Alguns comandos que outros usuários criaram:
Aqui vai uma boa base pra começar:
const Logger = require('../utils/Logger');
const Command = require('../models/Command');
const ReturnMessage = require('../models/ReturnMessage');
const logger = new Logger('meus-comandos');
const commands = [
new Command({
name: 'exemplo',
description: 'Um comando de exemplo',
reactions: {
before: "⌛️", // Emoji mostrado antes da execução
after: "✅" // Emoji mostrado após a execução
},
method: async (bot, message, args, group) => {
const chatId = message.group || message.author;
logger.debug(`Executando comando exemplo`);
// Obtém o primeiro argumento ou usa um valor padrão
const nome = args.length > 0 ? args[0] : "mundo";
// Envia a resposta
return new ReturnMessage({
chatId: chatId,
content: `Olá, ${nome}!`
});
}
})
];
// Exporta os comandos
module.exports = { commands };Se você sabe pedir pras LLMs programarem, aqui vai uma dica de como fazer:
Anexe os seguintes arquivos:
- models/Group.js
- models/Command.js
- models/ReturnMessage.js
- Este código de exemplo acima como exemplo.js
Se estiver fazendo alguma função similar a alguma existente no bot, anexo também o arquivo JS da pasta functions - por exemplo, se for fazer um comando que retorne Stickers, anexe o Stickers.js para a IA saber como tratar ReturnMessage de stickers, etc.
Peça para o LLM:
Respeitando os padrões de implementação apresentados nos modelos e restante do projeto desenvolva um novo comando conforme instruções a seguir:
- Comando 'soletrar'
- Recebe como argumento várias palavras
- Para cada palavra recebida como argumento, separe as letras com hifen
Exemplo:
- Entrada: !soletrar batata porco
- Saída: B-A-T-A-T-A | P-O-R-C-O
Free, usem como quiserem.