Notifiche d'ordine WhatsApp dal tuo backend
Invia da WhatsApp conferme d'ordine, aggiornamenti di spedizione e di consegna dal tuo backend: modelli di utilità, variabili, idempotenza e stati di consegna.
Per avvisare i clienti di un ordine su WhatsApp, crea un modello di categoria UTILITY per ogni
fase (confermato, spedito, consegnato), fallo approvare da Meta, poi chiama POST /api/v1/messages
dal tuo backend con le variabili dell'ordine. Il testo libero è consentito solo se il cliente ti ha
scritto nelle ultime 24 ore.
Ultimo aggiornamento: 8 ottobre 2026
Cosa mi serve prima di iniziare?
- Un numero collegato a Genuka WA e il suo
connectionId: vedi la guida rapida. - Una chiave API, usata solo lato server: vedi Autenticazione.
- Un metodo di pagamento sul WhatsApp Business Account, presso Meta. Genuka è un Meta Tech
Provider, non un BSP: Meta fattura direttamente l'account, e un cliente registrato tramite un
Tech Provider deve aggiungere il proprio metodo di pagamento
(Meta, Partners).
Senza, i modelli vengono approvati ma ogni invio torna indietro con l'errore
131042: vedi errore 131042.
Quali modelli dovrebbe creare un negozio online?
Un modello per ogni momento in cui il cliente aspetta notizie sul suo ordine. Tre bastano per iniziare:
| Fase | Modello | Variabili del corpo | Pulsante |
|---|---|---|---|
| Ordine confermato | order_confirmed | nome, numero, importo | URL "Vedi il mio ordine" |
| Ordine spedito | order_shipped | nome, numero, corriere | URL "Traccia il mio pacco" |
| Ordine consegnato | order_delivered | nome, numero | Nessuno: il messaggio invita a rispondere |
Per Meta, un modello di utilità è attivato da un'azione o una richiesta del cliente, è specifico per quel cliente e non contiene nulla di promozionale. Le conferme d'ordine e gli aggiornamenti di spedizione sono gli esempi da manuale; un modello che mescola informazioni sull'ordine con un'offerta, un upsell o una spinta al rinnovo viene ricategorizzato come marketing (documentazione Meta, categorization). Tieni le promozioni fuori da questi messaggi.
Come creo un modello di utilità?
Invia il modello
Ogni variabile del corpo richiede un esempio in example.body_text, e la variabile di un pulsante
URL sostituisce solo la fine dell'indirizzo, con il suo esempio.
curl -X POST https://wa.genuka.com/api/v1/templates \
-H "Authorization: Bearer $GENUKA_WA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"connectionId": "con_1",
"name": "order_shipped",
"language": "en",
"category": "UTILITY",
"components": [
{ "type": "BODY",
"text": "Hi {{1}}, your order {{2}} is on its way with {{3}}. Track it with the button below.",
"example": { "body_text": [["Awa", "ORD-1042", "DHL"]] } },
{ "type": "BUTTONS", "buttons": [
{ "type": "URL", "text": "Track my parcel",
"url": "https://shop.example.com/track/{{1}}",
"example": ["https://shop.example.com/track/ORD-1042"] }
] }
]
}'Nella dashboard: Modelli › Nuovo modello, categoria Utilità.
Attendi l'approvazione
Il verdetto di Meta arriva come webhook template_status (se il tuo endpoint è iscritto a
template.status_changed, o a tutti gli eventi), si può leggere su GET /api/v1/templates/{id} e
si può recuperare con POST /api/v1/templates/sync se un webhook è andato perso. Invia solo un
modello approved.
Imposta una durata di validità se il messaggio diventa obsoleto
Se un messaggio non può essere consegnato, WhatsApp continua a riprovare per la durata di validità
del modello: 30 giorni per impostazione predefinita per un modello di utilità, configurabile da 30
secondi a 12 ore
(documentazione Meta, time-to-live).
Un "il tuo corriere arriva tra 30 minuti" ricevuto il giorno dopo fa più danni che altro: per quel
tipo di modello, passa messageSendTtlSeconds alla creazione.
Come invio la notifica dal mio backend?
Una chiamata per notifica. body riempie {{1}}, {{2}}, {{3}} in ordine (variables è un
alias accettato), e buttons[].text completa l'URL del pulsante.
const API = "https://wa.genuka.com/api/v1";
type Order = { number: string; firstName: string; phone: string; carrier: string };
/** Il corpo della risposta: `data` in caso di successo, altrimenti `error` (più `meta` se Meta ha rifiutato). */
type ApiResult = {
data?: { messageId: string };
error?: string;
message?: string;
meta?: { retryable?: boolean; code?: number };
};
export async function sendOrderShipped(order: Order): Promise<string> {
const response = await fetch(`${API}/messages`, {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
connectionId: process.env.GENUKA_WA_CONNECTION_ID,
to: order.phone, // internazionale, con il +: "+237699001122"
template: {
name: "order_shipped",
language: "en", // la lingua esatta del modello, altrimenti l'invio punta a "en_US"
body: [order.firstName, order.number, order.carrier],
buttons: [{ type: "url", text: order.number }],
},
}),
signal: AbortSignal.timeout(15_000),
});
// Un 5xx della CDN non è JSON: senza questo catch, l'errore di parsing perderebbe `retryable`
// e la notifica verrebbe archiviata come errore permanente.
const result = (await response.json().catch(() => ({}))) as ApiResult;
if (!response.ok || !result.data) {
throw Object.assign(new Error(result.message ?? result.error), {
status: response.status,
// Un rifiuto permanente (modello, numero) non vale un nuovo tentativo: lo dice meta.retryable.
retryable: response.status >= 500 || result.meta?.retryable === true,
});
}
return result.data.messageId;
}Un 200 significa che Meta ha accettato il messaggio; segui la consegna via webhook, usando questo
messageId. Per inviare lo stesso modello a un intero elenco in una volta, usa invece le
campagne; ogni tipo di contenuto è descritto in
Inviare messaggi.
Quando posso inviare testo libero invece di un modello?
Quando il cliente ti scrive, si apre una finestra del servizio clienti di 24 ore, e ogni suo nuovo messaggio la fa ripartire. Finché è aperta puoi rispondere con qualsiasi messaggio; una volta chiusa, passano solo i modelli approvati (documentazione Meta).
Il caso tipico: il cliente risponde all'aggiornamento di spedizione con "Domani non sarò a casa". La
tua risposta può essere testo semplice, citato con replyTo:
{
"connectionId": "con_1",
"to": "+237699001122",
"replyTo": "wamid.HBg…",
"text": "Ricevuto, il corriere ripasserà giovedì tra le 14 e le 16."
}In fattura, Meta non addebita i messaggi non modello, e anche un modello di utilità consegnato dentro una finestra aperta è gratuito (prezzi di Meta).
Fuori dalla finestra, il testo libero fallisce, ma non al momento dell'invio. Nei nostri test su un
numero reale, Meta lo ha accettato con un messageId e poi lo ha scartato: di solito segue uno
stato failed con l'errore 131047
(codici di errore di Meta);
a volte non arriva alcuno stato. Quindi non aspettare l'errore: Genuka WA non blocca l'invio, ma ti
avvisa nella risposta, ed è su quell'avviso che devi agire:
{
"data": {
"messageId": "wamid.HBg…",
"warning": { "code": "outside_service_window", "message": "…" }
}
}outside_service_window significa che l'ultimo messaggio del cliente risale a più di 24 ore fa:
invia invece un modello. unverified_service_window significa solo che non abbiamo in archivio
alcun messaggio in arrivo da quel contatto, il che non prova che la finestra sia chiusa. Segui lo
stato del messaggio e reinvialo come modello solo se arriva failed con 131047, o non arriva
nulla: reinviarlo subito rischia di consegnare due volte la stessa notifica.
Come evito di inviare due volte la stessa notifica?
L'API non ha una chiave di idempotenza: è il tuo backend a garantire che un ordine riceva ogni notifica una sola volta. Il modo più semplice è una tabella la cui chiave primaria è la coppia ordine + fase.
create table order_notifications (
order_id text not null,
event text not null, -- confirmed | shipped | delivered
status text not null default 'pending',
message_id text unique, -- il wamid restituito da Genuka WA
error_code integer,
created_at timestamptz not null default now(),
primary key (order_id, event)
);import { Pool } from "pg";
const db = new Pool();
export async function notifyOnce(orderId: string, event: string, send: () => Promise<string>) {
// 1. Prenotazione: una seconda chiamata per lo stesso ordine e la stessa fase non fa nulla.
const claimed = await db.query(
"insert into order_notifications (order_id, event) values ($1, $2) on conflict do nothing",
[orderId, event],
);
if (claimed.rowCount === 0) return;
try {
// 2. Invia, 3. salva il wamid: è ciò che collega gli stati successivi a questa riga.
const messageId = await send();
await db.query(
"update order_notifications set status = 'sent', message_id = $3 where order_id = $1 and event = $2",
[orderId, event, messageId],
);
} catch (error) {
if ((error as { retryable?: boolean }).retryable === true) {
// Libera la prenotazione: la prossima esecuzione del job riproverà.
await db.query("delete from order_notifications where order_id = $1 and event = $2", [orderId, event]);
} else {
await db.query(
"update order_notifications set status = 'failed' where order_id = $1 and event = $2",
[orderId, event],
);
}
throw error;
}
}
// await notifyOnce(order.id, "shipped", () => sendOrderShipped(order));Un timeout di rete è ambiguo: Meta può aver accettato il messaggio prima che la risposta andasse persa. Questo codice lo archivia come errore piuttosto che rischiare un duplicato. Se per il tuo negozio un raro duplicato è meglio di una conferma persa, tratta anche i timeout come ritentabili.
Come seguo la consegna di ogni notifica?
Gli stati raggiungono il tuo webhook con il tipo message_status. data.id è il messageId
restituito al momento dell'invio, e data.status è sent, delivered, read o failed. In caso
di errore, data.errors[0].code contiene il codice di Meta
(documentazione Meta, statuses).
const RANK: Record<string, number> = { pending: 0, sent: 1, delivered: 2, read: 3, failed: 4 };
if (event.type === "message_status") {
const { id: messageId, status, errors } = event.data;
const row = await findNotificationByMessageId(messageId);
// Gli stati possono arrivare in disordine: uno stato non viene mai declassato,
// e `failed` è definitivo.
if (row && row.status !== "failed" && (RANK[status] ?? -1) > RANK[row.status]) {
await setNotificationStatus(messageId, status, errors?.[0]?.code ?? null);
}
}Per Meta, read significa che il messaggio è stato visualizzato in una chat aperta sul dispositivo
del cliente; non costruire logica di business che lo aspetti. La verifica della firma e la
deduplicazione sono trattate in
Ricevere risposte e stati via webhook.
Quali errori incontrerò più spesso?
| Errore | Dove leggerlo | Significato | Cosa fare |
|---|---|---|---|
400 missing_fields | Risposta | Manca connectionId o to | Completa la richiesta |
400 recipient_is_sender | Risposta | to è il numero mittente stesso | Cambia il destinatario |
402 subscription_past_due | Risposta | La prova o il periodo pagato è scaduto: non si invia nulla finché non viene rinnovato | Rinnova il piano, poi reinvia ciò che notifyOnce ha archiviato come failed |
402 plan_limit_messages | Risposta | La quota di messaggi del periodo è esaurita | Aggiungi numeri o cambia piano |
404 connection_not_found | Risposta | Il connectionId non esiste o è fuori dall'ambito della tua chiave | Controlla l'id e la chiave |
409 number_released | Risposta | Il numero è stato rilasciato dal tuo piano | Ricollegalo tramite l'Embedded Signup |
403 account_deactivated | Risposta | Il cliente a cui appartiene il numero è sospeso | Ripristina il cliente dalla sua pagina nella dashboard |
132001 | meta.code o stato failed | Modello mancante in quella lingua, o non approvato | Controlla nome, lingua e stato |
132000 | meta.code o stato failed | Il numero di variabili è diverso da quello del modello | Fai corrispondere body a {{1}}…{{n}} |
131026 | Stato failed | Messaggio non consegnabile, ad es. numero senza WhatsApp | Ripiega su email o SMS |
131047 | Stato failed, a volte mai ricevuto | Testo libero inviato più di 24 h dopo l'ultimo messaggio del cliente | Invia un modello; agisci sul warning della risposta |
130429 | meta.code | Raggiunto il throughput della Cloud API | Riprova con un backoff crescente |
131042 | meta.code o stato failed | Problema con il metodo di pagamento sull'account Meta | Il cliente sistema la fatturazione lato Meta: vedi errore 131042 |
I significati dei codici di Meta vengono dal suo elenco dei codici di errore.
FAQ
Quanto costa una notifica d'ordine WhatsApp?
Meta addebita i modelli consegnati per categoria e paese del destinatario, fatturati direttamente al WhatsApp Business Account del commerciante; un modello di utilità consegnato dentro una finestra del servizio clienti aperta è gratuito (prezzi di Meta). Genuka WA non applica ricarichi su queste tariffe: paghi un abbonamento per numero, con una quota di messaggi: vedi i piani.
Posso inserire un codice promozionale nella conferma d'ordine?
No. Un'offerta o un upsell dentro un modello di utilità lo fa ricategorizzare come marketing da Meta. Invia la promozione a parte, in un modello marketing, ai clienti che hanno accettato di riceverle.
Mi serve il consenso del cliente?
Sì. Meta ti chiede di indicare chiaramente che la persona accetta di ricevere messaggi dalla tua azienda, e di nominare quell'azienda (documentazione Meta, opt-in). Una casella "Ricevi gli aggiornamenti dell'ordine da [Nome del negozio] su WhatsApp" al checkout, salvata con l'ordine, soddisfa entrambe le condizioni.
E se il cliente non ha un account WhatsApp?
Lo stato torna failed con il codice 131026. Non riprovare: invia la stessa informazione via email
o SMS.
Gestisco più negozi: come scelgo il numero mittente?
Ogni negozio collega il suo numero e ottiene il proprio connectionId; è questo che decide da dove
parte il messaggio. Una chiave partner raggiunge tutti i tuoi negozi, una chiave cliente solo uno:
vedi Autenticazione e, per trovare il numero di un negozio,
Collegare un numero.
Fonti
Inviare codici OTP WhatsApp da Node.js
Invia password monouso su WhatsApp da Node.js con Genuka WA: modello di autenticazione, pulsante per copiare il codice, scadenza, verifica e fallback via SMS.
Inviare una campagna WhatsApp tramite l'API
Invia una campagna WhatsApp tramite l'API: modello marketing, destinatari, lancio, quote del piano, limiti marketing di Meta e tracciamento delle consegne.