# Error 131050 de WhatsApp: el usuario dejó de recibir marketing

URL: https://wa.genuka.com/es/docs/errors/131050
Language: Spanish

> Error 131050 de WhatsApp: el destinatario dejó de recibir tus mensajes de marketing. Por qué nunca debes reintentar y cómo Genuka WA bloquea los envíos que vendrían después.

El error 131050 de WhatsApp significa que el destinatario decidió dejar de recibir tus mensajes de
marketing en WhatsApp. No reintentes: el mensaje no se recibirá. Quítalo de tus envíos de
marketing y solo vuelve a incluirlo si él mismo reactiva los mensajes de marketing, algo que Meta
te comunica mediante un webhook.

## ¿Qué significa el error 131050?

> "Unable to deliver the message. This recipient has chosen to stop receiving marketing messages
> on WhatsApp from your business."
> — [Meta, códigos de error de la Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

(No se pudo entregar el mensaje. Este destinatario decidió dejar de recibir mensajes de marketing
de tu empresa en WhatsApp).

La instrucción de Meta no deja margen: "Do not retry sending messages to this user as they will
not be received." (No vuelvas a intentar enviar mensajes a este usuario, ya que no los recibirá).
Para enterarte con antelación y no después de un envío fallido, Meta remite al webhook
**`user_preferences`**, que se dispara cuando un usuario deja de recibir o reactiva los mensajes
de marketing de tu empresa. No se dispara con las respuestas "Me interesa" o "No me interesa"
dadas desde el ajuste *Ofertas y anuncios*
([Meta, webhook user\_preferences](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/user_preferences)).

## ¿Cuándo aparece el error 131050?

Cuando envías una plantilla `MARKETING` a alguien que dejó de recibir los mensajes de marketing de
la empresa. Con Genuka WA lo ves sobre todo en dos casos: la baja es anterior a la conexión del
número, así que Genuka WA nunca recibió el webhook `user_preferences` que la anunciaba; o la
plantilla se creó fuera de Genuka WA y desconocemos su categoría.

### ¿Qué hace Genuka WA por su lado?

Una baja es un límite de cumplimiento normativo, no una optimización. Genuka WA la trata así:

* **Dos fuentes alimentan el mismo registro**, por cliente: el webhook `user_preferences` de Meta
  (`stop` o `resume`) y cualquier 131050 informado por el webhook de estado de un envío. Un
  consentimiento solo puede provenir de un `resume`: un 131050 nunca se interpreta como
  consentimiento.
* **Envío individual**: una plantilla `MARKETING` conocida por Genuka WA, dirigida a un contacto
  dado de baja, se rechaza **antes** de llegar a Meta, con `403 recipient_opted_out`. No se envía
  nada y no se descuenta nada de tu cuota.
* **Campaña `MARKETING`**: los contactos dados de baja se excluyen antes del primer envío, se
  marcan como `skipped` con el motivo "Recipient opted out of marketing messages" y se cuentan en
  el campo `skipped` de la respuesta de lanzamiento.
* **Lo que no se bloquea**: las plantillas `UTILITY` y `AUTHENTICATION`, y las respuestas libres
  dentro de la ventana de 24 horas. Darse de baja del marketing no es renunciar a recibir
  respuestas.

### ¿Dónde lo ves en Genuka WA?

| Canal                                | Qué recibes                                                                 |
| ------------------------------------ | --------------------------------------------------------------------------- |
| Respuesta de `POST /api/v1/messages` | `403`, `"error": "recipient_opted_out"`, cuando la baja ya es conocida      |
| Webhook `message_status`             | `data.status: "failed"`, `data.errors[0].code: 131050`, cuando Meta rechaza |
| Webhook `user_preference.stopped`    | `data.waId`, `data.value: "stop"`, `data.timestamp`                         |
| Campaña                              | Destinatarios `skipped`, con el motivo en `errorMessage`                    |

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

## ¿Cómo corrijo el error 131050?

1. **Detén todos los envíos de marketing a este contacto.** Genuka WA clasifica el 131050 como
   `recipient_permanent`: nunca se reintenta.
2. **Registra la baja en tu propia herramienta** (CRM, base de clientes), para que sobreviva a una
   exportación o a una campaña preparada en otro lugar.
3. **Recibe los eventos `user_preference.stopped` y `user_preference.resumed`.** Un endpoint sin
   filtro de eventos ya los recibe; un endpoint filtrado debe agregarlos a su lista `events` con
   `PATCH /api/v1/webhooks/{id}`. Solo vuelve a dar de alta al contacto con un `resumed`.
4. **Trata `403 recipient_opted_out` como una respuesta normal**, no como una falla: el contacto
   sigue siendo alcanzable con una plantilla de utilidad y en respuesta a sus mensajes.

**Node.js**

```ts
// 1. Al enviar: un rechazo por baja no es un error por el que haya que alertar a nadie.
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. En tu ruta de webhook, una vez verificada la firma.
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
# En tu ruta de webhook, una vez verificada la firma.
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)
```

## ¿Cómo evito el error 131050?

* **Obtén un consentimiento explícito** antes de cualquier mensaje de marketing, indicando el
  nombre de tu empresa y lo que vas a enviar.
* **Escucha `user_preferences` desde el primer día**: una baja conocida por webhook evita el envío
  fallido; una conocida a través del 131050 llega cuando ya es tarde.
* **Crea tus plantillas con Genuka WA** (`POST /api/v1/templates`): así su categoría es conocida y
  se aplica el `403 recipient_opted_out` preventivo.
* **Envía menos, pero mejor.** Una baja es la respuesta de un cliente a mensajes que no quería; la
  frecuencia y la pertinencia son tus palancas.

## Códigos de error relacionados

* [131049](https://wa.genuka.com/es/docs/errors/131049): un mensaje de marketing retenido para este destinatario, pero
  solo de forma temporal; se puede reenviar después de 24 horas.
* [131026](https://wa.genuka.com/es/docs/errors/131026): el destinatario no recibe ningún mensaje, sea cual sea su
  categoría.
* [131047](https://wa.genuka.com/es/docs/errors/131047): la ventana de 24 horas está cerrada para un mensaje libre.

## Preguntas frecuentes

### ¿Puedo seguir enviando una confirmación de pedido a un contacto dado de baja?

Genuka WA no bloquea las plantillas `UTILITY` ni `AUTHENTICATION` para un contacto que se dio de
baja del marketing: el 131050 de Meta se refiere a los mensajes de marketing. La confirmación de
pedido debe ser entonces una verdadera plantilla de utilidad, no una promoción disfrazada.

### ¿La baja se aplica a un número o a toda la empresa?

Meta habla de mensajes de marketing "from your business" (de tu empresa). Genuka WA la registra por
cliente: abarca todos los números de ese cliente.

### ¿Qué pasa con una plantilla creada fuera de Genuka WA?

Genuka WA no conoce su categoría y la deja pasar. Si Meta informa un 131050, la baja se registra
igualmente: a partir de ese momento, tus campañas de marketing y las plantillas de marketing
creadas con Genuka WA excluirán a ese contacto. La plantilla desconocida, en cambio, sigue
llegando a Meta.

### ¿Cómo vuelve a darse de alta un contacto?

Reactivando en WhatsApp los mensajes de marketing de tu empresa. Meta envía entonces el webhook
`user_preferences` con el valor `resume`, que Genuka WA te reenvía como `user_preference.resumed`
y aplica a su registro.

## Fuentes

* [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)
