Biblioteca TypeScript
@genuka/whatsapp — constructores tipados, validación y normalización de eventos.
@genuka/whatsapp no es un cliente HTTP más. Es la capa que evita los 400 evitables, hace que el
manejo de webhooks sea exhaustivo en tiempo de compilación y convierte los ~200 códigos de error de
Meta en siete decisiones accionables.
La biblioteca funciona de forma independiente contra la Cloud API de Meta, sin cuenta de Genuka. Se distribuye bajo licencia MIT.
Instalación
npm install @genuka/whatsappConstruir un mensaje
Las longitudes, las cardinalidades y el formato del número de teléfono se verifican antes de la llamada de red.
import { messages } from "@genuka/whatsapp";
const choice = messages.buttons("+237 6 99 00 11 22", {
body: "How can we help?",
buttons: [
{ id: "order", title: "My order" },
{ id: "support", title: "A problem" },
],
});Un error de construcción se lanza de inmediato, con la ruta del campo problemático:
ValidationError: interactive.buttons: must contain at most 3 items (got 4)La ventana de 24 horas
import { sendStrategy } from "@genuka/whatsapp";
sendStrategy(contact.lastInboundAt); // "free_form" | "template"Una llamada a función, en lugar de un 131047 descubierto cuando el intento ya fue facturado.
Manejar un webhook
Meta anida todo en entry[].changes[].value, donde el verdadero discriminante no es un campo sino
la presencia de messages o de statuses. La biblioteca lo aplana de una vez por todas.
import { parseWebhook, eventKey } from "@genuka/whatsapp/webhooks";
for (const event of parseWebhook(await request.json())) {
if (await alreadyProcessed(eventKey(event))) continue;
switch (event.kind) {
case "message": // entrante
case "status": // sent / delivered / read / failed / deleted
case "template": // aprobación, calidad, recategorización
case "account": // calidad del número, límites, suspensión
case "user_preference": // baja de marketing (opt-out)
case "coexistence": // historial, ecos, contactos
case "unknown": // nunca se pierde, siempre se reenvía
}
}El parser nunca lanza excepciones: un payload mal formado produce una lista vacía. Una excepción aquí se convertiría en un 500, y Meta reenviaría todo el lote.
Decidir qué hacer con un error
errorClass lleva la decisión, no el código numérico.
import { WhatsAppError } from "@genuka/whatsapp";
try {
await send(payload);
} catch (error) {
if (!(error instanceof WhatsAppError)) throw error;
switch (error.errorClass) {
case "needs_template": return resendAsTemplate(); // 131047
case "recipient_permanent": return markUnreachable(); // 131026, 131050
case "recipient_throttled": return requeueLater(); // 131049
case "media": return reuploadAndRetryOnce(); // 131052
case "retryable": return backoff(); // 4, 130429, 5xx
case "config": return alertOperator(); // 190, 133010
case "template": return surfaceToCustomer(); // 132xxx
case "validation":
case "unknown": throw error;
}
}Dos transportes, un mismo núcleo
El mismo payload construido puede viajar por dos rutas, con los mismos constructores, la misma validación y la misma taxonomía de errores:
// Con una clave de Genuka WA: sin ningún token de Meta de por medio
import { GenukaTransport } from "@genuka/whatsapp";
const transport = new GenukaTransport({ apiKey: process.env.GENUKA_WA_API_KEY! });
// Directo a Meta, si tienes tus propias credenciales
import { MetaTransport } from "@genuka/whatsapp";
const transport = new MetaTransport({ accessToken: process.env.META_TOKEN! });Referencia completa
Cada módulo tiene su propia guía, extraída del propio paquete: viven junto al código que describen, así que no se desfasan:
Enviar mensajes
Plantillas
Multimedia
Webhooks
Flows
Gestión
Coexistencia
Llamadas
Versión de la Graph API
La biblioteca fija explícitamente una versión de la Graph API en lugar de seguir "latest". Un cambio
de versión silencioso es la mejor manera de descubrir un cambio incompatible en producción: modificar
DEFAULT_GRAPH_VERSION es una versión publicada a propósito.
Referencia de la API
Una sola API para controlarlo todo de forma programática: números, plantillas, mensajes, campañas y tu suscripción.
Códigos de error de WhatsApp Cloud API: causas y soluciones
Códigos de error de WhatsApp Cloud API explicados: qué significan 131047, 131026, 130429, 132001, 141010 y los demás, y si conviene reintentar.