whatsplay 2.0.0

A modern Python library for automating WhatsApp Web using Playwright

WhatsPlay 🚀

Automatización avanzada de WhatsApp Web usando Playwright y Python.
Permite interactuar con mensajes no leídos, autenticar mediante código QR y realizar acciones complejas a través de eventos personalizados y filtrado de mensajes.

---

✨ Características

• Eventos asíncronos: escucha eventos como on_start, on_auth, on_unread_chat.
• Persistencia de sesión: guarda datos de autenticación en un directorio local para no escanear el QR cada vez.
• Apertura de chat por nombre o teléfono: si no conocés el chat_name exacto, pasá el número de teléfono completo (con prefijo de país).
• Envío y recepción de mensajes (texto y multimedia).
• Filtros personalizados para procesar solo los mensajes que te interesen.
• Extracción automática de código QR para autenticación.
• Compatibilidad con servidores sin GUI gracias a Playwright en modo headless.
• Detección robusta de mensajes no leídos con múltiples heurísticas (aria-labels, badges, font-weight).
• Búsqueda mejorada con estrategias de fallback para máxima compatibilidad.
• Selectores actualizados compatibles con WhatsApp Web 2024-2025.

---

📦 Arquitectura

• Modularidad: cada componente (cliente, gestor de chats, filtros, autenticación) está separado.
• Mantenibilidad: componentes independientes y bien definidos.
• Testabilidad: cada módulo puede probarse por separado.
• Reutilización: los módulos pueden usarse en otros proyectos.

---

🛠 Instalación

Prerrequisitos

• Python 3.8 o superior

Instalación desde PyPI

pip install whatsplay

Después de instalar la librería, descargá los navegadores de Playwright con:

python -m playwright install

---

▶️ Ejemplos de uso

WhatsPlay está construido sobre asyncio, por lo que todas las operaciones son asíncronas. A continuación se muestra un ejemplo básico para iniciar sesión, escuchar eventos y enviar un mensaje.

Nota: siempre usá funciones async def como manejadores de eventos, ya que el sistema de eventos los invoca de forma asíncrona.

import asyncio
from pathlib import Path
from whatsplay import Client
from whatsplay.auth import LocalProfileAuth

async def main() -> None:
    data_dir = Path.home() / "Documents" / "whatsapp_session"
    data_dir.mkdir(parents=True, exist_ok=True)

    auth = LocalProfileAuth(data_dir)
    client = Client(auth=auth, headless=False)

    @client.event("on_start")
    async def on_start():
        print("✅ Cliente iniciado")

    @client.event("on_auth")
    async def on_auth():
        print("📸 Mostrando QR en pantalla")

    @client.event("on_unread_chat")
    async def on_unread_chat(chat_name, messages):
        # Si no conocés el nombre exacto, podés usar el número de teléfono
        await client.send_message(chat_name, "Hola, este es un mensaje automático!")

    await client.start()

if __name__ == "__main__":
    asyncio.run(main())

---

📚 Ejemplos Adicionales

La carpeta /examples incluye varios scripts de ejemplo para diferentes casos de uso:

• simple_example.py: Ejemplo básico con eventos y auto-respuesta a mensajes no leídos
• open_example.py: Cómo abrir un chat específico programáticamente
• search_example.py: Búsqueda de conversaciones con resultados detallados
• wsp.py: Herramienta CLI para envío rápido de mensajes desde terminal

Consulta la documentación completa en src/DOCUMENTACION.md para instrucciones detalladas de cada ejemplo.

---

📦 Dependencias

Principales

• playwright – Automatización de navegador

Desarrollo

• pytest – Framework de testing
• pytest-asyncio – Soporte para pruebas asíncronas
• black – Formateador de código
• flake8 – Linter
• mypy – Verificación de tipos
• requests – Uso en entornos de desarrollo y pruebas

---

🤝 Contribuciones

1. Hacé un fork del repositorio.
2. Creá una rama (git checkout -b feature/nueva-funcionalidad).
3. Commit de tus cambios (git commit -am 'Agrega nueva funcionalidad').
4. Push (git push origin feature/nueva-funcionalidad).
5. Abrí un Pull Request.

---

🗺 Roadmap

Completado ✅

• [✅] Soporte para mensajes multimedia (imágenes, videos, audios)
• [✅] Filtros para mensajes (MessageFilter)
• [✅] Detección robusta de chats no leídos
• [✅] Búsqueda mejorada con múltiples estrategias
• [✅] Selectores actualizados para WhatsApp Web 2024-2025
• [✅] Soporte para listas virtualizadas

En desarrollo 🚧

• Mejoras en detección de tipos de mensajes específicos
• API para envío de archivos multimedia
• Soporte para mensajes con reacciones

Planificado 🔮

• Integración con webhooks
• Dashboard web de monitoreo
• Soporte para múltiples cuentas simultáneas

---

❓ FAQ

¿Es seguro usar WhatsPlay? Usa la interfaz oficial de WhatsApp Web; es tan seguro como usar WhatsApp en un navegador.

¿Puede ser detectado por WhatsApp? Siempre hay riesgo al automatizar servicios web. Úsalo bajo tu responsabilidad.

¿Funciona sin GUI? Sí, gracias al modo headless de Playwright.

---

🐞 Reporte de bugs

Abrí un issue con:

• Descripción del problema
• Pasos para reproducirlo
• Versión de Python y dependencias
• Logs relevantes

---

📄 Licencia

Licencia Apache 2.0.

---

⭐ Dejá una estrella si te resultó útil
Hecho con ❤️ por Markbusking