wrapper-vjwhats 0.0.6

Wrapper for vjwhats library to send messages and sent messages

📱 Wrapper VJWhats

Uma biblioteca Python poderosa para automação do WhatsApp Web via Selenium

Desenvolvida por Renan Rodrigues Utilizada principalmente pela VJ Bots para soluções de automação

Instalação • Uso Rápido • Documentação • Exemplos

---

✨ Funcionalidades

• 🔍 Buscar contatos - Localizar e abrir conversas por nome de usuário ou número
• 💬 Enviar mensagens - Envio programático de mensagens de texto
• 📎 Compartilhar arquivos - Suporte a imagens, vídeos e documentos
• 📥 Baixar imagens - Download automático de imagens enviadas no dia
• 📱 Iniciar conversas - Abrir chat com números não salvos
• 🗑️ Limpar conversas - Apagar todo histórico de mensagens de um contato
• 🔄 Sessão persistente - Manter login usando perfis do Chrome
• 📊 Logging completo - Sistema de logs detalhado para debugging

📋 Requisitos

• Python 3.13 ou superior
• Google Chrome instalado
• ChromeDriver compatível com sua versão do Chrome

🚀 Instalação

Via Git (Desenvolvimento)

# Clone o repositório
git clone https://github.com/Renan-RodriguesDEV/wrapper-vjwhats.git
cd wrapper-vjwhats

# Instale as dependências
pip install -r requirements.txt

# Ou instale em modo desenvolvimento
pip install -e .

Via pip (Futuro)

pip install wrapper-vjwhats

🎯 Uso Rápido

from wrapper_vjwhats import WhatsApp
from selenium import webdriver
from selenium.webdriver.chrome.options import Options

# Configurar Chrome com perfil existente (para manter sessão do WhatsApp)
chrome_options = Options()
chrome_options.add_argument("user-data-dir=C:/Users/SEU_USUARIO/AppData/Local/Google/Chrome/User Data")
chrome_options.add_argument("profile-directory=Default")

# Inicializar WebDriver
driver = webdriver.Chrome(options=chrome_options)

# Criar instância do WhatsApp
wpp = WhatsApp(browser=driver, time_out=300)

# Enviar mensagem
wpp.find_by_username("João Silva")
wpp.send_message("Olá! Esta é uma mensagem automática.")

# Enviar arquivo
wpp.send_file("./documento.pdf", which=1)

# Fechar quando terminar
# driver.quit()

📚 Documentação da API

Classe WhatsApp

Inicialização

WhatsApp(browser: WebDriver = None, time_out: int = 300)

Parâmetros:

• browser: Instância do Selenium WebDriver
• time_out: Tempo limite em segundos para operações de espera (padrão: 300)

---

🔧 Métodos Principais

find_by_username(username: str) -> bool

Localiza e abre uma conversa com um contato específico.

Parâmetros:

• username: Nome do contato ou número de telefone

Retorna: True se o contato foi encontrado, False caso contrário

Exemplo:

if wpp.find_by_username("Maria Santos"):
    print("Conversa aberta com sucesso!")

---

send_message(message: str) -> str

Envia uma mensagem de texto para o chat atual.

Parâmetros:

• message: Texto da mensagem a ser enviada

Retorna: Código de status:

• "1": Mensagem enviada com sucesso
• "3": Erro ao enviar
• "4": Contato não encontrado

Exemplo:

status = wpp.send_message("Olá, tudo bem?")
if status == "1":
    print("Mensagem enviada!")

---

send_file(attachment: str, which: int) -> int

Envia um arquivo no chat atual.

Parâmetros:

• attachment: Caminho do arquivo (string)
• which: Tipo de arquivo
  • 1: Documento (PDF, TXT, DOCX, etc.)
  • 2: Imagem ou vídeo (JPG, PNG, MP4, etc.)

Retorna:

• 1: Arquivo enviado com sucesso
• -1: Erro ao enviar
• 0: Operação não concluída

Exemplo:

# Enviar documento
wpp.send_file("./relatorio.pdf", which=1)

# Enviar imagem
wpp.send_file("./foto.jpg", which=2)

---

start_conversation(mobile: str) -> bool

Inicia uma nova conversa com um número de telefone (mesmo não salvo).

Parâmetros:

• mobile: Número completo com código do país (ex: [phone])

Retorna: True se a conversa foi iniciada, False caso contrário

Timeout: 30 segundos

Exemplo:

if wpp.start_conversation("[phone]"):
    wpp.send_message("Olá, esta é uma mensagem automática!")

---

get_images_sent(limit_images: int = 0) -> int

Baixa imagens enviadas hoje no chat atual.

Parâmetros:

• limit_images: Número máximo de imagens para baixar (0 = sem limite)

Retorna: Número de imagens baixadas

Exemplo:

# Baixar até 10 imagens
num_images = wpp.get_images_sent(limit_images=10)
print(f"{num_images} imagens baixadas")

---

clear_messages(contact: str)

Limpa todo o histórico de mensagens de um contato.

Parâmetros:

• contact: Nome do contato

Exemplo:

wpp.clear_messages("Grupo Teste")

---

clear_search_box()

Limpa o campo de busca de contatos.

Exemplo:

wpp.clear_search_box()

---

💡 Exemplos Práticos

Envio em Massa

contatos = ["João", "Maria", "Pedro"]
mensagem = "Feliz Natal! 🎄"

for contato in contatos:
    if wpp.find_by_username(contato):
        wpp.send_message(mensagem)
        print(f"Mensagem enviada para {contato}")

Enviar Documento com Verificação

arquivo = "./relatorio_mensal.pdf"

if arquivo.exists():
    wpp.find_by_username("Gerente")
    resultado = wpp.send_file(arquivo, which=1)

    if resultado == 1:
        print("Relatório enviado com sucesso!")
    else:
        print("Erro ao enviar relatório")

Backup de Imagens

# Abrir conversa e baixar todas as imagens de hoje
wpp.find_by_username("Trabalho - Fotos")
total = wpp.get_images_sent()
print(f"Backup concluído: {total} imagens salvas")

Limpar Conversas Antigas

conversas_antigas = ["Grupo Temporário", "Chat Teste"]

for conversa in conversas_antigas:
    wpp.clear_messages(conversa)
    print(f"Conversa '{conversa}' limpa")

🔒 Melhores Práticas

1. Manter Sessão Ativa

# Use sempre um perfil do Chrome para evitar escanear QR code a cada execução
chrome_options = Options()
chrome_options.add_argument("user-data-dir=C:/Users/SEU_USUARIO/AppData/Local/Google/Chrome/User Data")
chrome_options.add_argument("profile-directory=Default")

2. Tratamento de Erros

try:
    wpp.find_by_username("Contato")
    wpp.send_message("Mensagem")
except Exception as e:
    print(f"Erro: {e}")

3. Aguardar Carregamento

import time

# Dê tempo para o WhatsApp Web carregar completamente antes de interagir
time.sleep(5)

4. Fechar Adequadamente

# Sempre feche o driver ao finalizar
try:
    # ... suas operações ...
finally:
    driver.quit()

📝 Logs

A biblioteca gera logs automáticos em logs/whatsapp_[PID]_[DATA].log com informações detalhadas sobre todas as operações.

Exemplo de log:

2025-12-24 10:30:15 - whatsapp -- [INFO] >> Successfully fetched chat "João Silva"
2025-12-24 10:30:17 - whatsapp -- [INFO] >> 1
2025-12-24 10:30:20 - whatsapp -- [INFO] >> Attachment has been successfully sent to João Silva

🤝 Contribuindo

Contribuições são bem-vindas! Siga estes passos:

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abra um Pull Request

⚠️ Avisos Importantes

• Esta biblioteca interage com o WhatsApp Web, que pode ter seus seletores alterados pelo WhatsApp a qualquer momento
• O uso de automação pode violar os Termos de Serviço do WhatsApp
• Use com responsabilidade e em conformidade com as políticas do WhatsApp
• Recomendado para uso pessoal e educacional

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

👨‍💻 Autor

Renan Rodrigues

• GitHub: @Renan-RodriguesDEV
• Email: [e-mail]

🔗 Links Úteis

• Documentação do Selenium
• WhatsApp Web
• Repositório do Projeto

---

Se este projeto foi útil para você, considere dar uma ⭐ no repositório!

Desenvolvido com ❤️ por Renan Rodrigues