promocion-por-whatsapp/README.md

Promoción por WhatsApp

Sistema automatizado de promoción vía WhatsApp utilizando n8n, Supabase y WhatsApp Cloud API.

---

Descripción General

Este flujo administra la interacción completa con usuarios mediante WhatsApp para registrar participantes en una promoción.

Incluye:

• Validación de mensajes entrantes
• Gestión de consentimiento de privacidad y marketing
• Registro de información del usuario
• Validación y registro de códigos de productos
• Control de estados del usuario
• Prevención de fraude y spam

---

Tecnologías Utilizadas

• n8n
• Supabase
• PostgreSQL
• WhatsApp Cloud API

---

Arquitectura del Flujo

El sistema funciona mediante una máquina de estados (state machine) donde cada usuario tiene un estado actual que determina la siguiente acción del flujo.

Estados Disponibles

• CONSENT_PRIVACY
• CONSENT_MARKETING
• ASK_NAME
• ASK_ID
• ASK_EMAIL
• ASK_LOCATION
• ASK_CODE
• MENU_AFTER_CODE
• DONE

---

Flujo General

1. Recepción y Normalización

El flujo recibe mensajes desde WhatsApp y:

• Extrae el contenido del mensaje
• Detecta el tipo de mensaje:
  • Texto
  • Imagen
  • Interactivo
• Normaliza caracteres y acentos
• Filtra números bloqueados

---

2. Validación Inicial

Si el mensaje no contiene contenido válido:

• El flujo se detiene automáticamente

---

3. Creación o Consulta del Usuario

Se ejecuta la función RPC:

ensure_user_wa

Esta función:

• Crea el usuario si no existe
• Consulta el estado actual del usuario
• Devuelve out_state

---

Router de Estados

Según el valor de out_state, el flujo dirige al usuario a la etapa correspondiente.

Estado	Acción
CONSENT_PRIVACY	Solicitar aceptación de privacidad
CONSENT_MARKETING	Solicitar consentimiento marketing
ASK_NAME	Solicitar nombre completo
ASK_ID	Solicitar identificación
ASK_EMAIL	Solicitar correo electrónico
ASK_LOCATION	Solicitar ubicación
ASK_CODE	Solicitar código del producto
MENU_AFTER_CODE	Mostrar menú posterior
DONE	Finalizar flujo

---

Consentimientos

Consentimiento de Privacidad

El usuario puede responder:

• SI
• NO

Comportamiento

• SI → continúa el flujo
• NO → se detiene el avance

RPC utilizada

set_consent_privacy_wa

---

Consentimiento de Marketing

El usuario puede responder:

• SI
• NO

Comportamiento

• SI → opt-in marketing
• NO → opt-out marketing

RPC utilizada

set_consent_marketing_wa

---

Captura de Datos

Nombre

Validaciones

• Mínimo 6 caracteres
• Debe contener al menos 2 palabras
• Solo letras permitidas

RPC

set_name_wa

---

Identificación

Validaciones

• Campo obligatorio
• No vacío

RPC

set_id_wa

---

Email

Opciones permitidas

• Correo válido
• NO para omitir

Validación

Se utiliza validación mediante regex para verificar formato email.

RPC

set_email_wa

---

Ubicación

Validación

• Debe pertenecer a una lista cerrada de departamentos

RPC

set_location_wa

---

Registro de Códigos

Formato del Código

El sistema valida códigos con la siguiente estructura:

• 4 números
• 1 letra
• 3 números
• marcador (C, S, M, T)
• 1 número

Ejemplo

1234A567C9

---

Registro del Código

RPC utilizada

register_lot_code

---

Posibles Respuestas

Respuesta	Descripción
❌ Código inválido	Formato incorrecto
⚠️ Código duplicado	Código ya registrado
🚫 Límite diario	Usuario alcanzó límite
🚫 Bloqueo por fraude	Detección antifraude
🎉 Código exitoso	Registro correcto y generación de cupones

---

Menú Posterior al Registro

Después de registrar un código, el usuario puede elegir:

1. Seguir ingresando códigos
2. Salir

Opción 1

El estado cambia a:

ASK_CODE

Opción 2

El estado cambia a:

DONE

---

Reinicio del Flujo

Si el usuario envía alguno de estos mensajes:

• hola
• buenas
• hello

El sistema reinicia el flujo mediante:

restart_wa

---

Tipos de Mensajes

El flujo soporta:

• Texto simple
• Botones interactivos
• Listas interactivas

---

API Utilizada

• WhatsApp Cloud API

---

Características Técnicas

• Arquitectura basada en estados
• Integración con Supabase mediante RPC
• Manejo intensivo de nodos Code
• Normalización de texto y caracteres
• Sistema antifraude
• Validaciones avanzadas
• Manejo de errores

---

Estructura del Proyecto

Base de datos Supabase/
├── Base de datos Postgre Presto.txt
├── Triggers.png
└── pg-dump-postgres1-1776492006.dmp

Flujo n8n/
├── Flujo WhatsApp.docx
└── Flujo con WSP.json