Error 131050 de WhatsApp: el usuario dejó de recibir marketing
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
(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).
¿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_preferencesde Meta (stoporesume) y cualquier 131050 informado por el webhook de estado de un envío. Un consentimiento solo puede provenir de unresume: un 131050 nunca se interpreta como consentimiento. - Envío individual: una plantilla
MARKETINGconocida por Genuka WA, dirigida a un contacto dado de baja, se rechaza antes de llegar a Meta, con403 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 comoskippedcon el motivo "Recipient opted out of marketing messages" y se cuentan en el camposkippedde la respuesta de lanzamiento. - Lo que no se bloquea: las plantillas
UTILITYyAUTHENTICATION, 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 |
{
"error": "recipient_opted_out",
"message": "This recipient opted out of marketing messages"
}¿Cómo corrijo el error 131050?
Detén todos los envíos de marketing a este contacto. Genuka WA clasifica el 131050 como
recipient_permanent: nunca se reintenta.
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.
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.
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.
// 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);
}¿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_preferencesdesde 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 el403 recipient_opted_outpreventivo. - 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: un mensaje de marketing retenido para este destinatario, pero solo de forma temporal; se puede reenviar después de 24 horas.
- 131026: el destinatario no recibe ningún mensaje, sea cual sea su categoría.
- 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
Error 131049 de WhatsApp: mensaje de marketing no entregado
Error 131049 de WhatsApp: Meta retuvo tu plantilla de marketing para mantener un buen nivel de interacción. El límite por usuario, y cuándo reenviar sin empeorar la situación.
Error 132000 de WhatsApp: número de variables incorrecto en la plantilla
Error 132000 de WhatsApp (Template Param Count Mismatch): las variables que enviaste no coinciden con la plantilla. Cómo contarlas y enviarlas correctamente.