Genuka WA docs

Errore WhatsApp 131050: l'utente ha interrotto i messaggi di marketing

Errore WhatsApp 131050: il destinatario ha interrotto i tuoi messaggi di marketing. Perché non devi mai riprovare, e come Genuka WA blocca gli invii successivi.

L'errore WhatsApp 131050 significa che il destinatario ha scelto di non ricevere più i tuoi messaggi di marketing su WhatsApp. Non riprovare: il messaggio non verrà ricevuto. Toglilo dai tuoi invii di marketing, e aggiungilo di nuovo solo se è lui stesso a riattivare i messaggi di marketing, cosa che Meta ti segnala tramite un webhook.

Cosa significa l'errore 131050?

"Unable to deliver the message. This recipient has chosen to stop receiving marketing messages on WhatsApp from your business." — Meta, Cloud API error codes

L'istruzione di Meta non lascia margini: "Do not retry sending messages to this user as they will not be received." Per saperlo in anticipo invece che dopo un invio fallito, Meta indica il webhook user_preferences, che scatta quando un utente interrompe o riprende i messaggi di marketing della tua azienda. Non scatta per i feedback "Interested" o "Not interested" dati tramite l'impostazione Offers and announcements (Meta, user_preferences webhook).

Quando si verifica l'errore 131050?

Quando invii un modello MARKETING a qualcuno che ha interrotto i messaggi di marketing dell'azienda. Con Genuka WA lo vedi soprattutto in due casi: la disiscrizione è precedente al collegamento del numero, quindi Genuka WA non ha mai ricevuto il webhook user_preferences che la annunciava; oppure il modello è stato creato fuori da Genuka WA, e la sua categoria ci è sconosciuta.

Cosa fa Genuka WA dal suo lato?

Una disiscrizione è un vincolo di conformità, non un'ottimizzazione. Genuka WA la tratta così:

  • Due fonti alimentano lo stesso registro, per cliente: il webhook user_preferences di Meta (stop o resume), e qualsiasi 131050 segnalato dal webhook di stato di un invio. Un'iscrizione può arrivare solo da un resume: un 131050 non viene mai interpretato come consenso.
  • Invio singolo: un modello MARKETING noto a Genuka WA, indirizzato a un contatto disiscritto, viene rifiutato prima di arrivare a Meta, con 403 recipient_opted_out. Non viene inviato nulla, non viene contato nulla sulla tua quota.
  • Campagna MARKETING: i contatti disiscritti vengono esclusi prima del primo invio, marcati skipped con il motivo "Recipient opted out of marketing messages", e contati nel campo skipped della risposta di lancio.
  • Cosa non viene bloccato: i modelli UTILITY e AUTHENTICATION, e le risposte libere dentro la finestra di 24 ore. Disiscriversi dal marketing non vuol dire rinunciare a ricevere risposte.

Dove lo vedi in Genuka WA?

CanaleCosa ottieni
Risposta di POST /api/v1/messages403, "error": "recipient_opted_out", quando la disiscrizione è già nota
Webhook message_statusdata.status: "failed", data.errors[0].code: 131050, quando Meta rifiuta
Webhook user_preference.stoppeddata.waId, data.value: "stop", data.timestamp
CampagnaDestinatari skipped, con il motivo in errorMessage
403 — POST /api/v1/messages
{
  "error": "recipient_opted_out",
  "message": "This recipient opted out of marketing messages"
}

Come risolvo l'errore 131050?

Interrompi ogni invio di marketing verso questo contatto. Genuka WA classifica 131050 come recipient_permanent: non viene mai riprovato.

Registra la disiscrizione nel tuo strumento (CRM, database clienti), così sopravvive a un export o a una campagna costruita altrove.

Ricevi gli eventi user_preference.stopped e user_preference.resumed. Un endpoint senza filtro sugli eventi li riceve già; un endpoint filtrato deve aggiungerli alla sua lista events tramite PATCH /api/v1/webhooks/{id}. Riattiva il contatto solo su un resumed.

Tratta 403 recipient_opted_out come una risposta normale, non come un disservizio: il contatto può ancora essere raggiunto con un modello di utilità e in risposta ai suoi messaggi.

// 1. On send: an opt-out refusal is not an error to page anyone about.
const response = await fetch("https://wa.genuka.com/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    connectionId: "con_1",
    to: "+237690000001",
    template: { name: "october_promo", language: "en", body: ["Awa"] },
  }),
});
if (response.status === 403) {
  const { error } = await response.json();
  if (error === "recipient_opted_out") await crm.setMarketingConsent("+237690000001", false);
}

// 2. In your webhook route, once the signature is verified.
export async function onEvent(event: { type: string; data: { waId?: string } }) {
  if (event.type === "user_preference.stopped") await crm.setMarketingConsent(event.data.waId!, false);
  if (event.type === "user_preference.resumed") await crm.setMarketingConsent(event.data.waId!, true);
}

Come prevengo l'errore 131050?

  • Raccogli un consenso esplicito prima di qualsiasi marketing, indicando la tua azienda e cosa invierai.
  • Ascolta user_preferences fin dal primo giorno: una disiscrizione appresa via webhook evita l'invio fallito, una appresa tramite 131050 arriva a cose fatte.
  • Crea i tuoi modelli tramite Genuka WA (POST /api/v1/templates): la loro categoria è allora nota, e si applica il 403 recipient_opted_out preventivo.
  • Invia meno, ma meglio. Una disiscrizione è la risposta di un cliente a messaggi che non voleva; frequenza e pertinenza sono le tue leve.

Codici di errore correlati

  • 131049: un messaggio di marketing trattenuto per questo destinatario, ma solo temporaneamente; rinviare dopo 24 ore è consentito.
  • 131026: il destinatario non riceve alcun messaggio, qualunque sia la categoria.
  • 131047: la finestra di 24 ore è chiusa per un messaggio libero.

FAQ

Posso ancora inviare una conferma d'ordine a un contatto disiscritto?

Genuka WA non blocca i modelli UTILITY o AUTHENTICATION per un contatto che si è disiscritto dal marketing: il 131050 di Meta riguarda i messaggi di marketing. La conferma d'ordine deve però essere un vero modello di utilità, non una promozione mascherata.

La disiscrizione vale per un numero o per tutta l'azienda?

Meta parla di messaggi di marketing "from your business". Genuka WA la registra per cliente: ogni numero di quel cliente è coperto.

Cosa succede con un modello creato fuori da Genuka WA?

Genuka WA non conosce la sua categoria e lo lascia passare. Se Meta segnala un 131050, la disiscrizione viene comunque registrata: le tue campagne di marketing e i modelli di marketing creati tramite Genuka WA escluderanno quel contatto da quel momento in poi. Il modello sconosciuto, invece, continua ad arrivare a Meta.

Come si riattiva un contatto?

Riattivando i messaggi di marketing della tua azienda in WhatsApp. Meta invia allora il webhook user_preferences con il valore resume, che Genuka WA ti inoltra come user_preference.resumed e applica al suo registro.

Fonti

In questa pagina