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

URL: https://wa.genuka.com/it/docs/errors/131050
Language: Italian

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

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](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences)).

## 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?

| Canale                              | Cosa ottieni                                                                |
| ----------------------------------- | --------------------------------------------------------------------------- |
| Risposta di `POST /api/v1/messages` | `403`, `"error": "recipient_opted_out"`, quando la disiscrizione è già nota |
| Webhook `message_status`            | `data.status: "failed"`, `data.errors[0].code: 131050`, quando Meta rifiuta |
| Webhook `user_preference.stopped`   | `data.waId`, `data.value: "stop"`, `data.timestamp`                         |
| Campagna                            | Destinatari `skipped`, con il motivo in `errorMessage`                      |

```json title="403 — POST /api/v1/messages"
{
  "error": "recipient_opted_out",
  "message": "This recipient opted out of marketing messages"
}
```

## Come risolvo l'errore 131050?

1. **Interrompi ogni invio di marketing verso questo contatto.** Genuka WA classifica 131050 come
   `recipient_permanent`: non viene mai riprovato.
2. **Registra la disiscrizione nel tuo strumento** (CRM, database clienti), così sopravvive a un export o a una
   campagna costruita altrove.
3. **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`.
4. **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.

**Node.js**

```ts
// 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);
}
```

**Python**

```python
# In your webhook route, once the signature is verified.
def on_event(event: dict) -> None:
    kind = event.get("type")
    data = event.get("data", {})

    if kind == "user_preference.stopped":
        crm.set_marketing_consent(data["waId"], False)
    elif kind == "user_preference.resumed":
        crm.set_marketing_consent(data["waId"], True)
    elif kind == "message_status" and data.get("status") == "failed":
        if any(error.get("code") == 131050 for error in data.get("errors", [])):
            crm.set_marketing_consent(data["recipient_id"], False)
```

## 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](https://wa.genuka.com/it/docs/errors/131049): un messaggio di marketing trattenuto per questo destinatario, ma solo
  temporaneamente; rinviare dopo 24 ore è consentito.
* [131026](https://wa.genuka.com/it/docs/errors/131026): il destinatario non riceve alcun messaggio, qualunque sia la
  categoria.
* [131047](https://wa.genuka.com/it/docs/errors/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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — user\_preferences webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences)
* [Meta — About the platform, user opt-in](https://developers.facebook.com/documentation/business-messaging/whatsapp/about-the-platform)
