Libreria TypeScript
@genuka/whatsapp — builder tipizzati, validazione e normalizzazione degli eventi.
@genuka/whatsapp non è l'ennesimo client HTTP. È lo strato che previene i 400 evitabili, rende
la gestione dei webhook esaustiva in fase di compilazione e trasforma i ~200 codici di errore di
Meta in sette decisioni concrete.
La libreria funziona in modo autonomo con la Cloud API di Meta, senza account Genuka. È distribuita con licenza MIT.
Installazione
npm install @genuka/whatsappCostruire un messaggio
Lunghezze, cardinalità e formato del numero di telefono vengono verificati prima della chiamata di rete.
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 errore di costruzione viene lanciato immediatamente, con il percorso del campo problematico:
ValidationError: interactive.buttons: must contain at most 3 items (got 4)La finestra di 24 ore
import { sendStrategy } from "@genuka/whatsapp";
sendStrategy(contact.lastInboundAt); // "free_form" | "template"Una chiamata di funzione, invece di un 131047 scoperto quando il tentativo è già stato fatturato.
Gestire un webhook
Meta annida tutto in entry[].changes[].value, dove il vero discriminante non è un campo ma la
presenza di messages o di statuses. La libreria appiattisce tutto una volta per tutte.
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": // in arrivo
case "status": // sent / delivered / read / failed / deleted
case "template": // approvazione, qualità, ricategorizzazione
case "account": // qualità del numero, limiti, sospensione
case "user_preference": // disiscrizione dal marketing (opt-out)
case "coexistence": // cronologia, echi, contatti
case "unknown": // mai perso, sempre inoltrato
}
}Il parser non lancia mai eccezioni: un payload malformato produce una lista vuota. Un'eccezione qui diventerebbe un 500, e Meta reinvierebbe l'intero lotto.
Decidere cosa fare con un errore
errorClass porta la decisione, non il codice numerico.
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;
}
}Due trasporti, un solo nucleo
Lo stesso payload costruito può viaggiare su due percorsi, con gli stessi builder, la stessa validazione e la stessa tassonomia degli errori:
// Con una chiave Genuka WA: nessun token Meta coinvolto
import { GenukaTransport } from "@genuka/whatsapp";
const transport = new GenukaTransport({ apiKey: process.env.GENUKA_WA_API_KEY! });
// Direttamente verso Meta, se hai le tue credenziali
import { MetaTransport } from "@genuka/whatsapp";
const transport = new MetaTransport({ accessToken: process.env.META_TOKEN! });Riferimento completo
Ogni modulo ha la sua guida, tratta direttamente dal pacchetto: vivono accanto al codice che descrivono, quindi non si disallineano:
Inviare messaggi
Modelli
Media
Webhook
Flows
Gestione
Coesistenza
Chiamate
Versione della Graph API
La libreria fissa esplicitamente una versione della Graph API invece di seguire "latest". Un
cambio di versione silenzioso è il modo migliore per scoprire una modifica incompatibile in
produzione: cambiare DEFAULT_GRAPH_VERSION è un rilascio deliberato.
Riferimento dell'API
Una sola API per gestire tutto in modo programmatico: numeri, modelli, messaggi, campagne e il tuo abbonamento.
Codici di errore della WhatsApp Cloud API: cause e soluzioni
I codici di errore della WhatsApp Cloud API spiegati: cosa significano 131047, 131026, 130429, 132001, 141010 e gli altri, e se conviene riprovare.