ArjuyWhatsApp 1.0.1

ArjuyWhatsApp

Cliente .NET liviano y sin dependencias de terceros propias para la WhatsApp Cloud API oficial de Meta. Permite enviar mensajes de texto, plantillas, imágenes y documentos, y descargar media recibida, usando HttpClient a través de IHttpClientFactory e integración estándar con Microsoft.Extensions.DependencyInjection / Microsoft.Extensions.Options.

No envuelve ningún SDK no oficial: habla directamente contra https://graph.facebook.com.

Instalación

dotnet add package ArjuyWhatsApp

Quickstart

1. Registrar el cliente

Opción A — desde IConfiguration (recomendada para apps con appsettings.json):

using ArjuyWhatsApp;

var builder = Host.CreateApplicationBuilder(args);

// Lee la sección "ArjuyWhatsApp" de appsettings.json (nombre de sección configurable).
builder.Services.AddArjuyWhatsApp(builder.Configuration);

{
  "ArjuyWhatsApp": {
    "AccessToken": "TU_ACCESS_TOKEN",
    "PhoneNumberId": "TU_PHONE_NUMBER_ID",
    "BusinessAccountId": "TU_BUSINESS_ACCOUNT_ID",
    "AppSecret": "TU_APP_SECRET",
    "VerifyToken": "TU_VERIFY_TOKEN",
    "ApiVersion": "v21.0"
  }
}

Opción B — configuración en código, sin IConfiguration:

using ArjuyWhatsApp;

services.AddArjuyWhatsApp(options =>
{
    options.AccessToken = "TU_ACCESS_TOKEN";
    options.PhoneNumberId = "TU_PHONE_NUMBER_ID";
    options.BusinessAccountId = "TU_BUSINESS_ACCOUNT_ID";
    options.AppSecret = "TU_APP_SECRET";
    options.VerifyToken = "TU_VERIFY_TOKEN";
    options.ApiVersion = "v21.0";
});

Usá una sola de las dos opciones por contenedor de DI: ambas registran la misma interfaz (IArjuyWhatsAppClient) y la última en ejecutarse gana la configuración de opciones.

2. Enviar un mensaje de texto

var whatsAppClient = serviceProvider.GetRequiredService<IArjuyWhatsAppClient>();

var result = await whatsAppClient.SendTextAsync("5491100000000", "Hola desde ArjuyWhatsApp!");

if (result.IsSuccess)
{
    Console.WriteLine($"Mensaje enviado. Message id: {result.Data}");
}
else
{
    Console.WriteLine($"Error al enviar el mensaje: {result.Message}");
}

Ver el proyecto ArjuyWhatsApp.Sample para un ejemplo ejecutable completo, con ambas formas de registro comentadas en Program.cs.

API — IArjuyWhatsAppClient

Todos los métodos que devuelven Task<MResult<T>> usan el mismo tipo de resultado propio y autocontenido (IsSuccess, Data, Message), sin excepciones para el flujo normal de error. Las excepciones de red/HTTP se capturan internamente y se traducen a MResult.Fail(...). Ver MANUAL.md, sección 3, para el flujo completo de recepción de mensajes vía webhook.

Responder citando un mensaje (context.message_id): todos los métodos de envío de contenido (SendTextAsync, ambos overloads de SendTemplateAsync, SendImageAsync, SendDocumentAsync, SendImageByMediaIdAsync, SendDocumentByMediaIdAsync, SendAudioAsync/SendAudioByMediaIdAsync, SendVideoAsync/SendVideoByMediaIdAsync, SendStickerAsync/SendStickerByMediaIdAsync, SendLocationAsync, SendContactsAsync, SendInteractiveButtonsAsync, SendInteractiveListAsync) aceptan un parámetro opcional replyToMessageId al final de la firma (excepción: SendReactionAsync no lo admite — la reacción ya referencia en sí misma al mensaje reaccionado). Pasale el wamid. de un mensaje entrante (el mismo valor de WhatsAppMessageReceived.MessageId) para que WhatsApp muestre el mensaje enviado como respuesta/cita de ese mensaje en el chat del destinatario. Si se omite, el mensaje se envía sin contexto, como hasta ahora.

await whatsAppClient.SendTextAsync("5491100000000", "¡Gracias por tu consulta!", replyToMessageId: mensajeEntrante.MessageId);

Errores estructurados de Meta (MResult.Error / MetaApiError)

Cuando un Fail viene de una respuesta no exitosa de la Graph API (no de una validación local, como los límites de botones/listas o falta de configuración), MResult.Error trae un MetaApiError con el code, error_subcode, type, fbtrace_id y el body crudo que devolvió Meta — además del Message de siempre, que sigue poblado para no romper a quien solo lo lee. Esto permite distinguir programáticamente, por ejemplo, un número sin WhatsApp de un token vencido o de un rate limit, sin tener que parsear el string de error a mano:

var result = await whatsAppClient.SendTextAsync("5491100000000", "Hola");

if (!result.IsSuccess && result.Error is { IsRateLimited: true })
{
    // No hace falta manejarlo a mano en general — ver "Retry automático" más abajo, la librería
    // ya reintenta sola los errores transitorios. Este chequeo sirve para lógica adicional propia
    // (por ejemplo, encolar el mensaje para reintentar más tarde si se agotaron los reintentos).
}

Error es null cuando el resultado es exitoso o cuando el fallo es de validación local de la librería (esos casos siguen usando MResult.Fail(string), sin un error de Meta detrás).

Retry automático con backoff exponencial

Ante un error transitorio de Meta (MetaApiError.IsTransient — rate limiting HTTP 429 o error 5xx del lado de Meta), la librería reintenta automáticamente antes de devolver el MResult.Fail. Los errores no transitorios (400, 401, 403, y las validaciones locales de botones/listas) nunca se reintentan — no tiene sentido reintentar algo que va a fallar exactamente igual.

{
  "ArjuyWhatsApp": {
    "MaxRetryAttempts": 3,
    "BaseRetryDelay": "00:00:00.500"
  }
}

• MaxRetryAttempts (default 3): cantidad de reintentos, sin contar el intento inicial. 0 desactiva el retry por completo.
• BaseRetryDelay (default 500ms): delay base del backoff exponencial — el reintento N espera BaseRetryDelay * 2^(N-1) con jitter aleatorio de ±20% (para no sincronizar reintentos entre varias instancias corriendo en paralelo). Con el default: ~500ms, ~1s, ~2s.
• Si la respuesta 429 de Meta trae el header Retry-After, ese valor se usa en vez del backoff calculado — Meta te está diciendo explícitamente cuánto esperar.

Aplica a todos los métodos que llaman a la Graph API (envío de mensajes, UploadMediaAsync, DownloadMediaAsync). Agotados los reintentos, se devuelve el último MResult.Fail tal cual, con el MetaApiError real de Meta.

Normalización de números de teléfono

La normalización del número de destino (campo "to" del payload) es una estrategia inyectable, IPhoneNumberNormalizer, no un método para heredar. La librería trae dos implementaciones built-in y elige una automáticamente según ArjuyWhatsAppOptions.CountryCode:

• "AR" → ArgentinaPhoneNumberNormalizer — resuelve el "9" móvil de Argentina (va inmediatamente después del código de país 54, no al final) y el "15" del marcado local de celular. Ver el XML doc de la clase para la limitación conocida sobre códigos de área de más de 2 dígitos.
• Cualquier otro valor (o sin configurar) → DefaultPhoneNumberNormalizer — solo recorta espacios, sin ninguna transformación adicional (comportamiento histórico de la librería).

{
  "ArjuyWhatsApp": {
    "CountryCode": "AR"
  }
}

Si necesitás una regla propia (otro país, o una tabla de códigos de área más precisa que la built-in de Argentina), registrá tu propia implementación en el contenedor de DI antes de llamar a AddArjuyWhatsApp — la librería usa TryAddSingleton, así que tu registración gana y el CountryCode de las opciones se ignora:

services.AddSingleton<IPhoneNumberNormalizer, MiNormalizadorPropio>();
services.AddArjuyWhatsApp(builder.Configuration);

Target framework choice

El paquete apunta a net8.0.

Se evaluó netstandard2.0 para maximizar compatibilidad hacia atrás (incluyendo .NET Framework), pero se descartó porque:

• El SDK instalado en esta máquina (dotnet --list-sdks → 10.0.400) soporta correctamente net8.0, que es la LTS activa más reciente al momento de crear este paquete.
• net8.0 da acceso directo a APIs modernas usadas en la implementación (System.Net.Http.Json, JsonContent.Create, IHttpClientFactory con Microsoft.Extensions.Http 8.x) sin necesidad de polyfills ni paquetes adicionales que netstandard2.0 hubiera requerido.
• El público objetivo (proyectos propios arjuy*, todos en .NET moderno) ya vive en .NET 8+, por lo que la compatibilidad extendida de netstandard2.0 no aporta valor real y sí agrega fricción (menos APIs disponibles, necesidad de #if o paquetes de compatibilidad).

Si en el futuro se necesita soporte para .NET Framework o Xamarin, se puede agregar netstandard2.0 como un multi-targeting adicional (<TargetFrameworks>net8.0;netstandard2.0</TargetFrameworks>) sin romper a los consumidores actuales.

Errores comunes de Meta (troubleshooting)

Tabla con códigos de error reales encontrados en producción (no de la documentación teórica de Meta), con la causa típica y cómo esta librería ya los previene o qué tiene que hacer quien consume la librería:

Al diagnosticar un WhatsAppMessageStatusUpdate con Status == Failed, mirá primero ErrorDetails (no ErrorMessage): Meta suele mandar title/message genéricos o directamente idénticos entre sí (ej. código 131053 trae Title = "Media upload error" y Message = "Media upload error", que no dicen nada), mientras que error_data.details —mapeado a ErrorDetails— siempre trae el motivo específico y accionable (para el mismo caso 131053: "Unsupported Audio mime type video/ogg. Please use one of audio/ogg; codecs=opus, audio/mpeg, audio/amr, audio/mp4, audio/aac.").

Roadmap / Pendiente

Estas funcionalidades quedaron explícitamente fuera de esta primera versión y son las primeras candidatas para una futura iteración:

1. Audio/video/sticker con helpers dedicados por URL o media_id (hoy solo imagen/documento los tienen — para el resto de tipos hay que armar el payload genérico a mano).

Estructura del repositorio

• ArjuyWhatsApp/ — la librería empaquetable (el paquete NuGet en sí).
• ArjuyWhatsApp.Tests/ — tests unitarios con xUnit, mockeando HttpMessageHandler (nunca pega contra la API real de Meta).
• ArjuyWhatsApp.Sample/ — consola de ejemplo que muestra ambas formas de registro y un envío de texto real usando DI.
• ArjuyWhatsApp.Sample.Api/ — API mínima con envío por controllers y recepción vía webhook (puerto 7100), usada en la guía end-to-end de MANUAL.md.
• ArjuyWhatsApp.Sample.Web/ — sample tipo "chat" con Razor Pages: envío + listado de recibidos (puerto 7220/5220).
• ArjuyWhatsApp.Sample.WinForms/ — sample de escritorio (Windows Forms) con host Kestrel embebido para el webhook (puerto 7300).
• ArjuyWhatsApp.Sample.Wpf/ — sample de escritorio (WPF) con host Kestrel embebido para el webhook (puerto 7200).

Si esta librería te resultó útil, una ⭐ en el repo ayuda más de lo que parece.