feat(whatsapp): enviar plantillas de notificación (donación / recurso / necesidad) e invitar a gestionar desde el bot

[vgpastor]

Contexto

Tenemos un bot de WhatsApp (repo GlobalEmergency/ResponseGrid-ChatBot, desplegado en srv07) conectado a esta API. Los usuarios pueden gestionar sus recursos, donaciones e inventarios desde el propio chat de WhatsApp (login por teléfono ya funcional vía /auth/trusted/login-by-phone, #315).

Queremos avisar proactivamente al usuario por WhatsApp cuando ocurre un evento en la web e invitarle a gestionarlo desde el bot. Para mensajes iniciados por el negocio (fuera de la ventana de 24 h) WhatsApp obliga a usar plantillas aprobadas. Las plantillas ya están creadas en Meta; falta que el backend las dispare cuando ocurre el evento.

Qué hay que implementar (backend)

Enviar la plantilla de WhatsApp correspondiente cuando se produce cada evento, al teléfono del usuario dueño del recurso/donación/necesidad, en su idioma (es/en):

Evento en la web	Plantilla	Variables del body
Usuario registra una donación	donacion_registrada	{{1}} = nombre del usuario · {{2}} = resumen de la donación (p. ej. "20 mantas y 10 cajas de agua")
Usuario da de alta un recurso (centro de acopio, logístico, etc.)	recurso_registrado	{{1}} = nombre · {{2}} = nombre del recurso
Se publica una necesidad	necesidad_publicada	{{1}} = nombre · {{2}} = resumen de la necesidad

Cada plantilla existe en español (es) e inglés (en) con el mismo name; se elige con language.code según el idioma del usuario. Todas llevan un botón quick-reply "Gestionar…" que el bot ya sabe atender (arranca el flujo de gestión en el mismo chat) — no hay que hacer nada del lado del bot.

Cómo se envía (WhatsApp Cloud API)

POST https://graph.facebook.com/v25.0/{PHONE_NUMBER_ID}/messages
Authorization: Bearer {WHATSAPP_TOKEN}
Content-Type: application/json

{
  "messaging_product": "whatsapp",
  "to": "<teléfono del usuario en formato internacional sin +, p. ej. 34612345678>",
  "type": "template",
  "template": {
    "name": "donacion_registrada",
    "language": { "code": "es" },          // "es" o "en" según el idioma del usuario
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "<nombre del usuario>" },
        { "type": "text", "text": "<resumen>" }
      ]}
    ]
  }
}

El botón quick-reply no necesita parámetros. Respuesta 200 con messages[].id = enviado.

Datos de configuración (a guardar como secretos/env, NO hardcodear)

• PHONE_NUMBER_ID: 1151382894730278 (número +1 555-938-6039, WABA "Response Grid" 1929490727714208).
• WHATSAPP_TOKEN: token de System User de la app de Meta (mismo que usa el bot; pedir al equipo de infra / vault). Permiso whatsapp_business_messaging.
• Versión de Graph API: v25.0.

Plantillas creadas en Meta (pendientes de aprobación al abrir este issue)

• donacion_registrada (es + en)
• recurso_registrado (es + en)
• necesidad_publicada (es + en)

Categoría UTILITY. Comprobar que están APPROVED antes de enviar (una plantilla no aprobada da error al enviar).

Consideraciones

• Opt-in / consentimiento: WhatsApp exige que el usuario haya dado opt-in para recibir mensajes de negocio. Enviar solo a usuarios con teléfono válido y que hayan aceptado recibir notificaciones por WhatsApp. Definir/registrar ese opt-in.
• Idioma: usar la preferencia de idioma del usuario (o la de la emergencia); por defecto es.
• Solo si hay teléfono: no todos los usuarios tendrán teléfono; enviar solo cuando exista.
• Manejo de errores: logear fallos de la Graph API. Códigos habituales: 131030 (destinatario no permitido — solo en modo test), 131047 (fuera de ventana, se resuelve con plantilla), 132000 (plantilla no encontrada/no aprobada), 100 (parámetros). No romper el flujo del evento si el envío falla (enviar en background / cola).
• Idempotencia: evitar reenvíos duplicados si el evento se procesa más de una vez.
• Dónde engancharlo: en los casos de uso / eventos de dominio de donación creada, recurso creado y necesidad publicada. Idealmente un pequeño servicio WhatsAppNotifier desacoplado (puerto de salida) que se llame desde esos eventos, en background.

Qué NO hay que hacer

• El bot ya recibe el toque del botón y gestiona en el chat (repo ResponseGrid-ChatBot). Este issue es solo el envío desde el backend.
• Las plantillas ya están creadas en Meta; no hay que crearlas.