Genuka WA docs

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:

FaseModelloVariabili del corpoPulsante
Ordine confermatoorder_confirmednome, numero, importoURL "Vedi il mio ordine"
Ordine speditoorder_shippednome, numero, corriereURL "Traccia il mio pacco"
Ordine consegnatoorder_deliverednome, numeroNessuno: 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.

POST /api/v1/templates
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.

send-order-shipped.ts
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:

POST /api/v1/messages
{
  "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:

200 OK — con un avviso
{
  "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.

schema.sql
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)
);
notify-once.ts
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).

Nel tuo ricevitore di webhook (firma già verificata)
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?

ErroreDove leggerloSignificatoCosa fare
400 missing_fieldsRispostaManca connectionId o toCompleta la richiesta
400 recipient_is_senderRispostato è il numero mittente stessoCambia il destinatario
402 subscription_past_dueRispostaLa prova o il periodo pagato è scaduto: non si invia nulla finché non viene rinnovatoRinnova il piano, poi reinvia ciò che notifyOnce ha archiviato come failed
402 plan_limit_messagesRispostaLa quota di messaggi del periodo è esauritaAggiungi numeri o cambia piano
404 connection_not_foundRispostaIl connectionId non esiste o è fuori dall'ambito della tua chiaveControlla l'id e la chiave
409 number_releasedRispostaIl numero è stato rilasciato dal tuo pianoRicollegalo tramite l'Embedded Signup
403 account_deactivatedRispostaIl cliente a cui appartiene il numero è sospesoRipristina il cliente dalla sua pagina nella dashboard
132001meta.code o stato failedModello mancante in quella lingua, o non approvatoControlla nome, lingua e stato
132000meta.code o stato failedIl numero di variabili è diverso da quello del modelloFai corrispondere body a {{1}}…{{n}}
131026Stato failedMessaggio non consegnabile, ad es. numero senza WhatsAppRipiega su email o SMS
131047Stato failed, a volte mai ricevutoTesto libero inviato più di 24 h dopo l'ultimo messaggio del clienteInvia un modello; agisci sul warning della risposta
130429meta.codeRaggiunto il throughput della Cloud APIRiprova con un backoff crescente
131042meta.code o stato failedProblema con il metodo di pagamento sull'account MetaIl 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

In questa pagina