Genuka WA docs

Errore WhatsApp 131049: messaggio di marketing non consegnato

Errore WhatsApp 131049: Meta ha trattenuto il tuo modello di marketing per mantenere sano il coinvolgimento. Il limite per utente, e quando rinviare senza peggiorare le cose.

L'errore WhatsApp 131049 significa che Meta ha scelto di non consegnare un modello di marketing a questo destinatario, il più delle volte perché per ora ha raggiunto il suo limite di messaggi di marketing. Non è né un bug né una penalità sul tuo numero. Aspetta almeno 24 ore prima di riprovare con quel destinatario, a meno che non abbia un numero statunitense: lì, aspettare non serve.

Cosa significa l'errore 131049?

"This message was not delivered to maintain healthy ecosystem engagement." — Meta, Cloud API error codes

Meta aggiunge: "If you do receive this error code and suspect it is due to the limit, wait at least 24 hours before resending the template message." Il limite in questione è il limite per utente dei modelli di messaggio di marketing (Meta, Per-user marketing template message limits):

  • WhatsApp può limitare quanti modelli di marketing una persona riceve da qualsiasi azienda in un periodo, quando è meno probabile che interagisca con essi.
  • Il limite si adatta a ogni persona: il suo tasso di lettura recente dei messaggi di marketing, e quanti messaggi ha già nella sua inbox da amici, familiari e aziende.
  • Ogni modello di marketing consegnato conta. Se la persona risponde, si apre una finestra di assistenza clienti di 24 ore, e i messaggi di marketing inviati dentro quella finestra non contano.
  • Rinviare più volte entro 24 ore a qualcuno che ha raggiunto il suo limite può rendere quel destinatario irraggiungibile per fino a altre 24 ore, con lo stesso 131049. Gli altri tuoi destinatari non ne risentono.
  • Il limite non è attivo per i messaggi inviati da un numero dello Spazio economico europeo, del Regno Unito, del Giappone o della Corea del Sud, né verso un utente in quei paesi.

Perché i miei destinatari statunitensi falliscono sempre?

Perché Meta non consegna più alcun modello di marketing a loro. Sulla stessa pagina:

"WhatsApp does not currently deliver marketing template messages to WhatsApp users with United States phone numbers (numbers composed of a +1 dialing code and a US area code)."

Questo non è il limite per utente: il blocco non si toglie dopo 24 ore, e Meta non annuncia alcuna data di fine. Meta parla solo di "an error", senza codice; gli integratori lo riportano come 131049, in vigore dal 1° aprile 2025 (Message Central). Sono coinvolti solo i prefissi statunitensi, non tutti i numeri +1.

  • Togli quei numeri dalle tue campagne MARKETING. In una campagna, un 131049 ricevuto alla chiamata lascia il destinatario pending: un numero statunitense resterà lì a ogni rilancio.
  • Usa un altro tipo di messaggio: un modello UTILITY o AUTHENTICATION quando il contenuto lo consente (queste categorie non sono coinvolte, secondo la stessa fonte), oppure una risposta dentro la finestra di servizio di 24 ore che apre un messaggio del cliente.
  • Non riprogrammarli ogni 24 ore: ogni invio che Meta accetta prima di farlo fallire conta sulla quota del tuo abbonamento Genuka WA.

Quando si verifica l'errore 131049?

Riguarda solo i modelli MARKETING, e arriva sul webhook di stato: Meta lo dice esplicitamente, il fallimento è segnalato dal webhook messages con lo stato failed. Ecco l'esempio di Meta stessa, così come Genuka WA te lo inoltra in data:

message_status webhook (excerpt)
{
  "type": "message_status",
  "field": "messages",
  "data": {
    "id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgARGBI0QUQ2MjA4NEYyRkExNjMyREUA",
    "status": "failed",
    "timestamp": "1751142888",
    "recipient_id": "16505551234",
    "errors": [
      {
        "code": 131049,
        "title": "This message was not delivered to maintain healthy ecosystem engagement.",
        "message": "This message was not delivered to maintain healthy ecosystem engagement.",
        "error_data": {
          "details": "In order to maintain a healthy ecosystem engagement, the message failed to be delivered."
        },
        "href": "/documentation/business-messaging/whatsapp/support/error-codes"
      }
    ]
  }
}

Dove lo vedi in Genuka WA?

CanaleCosa ottieni
Webhook message_statusdata.status: "failed", data.errors[0].code: 131049
Campagna, fallimento segnalato via webhookIl destinatario diventa failed, con il messaggio di Meta in errorMessage
Campagna, rifiutato alla chiamataIl destinatario resta pending: non viene contato come fallito, e un nuovo lancio lo riprende
Risposta di POST /api/v1/messages, quando Meta rifiuta già alla chiamata400, "error": "send_recipient_throttled", meta.code: 131049

Genuka WA classifica questo codice come recipient_throttled: il messaggio va bene, il destinatario va bene, è il momento a essere sbagliato. Non viene mai riprovato subito, perché servirebbe solo a prolungare il blocco.

Come risolvo l'errore 131049?

Non inviare nulla per 24 ore. È l'unica istruzione di Meta, e quella più spesso ignorata: un rinvio immediato non passa e può prolungare il blocco.

Metti da parte quei destinatari. Dal webhook, salva il numero e l'ora del fallimento. GET /api/v1/campaigns/{id}/recipients?status=failed&limit=1000 ti dà anche l'elenco lato campagna, limitato a 1.000 righe senza paginazione: oltre, affidati a quello che hai salvato dal webhook.

Riprovali più tardi, in una nuova campagna, almeno 24 ore dopo il fallimento, senza i numeri statunitensi. Una campagna già lanciata rinvia solo i destinatari ancora pending.

import { parsePhoneNumberFromString } from "libphonenumber-js";

const RETRY_AFTER_MS = 24 * 60 * 60 * 1000;

// Called by your webhook route, once the signature is verified.
export async function onMessageStatus(event: {
  type: string;
  data: { status: string; recipient_id: string; errors?: { code: number }[] };
}) {
  if (event.type !== "message_status" || event.data.status !== "failed") return;
  if (!event.data.errors?.some((error) => error.code === 131049)) return;

  // A US number will not receive marketing in 24 hours either: take it out of your campaigns.
  if (parsePhoneNumberFromString(`+${event.data.recipient_id}`)?.country === "US") {
    await db.marketingExclusion.upsert({ waId: event.data.recipient_id, reason: "us_marketing" });
    return;
  }

  // Your storage: a "retry later" table with the earliest time a resend is allowed.
  await db.marketingRetry.upsert({
    waId: event.data.recipient_id,
    notBefore: new Date(Date.now() + RETRY_AFTER_MS),
  });
}

Come prevengo l'errore 131049?

  • Punta su chi legge. Il limite segue il tasso di lettura recente di ogni destinatario: una lista di clienti attivi rende meglio di tutta la tua anagrafica.
  • Invita a rispondere. Una risposta apre una finestra di 24 ore in cui i tuoi messaggi di marketing non contano più sul limite.
  • Distanzia le campagne verso le stesse persone, e togli dalle tue liste chi continua a collezionare 131049.
  • Misura la consegna sui webhook, non sugli invii accettati: una campagna di marketing può mostrare il 100% di accettati e una quota di 131049 all'arrivo.

Codici di errore correlati

  • 131050: la persona ha interrotto i tuoi messaggi di marketing; non rinviare mai.
  • 131048: è il tuo numero a essere limitato a causa di segnalazioni di spam, non un singolo destinatario.
  • 131026: il destinatario non può ricevere proprio nulla.

FAQ

L'errore 131049 penalizza il mio numero?

No. Meta precisa che il blocco causato da rinvii eccessivi non incide sulla tua capacità di inviare messaggi di marketing ad altri utenti. È un limite per destinatario.

I modelli di utilità e di autenticazione sono coinvolti?

Il limite descritto da Meta si applica ai modelli di marketing. Un codice di accesso o una conferma d'ordine in un modello AUTHENTICATION o UTILITY non vi è soggetto.

Quanto dura il limite?

Meta non indica una durata fissa: il limite si adatta al coinvolgimento di ogni persona. La regola è non rinviare prima di almeno 24 ore.

Perché alcuni dei miei destinatari europei non ricevono mai 131049?

Perché il limite non è attivo per gli utenti dello Spazio economico europeo, del Regno Unito, del Giappone e della Corea del Sud, né per i messaggi inviati da un numero in quei paesi.

Un modello di marketing fallito con 131049 viene fatturato?

Non da Meta, che addebita un modello di messaggio solo quando viene consegnato (Meta, Pricing). Lato Genuka WA, l'invio accettato da Meta ha già contato sulla quota del tuo abbonamento: rinviare troppo presto costa un messaggio di quota e non consegna nulla.

Fonti

In questa pagina