WhatsNET 1.0.2

WhatsNET 🚀

GITHUB: https://github.com/paps2847a/WhatsNET

WhatsNET es una potente librería para C# y .NET que permite interactuar con la API de WhatsApp Web de forma programática. Utiliza PuppeteerSharp para controlar una instancia oculta del navegador Chromium, lo que la hace sumamente flexible y capaz de realizar casi cualquier acción que un usuario humano podría hacer en la interfaz web de WhatsApp.

Inspirada en librerías populares de Node.js, WhatsNET trae todo el poder de la automatización de WhatsApp al ecosistema de .NET, con una arquitectura orientada a eventos, tipado estático fuerte y un diseño asíncrono moderno.

📖 Índice

1. Características Principales
2. Instalación
3. Uso Básico y Configuración
4. Estrategias de Autenticación
5. Manejo de Eventos
6. Envío de Mensajes y Medios
7. Grupos, Canales y Búsqueda
8. Utilidades: Encuestas, Reacciones y Formateo
9. Cierre Seguro del Cliente

✨ Características Principales

• API Fluida (Builder): Configuración intuitiva y encadenable para instanciar el cliente.
• Múltiples estrategias de autenticación: Permite guardar la sesión localmente para evitar escanear el código QR cada vez.
• Soporte completo de Mensajería: Envío de texto, imágenes, videos, audios, documentos, contactos, ubicaciones y encuestas.
• Gestión de Grupos y Canales: Creación de grupos, administración de participantes, búsqueda de canales.
• Arquitectura Orientada a Eventos: Cientos de eventos mapeados nativamente a eventos de C# (QrReceived, MessageCreated, IncomingCall, etc.).
• Gestión Integrada de Medios: Descarga automática de FFMPEG para compresión de videos/audios.
• Tipado Estricto: Clases fuertemente tipadas (Message, Chat, GroupChat, Contact, Channel) para evitar errores en tiempo de ejecución.

📦 Instalación

Asegúrate de incluir la librería en tu proyecto de .NET. (Si está disponible en NuGet, puedes instalarla vía CLI):

dotnet add package WhatsNET

Nota: La librería utiliza PuppeteerSharp, el cual descargará automáticamente una versión de Chromium compatible la primera vez que se ejecute (si se configura para hacerlo).

🚀 Uso Básico y Configuración

WhatsNET proporciona un Builder Fluido (WhatsAppClientBuilder) para configurar el cliente de forma sencilla.

using System;
using System.Threading.Tasks;
using WhatsNET;

class Program
{
    static async Task Main(string[] args)
    {
        // 1. Configurar y crear el cliente
        var client = WhatsAppClient.Create()
            .WithLocalAuth()                   // Guarda la sesión localmente
            .BrowserDownload(true)             // Descarga Chromium si no existe
            .WithAuthTimeout(120_000)          // Tiempo de espera para escanear el QR (2 mins)
            .WithoutWebVersionCache()          // Usa siempre la última versión de WhatsApp Web
            .HistoricalMessages(false)         // Ignora mensajes antiguos al conectar
            .WithBrowserArgs("--no-sandbox")   // Argumentos adicionales para el navegador
            .Build();

        // 2. Escuchar el evento del Código QR
        client.QrReceived += (sender, e) =>
        {
            Console.WriteLine("Por favor, escanea el siguiente código QR:");
            // Utilidad para imprimir el QR en consola (small, medium, big)
            Console.WriteLine(WhatsNET.Util.WWebUtil.GenerateQrCodeAscii(e.QrCode, "medium"));
        };

        // 3. Escuchar cuando el cliente esté listo
        client.Ready += (sender, e) =>
        {
            Console.WriteLine("¡El cliente de WhatsApp está listo para usarse!");
        };

        // 4. Iniciar el cliente de forma asíncrona
        await client.InitializeAsync();

        // Mantener la aplicación corriendo
        await client.WaitForExitAsync();
    }
}

🔐 Estrategias de Autenticación

Por defecto, si no configuras una estrategia, se usará NoAuth (tendrás que escanear el QR en cada reinicio).

LocalAuth (Recomendado)

Guarda la sesión (cookies, tokens) en una carpeta local. La próxima vez que inicies la app, no será necesario escanear el QR.

var client = WhatsAppClient.Create()
    .WithLocalAuth("./mi_sesion") // Opcional: Especificar la ruta de la carpeta
    .Build();

📡 Manejo de Eventos

La librería expone eventos clásicos de C# para reaccionar a cualquier actividad en tu cuenta de WhatsApp.

Eventos de Mensajería

• MessageCreated: Se dispara cuando se crea un mensaje (incluye tus propios mensajes).
• MessageReceived: Se dispara solo cuando recibes un mensaje de otro usuario.
• MessageAcked: Se dispara cuando cambia el estado de lectura de un mensaje (Enviado, Entregado, Leído).
• MessageReaction: Se dispara cuando alguien reacciona a un mensaje.

client.MessageCreated += async (sender, e) =>
{
    var msg = e.Message;
    Console.WriteLine($"Mensaje recibido de {msg.From}: {msg.Body}");

    // Respuesta simple a un comando
    if (msg.Body == "!ping")
    {
        await client.SendMessageAsync(msg.From, "pong");
    }

    // Responder citando el mensaje original
    if (msg.Body == "!hola")
    {
        await msg.ReplyAsync("¡Hola! ¿Cómo estás?");
    }
};

Eventos de Llamadas

La API de WhatsApp Web no permite contestar llamadas, pero sí puedes detectarlas y rechazarlas automáticamente.

client.IncomingCall += async (sender, e) =>
{
    var call = e.Call;
    Console.WriteLine($"Llamada entrante de {call.From}");

    // Rechazar la llamada automáticamente
    await call.RejectAsync();
    await client.SendMessageAsync(call.From, "Lo siento, soy un bot y no puedo recibir llamadas.");
};

✉️ Envío de Mensajes y Medios

El método SendMessageAsync es altamente flexible. El primer parámetro es el ID del Chat (formato numero@c.us o idgrupo@g.us), y el segundo puede ser texto, un archivo, una ubicación, etc.

Enviar Texto Formateado

Puedes usar la clase WhatsAppText para construir mensajes con formato (negrita, cursiva, monoespaciado) de manera sencilla:

var mensajeFormat = WhatsAppText.New()
    .Bold("Notificación Importante").NewLine()
    .Text("El servidor ha sido reiniciado a las ")
    .Code("14:00").NewLine()
    .Italic("Por favor, verifica el sistema.");

await client.SendMessageAsync("1234567890@c.us", mensajeFormat);

Enviar Imágenes, Documentos y Stickers (MessageMedia)

Nota: Si se activa AutoCompressMedia en las opciones, la librería puede usar FFMPEG localmente para comprimir archivos antes de enviarlos.

// Desde una URL (requiere descargar la imagen primero y convertir a Base64, o usar herramientas internas si se exponen)
// Para archivos locales:
var media = MessageMedia.FromFilePath("ruta/imagen.jpg");

// Enviar como imagen normal
await client.SendMessageAsync(chatId, media);

// Enviar especificando que debe tratarse como Sticker
var opciones = new MessageSendOptions { SendMediaAsSticker = true };
await client.SendMessageAsync(chatId, media, opciones);

👥 Grupos, Canales y Búsqueda

WhatsNET ofrece funciones completas para gestionar y extraer información de grupos.

Obtener los grupos de un usuario

// Buscar todos los grupos del cliente actual
var grupos = await client.GetGroupsAsync();

foreach (var grupo in grupos)
{
    Console.WriteLine($"- Nombre: {grupo.Name} | ID: {grupo.Id.Serialized}");
}

Buscar un Chat Específico

var chat = await client.GetChatByIdAsync("1234567890@c.us");
if (chat != null)
{
    // Archivar chat
    await chat.ArchiveAsync();

    // Marcar como no leído
    await chat.MarkUnreadAsync();
}

🛠 Utilidades: Encuestas, Reacciones y Formateo

Crear y Enviar Encuestas

Utiliza PollBuilder para generar encuestas de manera intuitiva:

var encuesta = PollBuilder.Create("¿Cuál es tu lenguaje de programación favorito?")
    .AddOption("C#")
    .AddOption("TypeScript")
    .AddOption("Python")
    .AllowMultipleAnswers(false) // Permitir una sola respuesta
    .Build();

await client.SendMessageAsync(chatId, encuesta);

Reaccionar a Mensajes

Puedes reaccionar directamente usando el objeto Message:

client.MessageCreated += async (sender, e) =>
{
    var msg = e.Message;
    if (msg.Body.Contains("genial"))
    {
        await msg.ReactAsync("🚀"); // Reaccionar con un emoji
    }
};

Cola de Mensajes (Rate Limiting)

Para evitar bloqueos por spam al enviar mensajes masivos, usa SendMessageQueuedAsync. La librería gestionará un retraso aleatorio (basado en la configuración WithQueue) entre mensajes.

// En configuración: .WithQueue(minDelay: 1000, maxDelay: 3000)
await client.SendMessageQueuedAsync(chatId, "Mensaje 1");
await client.SendMessageQueuedAsync(chatId, "Mensaje 2"); // Se enviará de 1 a 3 segundos después

🛑 Cierre Seguro del Cliente

Para evitar dejar procesos de Chromium colgados o bases de datos corruptas (especialmente con LocalAuth), siempre cierra el cliente de forma limpia:

// Cuando recibas una señal de apagado o al finalizar tu aplicación:
client.RequestShutdown();
// Esto hará que el método WaitForExitAsync() termine y el cliente ejecute DestroyAsync() de forma segura.

Notas Adicionales

• Plataforma subyacente: Depende fuertemente de los scripts inyectados en la página web de WhatsApp. Si WhatsApp Web sufre una actualización importante, algunas funciones pueden fallar hasta que la librería sea actualizada.
• Seguridad: Nunca compartas el contenido de tu carpeta de sesión (LocalAuth), ya que contiene el acceso directo a tu cuenta de WhatsApp sin necesidad del código QR.