# Error 131047 de WhatsApp: Re-engagement message — solución

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

> El error 131047 de WhatsApp (Re-engagement message) significa que la ventana de 24 horas está cerrada. Por qué Meta rechaza el mensaje libre y cómo pasar a una plantilla.

El error 131047 de WhatsApp significa que pasaron más de 24 horas desde el último mensaje que te
envió el destinatario: la ventana de atención al cliente está cerrada y solo una plantilla
aprobada puede llegarle todavía. La solución es sencilla: reenvía el contenido como plantilla y
vuelve a los mensajes libres en cuanto el cliente responda.

## ¿Qué significa el error 131047?

> "More than 24 hours have passed since the recipient last replied to the sender number."
> — [Meta, códigos de error de la Cloud API](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

La solución que sugiere Meta cabe en una línea: "Send the recipient a template message instead."
(Envía al destinatario un mensaje de plantilla en su lugar). En el campo `message` de la
respuesta, el código va seguido de su título, "Re-engagement message"
([lista de 360dialog](https://docs.360dialog.com/docs/support/api-error-message-list)); Meta
advierte que estos títulos dejarán de usarse, así que no programes en función de ellos.

La regla detrás del código es la **ventana de atención al cliente**. Cuando un usuario te escribe
o te llama, se inicia un temporizador de 24 horas; cada nuevo mensaje o llamada suya lo reinicia a
24 horas. Mientras corre, puedes enviar cualquier mensaje libre: texto, imagen, botones, lista.
Cuando vence, solo pasan las plantillas aprobadas
([Meta, Send messages](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)).

## ¿Cuándo aparece el error 131047?

* **Un mensaje libre enviado demasiado tarde**: la respuesta del soporte sale a la mañana
  siguiente, cuando el cliente escribió a las 8 a. m. del día anterior.
* **Un primer mensaje libre** a alguien que nunca te escribió: no hay ninguna ventana.
* **Un Flow enviado como mensaje interactivo** fuera de la ventana: la misma regla, consulta
  [Flows en la biblioteca](https://wa.genuka.com/sdk/flows).
* **Bloquear a un usuario**: Meta solo te permite bloquear un número que te escribió en las
  últimas 24 horas
  ([Meta, Block users](https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users)).
  `POST /api/v1/blocked-users` informa entonces el fallo número por número, con el código 131047 y
  el mensaje "Failed to block due to re-engagement check failed", que registramos en un número en
  producción el 13 de agosto de 2026.

### ¿Por qué la API responde 200 si el mensaje nunca llega?

Es la principal trampa de este código. El 13 de agosto de 2026, en un número en producción,
enviamos tres textos libres fuera de la ventana: Meta respondió **HTTP 200 con un `wamid` válido**
para cada uno, y ninguno se entregó. Ningún 131047 durante la llamada. Una plantilla enviada al
mismo destinatario justo después llegó de inmediato.

Según el caso, el error vuelve durante la llamada, más tarde por el webhook de estado, o nunca. Por
eso Genuka WA comprueba la ventana por su lado antes de cada mensaje libre y lo indica en la
respuesta, sin bloquear el envío:

```json title="200 — POST /api/v1/messages fuera de la ventana"
{
  "data": {
    "messageId": "wamid.HBgLMjM3...",
    "warning": {
      "code": "outside_service_window",
      "message": "This contact last messaged you at 2026-10-06T08:12:44.000Z, more than 24 hours ago, so the service window is closed. Meta will most likely drop this message; send an approved template instead."
    }
  }
}
```

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

| Canal                                      | Qué recibes                                                                                                                                                                    |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Respuesta `200` de `POST /api/v1/messages` | `data.warning.code`: `outside_service_window` (último mensaje entrante hace más de 24 h) o `unverified_service_window` (ningún mensaje entrante registrado para este contacto) |
| Respuesta `400` de `POST /api/v1/messages` | `"error": "send_needs_template"`, `meta.code: 131047`, cuando Meta rechaza durante la llamada                                                                                  |
| Webhook `message_status`                   | `data.status: "failed"` y `data.errors[0].code: 131047`                                                                                                                        |
| Panel, sección Bandeja de entrada          | La burbuja fallida; "Ver por qué" muestra el código y los detalles de Meta                                                                                                     |

El `warning` nunca es un rechazo: nuestro registro de la ventana proviene del flujo de webhooks, y
una caída de nuestro lado no debe bloquear un envío que Meta habría entregado. La decisión es tuya.

## ¿Cómo corrijo el error 131047?

1. **No reenvíes el mensaje libre.** Fallará exactamente igual. Genuka WA clasifica el 131047 como
   `needs_template` y nunca lo reintenta, ni en un envío individual ni en una campaña.
2. **Elige una plantilla aprobada** del tipo adecuado: `UTILITY` para información de pedidos o de
   cuenta, `MARKETING` para una promoción. La lista está en `GET /api/v1/templates?status=approved`
   para las plantillas creadas con Genuka WA; las creadas en el Administrador de WhatsApp (en inglés, *WhatsApp Manager*) no aparecen, pero se
   envían de la misma manera.
3. **Envíala con el campo `template`** en el mismo endpoint, indicando siempre `language`.
4. **Vuelve a los mensajes libres cuando el cliente responda.** Su respuesta abre una nueva ventana
   de 24 horas.

**curl**

```bash
curl -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "con_1",
    "to": "+237690000001",
    "template": { "name": "order_update", "language": "en", "body": ["Awa", "ORD-1042"] }
  }'
# { "data": { "messageId": "wamid.HBg..." } }
```

**Node.js**

```ts
const API = "https://wa.genuka.com/api/v1";
const WINDOW_MS = 24 * 60 * 60 * 1000;

async function post(path: string, body: unknown) {
  const response = await fetch(`${API}${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });
  const json = await response.json();
  if (!response.ok) throw Object.assign(new Error(json.message ?? json.error), json);
  return json.data as { messageId: string; warning?: { code: string; message: string } };
}

// lastInboundAt: cuándo te escribió este contacto por última vez, actualizado por tus webhooks.
export async function notify(to: string, text: string, lastInboundAt: Date | null) {
  const windowOpen = lastInboundAt !== null && Date.now() - lastInboundAt.getTime() < WINDOW_MS;
  const template = {
    connectionId: "con_1",
    to,
    template: { name: "order_update", language: "en", body: ["Awa", "ORD-1042"] },
  };
  if (!windowOpen) return post("/messages", template);

  try {
    return await post("/messages", { connectionId: "con_1", to, text });
  } catch (error) {
    if ((error as { error?: string }).error === "send_needs_template") return post("/messages", template);
    throw error;
  }
}
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://wa.genuka.com/api/v1/messages",
    headers={
        "Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}",
        "User-Agent": "acme-crm/1.0 (+https://example.com)",
    },
    json={
        "connectionId": "con_1",
        "to": "+237690000001",
        "template": {"name": "order_update", "language": "en", "body": ["Awa", "ORD-1042"]},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json()["data"]["messageId"])
```

**PHP**

```php
<?php
$ch = curl_init("https://wa.genuka.com/api/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERAGENT => "acme-crm/1.0 (+https://example.com)",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("GENUKA_WA_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "connectionId" => "con_1",
        "to" => "+237690000001",
        "template" => ["name" => "order_update", "language" => "en", "body" => ["Awa", "ORD-1042"]],
    ]),
]);
$json = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $json["data"]["messageId"] ?? $json["error"];
```

Si el mensaje libre ya salió y un webhook `message_status` vuelve como `failed` con el código
131047, se aplica la misma regla: reenvía el contenido como plantilla, una sola vez.

## ¿Cómo evito el error 131047?

* **Lleva tu propio reloj de la ventana.** Cada mensaje entrante llega a tu webhook con el
  remitente y una marca de tiempo: guarda el más reciente por contacto y elige plantilla o mensaje
  libre **antes** de enviar.
* **Lee `data.warning`.** Cuando aparece, asume que el mensaje libre probablemente no se entregará
  y vigila su estado.
* **Usa una plantilla para todo lo que inicias tú**: confirmación de pedido, recordatorio de cita,
  código de inicio de sesión. La [guía de notificaciones de pedidos](https://wa.genuka.com/es/docs/guides/order-notifications)
  se basa en ese principio.
* **Ten una plantilla de reactivación** en la categoría `UTILITY`, breve, que invite al cliente a
  responder para que la conversación se reabra.

## Códigos de error relacionados

* [132001](https://wa.genuka.com/es/docs/errors/132001): la plantilla que elegiste para reactivar la conversación no
  existe en ese idioma o no está aprobada.
* [132000](https://wa.genuka.com/es/docs/errors/132000): la plantilla se encuentra, pero la cantidad de variables no
  coincide.
* [131050](https://wa.genuka.com/es/docs/errors/131050): el destinatario dejó de recibir mensajes de marketing; una
  plantilla `MARKETING` tampoco pasará.
* [131026](https://wa.genuka.com/es/docs/errors/131026): el destinatario no puede recibir ningún mensaje, ni siquiera
  plantillas.

## Preguntas frecuentes

### ¿Las 24 horas cuentan desde mi último mensaje o desde el suyo?

Desde el suyo. La ventana empieza con el último mensaje o llamada del **cliente**; los mensajes que
tú envías no la prolongan.

### ¿Una plantilla reabre la ventana de 24 horas?

No, la reabre la respuesta del cliente. Meta lo detalla para las plantillas de marketing: si el
usuario responde, se inicia una ventana de 24 horas de atención al cliente
([Meta, Per-user marketing limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)).

### ¿Se cobra un mensaje libre enviado dentro de la ventana?

Meta lo marca como `free_customer_service` en el webhook de estado: un mensaje que no es de
plantilla enviado dentro de una ventana de atención al cliente es gratuito, igual que una
plantilla `UTILITY` enviada dentro de la ventana
([Meta, webhook de estado](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)).
Meta factura las plantillas directamente a la cuenta de WhatsApp Business del cliente; Genuka WA
no agrega ningún recargo.

### ¿Puedo bloquear un número que nunca me escribió?

No. Bloquear requiere un mensaje entrante de las últimas 24 horas; de lo contrario, Meta responde
131047 para ese número. `POST /api/v1/blocked-users` devuelve `207` cuando algunos números se
bloquearon y `422` cuando no se bloqueó ninguno.

## Fuentes

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Send messages, customer service windows](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/send-messages#customer-service-windows)
* [Meta — Status webhook reference](https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/status)
* [Meta — Per-user marketing template message limits](https://developers.facebook.com/documentation/business-messaging/whatsapp/templates/marketing-templates/per-user-limits)
* [Meta — Block users](https://developers.facebook.com/documentation/business-messaging/whatsapp/block-users)
* [360dialog — API error message list](https://docs.360dialog.com/docs/support/api-error-message-list)
