# WhatsApp Module

## Descripcion

Integracion con WhatsApp Business API para comunicacion con clientes. Soporta envio y recepcion de mensajes de texto, multimedia y templates; gestion de contactos con opt-in/opt-out; automatizaciones; broadcasts masivos; y respuestas rapidas.

## Entidades

| Entidad | Schema | Descripcion |
|---------|--------|-------------|
| `WhatsAppAccount` | whatsapp.accounts | Cuentas de WhatsApp Business configuradas por tenant |
| `WhatsAppContact` | whatsapp.contacts | Contactos de WhatsApp con estado de conversacion y opt-in |
| `WhatsAppConversation` | whatsapp.conversations | Hilos de conversacion con ventana de 24h |
| `WhatsAppMessage` | whatsapp.messages | Mensajes enviados/recibidos con estado de entrega |
| `WhatsAppTemplate` | whatsapp.templates | Templates de mensajes aprobados por Meta |
| `WhatsAppQuickReply` | whatsapp.quick_replies | Respuestas rapidas predefinidas |
| `WhatsAppAutomation` | whatsapp.automations | Reglas de automatizacion de respuestas |
| `WhatsAppBroadcast` | whatsapp.broadcasts | Campanas de mensajes masivos |
| `WhatsAppBroadcastRecipient` | whatsapp.broadcast_recipients | Destinatarios de broadcasts |
| `MessageStatusUpdate` | whatsapp.message_status_updates | Historial de cambios de estado |

## Servicios

| Servicio | Responsabilidades |
|----------|-------------------|
| `WhatsAppService` | Gestion completa: cuentas, contactos, mensajes, templates; estadisticas; ventanas de conversacion |

## Endpoints

| Method | Path | Descripcion |
|--------|------|-------------|
| GET | `/accounts` | Lista cuentas del tenant |
| GET | `/accounts/active` | Lista cuentas activas |
| GET | `/accounts/:id` | Obtiene cuenta por ID |
| POST | `/accounts` | Registra nueva cuenta |
| PATCH | `/accounts/:id` | Actualiza cuenta |
| PATCH | `/accounts/:id/status` | Cambia estado de cuenta |
| GET | `/accounts/:id/stats` | Estadisticas de la cuenta |
| GET | `/accounts/:accountId/contacts` | Lista contactos de cuenta |
| GET | `/contacts/:id` | Obtiene contacto por ID |
| GET | `/accounts/:accountId/contacts/phone/:phoneNumber` | Busca contacto por telefono |
| POST | `/contacts` | Crea contacto |
| PATCH | `/contacts/:id` | Actualiza contacto |
| POST | `/contacts/:id/opt-in` | Registra opt-in |
| POST | `/contacts/:id/opt-out` | Registra opt-out |
| POST | `/contacts/:id/tags` | Agrega tag a contacto |
| DELETE | `/contacts/:id/tags/:tag` | Elimina tag de contacto |
| GET | `/accounts/:accountId/messages` | Lista mensajes de cuenta |
| GET | `/messages/:id` | Obtiene mensaje por ID |
| GET | `/contacts/:contactId/messages` | Historial de conversacion |
| POST | `/messages` | Envia mensaje |
| PATCH | `/messages/:id/status` | Actualiza estado de mensaje |
| GET | `/accounts/:accountId/templates` | Lista templates de cuenta |
| GET | `/accounts/:accountId/templates/approved` | Lista templates aprobados |
| GET | `/templates/:id` | Obtiene template por ID |
| POST | `/templates` | Crea template |
| PATCH | `/templates/:id` | Actualiza template |
| PATCH | `/templates/:id/status` | Actualiza estado de Meta |
| DELETE | `/templates/:id` | Desactiva template |

## Dependencias

- `common` - Utilidades compartidas
- `auth` - Contexto de tenant
- WhatsApp Business API (Meta)

## Configuracion

| Variable | Descripcion | Requerida |
|----------|-------------|-----------|
| Almacenado por cuenta | Access Token, Phone Number ID, Business Account ID | Si |

## Tipos de Mensaje

- `text` - Mensaje de texto
- `image` - Imagen con caption opcional
- `video` - Video
- `audio` - Audio/nota de voz
- `document` - Documento adjunto
- `sticker` - Sticker
- `location` - Ubicacion
- `contacts` - Tarjeta de contacto
- `interactive` - Botones y listas
- `template` - Template pre-aprobado
- `reaction` - Reaccion a mensaje

## Categorias de Templates

- `MARKETING` - Promociones y ofertas
- `UTILITY` - Notificaciones transaccionales
- `AUTHENTICATION` - Codigos de verificacion

## Ventana de Conversacion

WhatsApp permite enviar mensajes de texto libre solo dentro de una ventana de 24 horas despues del ultimo mensaje del cliente. Fuera de esta ventana, solo se pueden enviar templates aprobados.
