usite-sas-bic/sirpremiumv2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

up

Browse Source
This commit is contained in:
Lizandro Guarnizo
2026-04-24 21:40:10 -05:00
parent 877a0d393a
commit 148fa6b9f9
36 changed files with 3037 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
public/DOCUMENTACION_BOT_WHATSAPP.md
+916
View File
@@ -0,0 +1,916 @@
# Documentación Técnica — Bot WhatsApp Cloud API
> **Propósito:** Esta documentación está pensada para ser entregada a otra IA o equipo de desarrollo para reimplementar el bot en cualquier lenguaje/plataforma, con toda la información necesaria sobre flujos, APIs, base de datos y contratos de datos.
---
## 1. Resumen del sistema
El sistema es un **bot de WhatsApp** basado en la **WhatsApp Cloud API (Meta/Facebook Graph API v22.0)**. Permite:
- Recibir y procesar mensajes entrantes mediante un **webhook HTTP**.
- Responder automáticamente con textos, menús, botones interactivos, listas y archivos multimedia.
- Transferir la conversación a un asesor humano.
- Enviar **plantillas de mensaje** aprobadas por Meta.
- Enviar **mensajes programados**.
- Gestionar **términos y condiciones** (envío y aceptación).
**Lenguaje original:** PHP 8.x
**Base de datos:** MySQL / MariaDB
**Cola / Workers:** Worker PHP con cron (no RabbitMQ ni Redis, aunque se usa Redis como opción para rate-limit).
---
## 2. Credenciales y configuración requerida
Todas las credenciales se almacenan en la **tabla `system_config`** de la base de datos (no en código duro). También se cargan desde variables de entorno / archivo `.env`.
### 2.1 Variables de entorno (`.env`)
```
DB_HOST=mysql # Host de la base de datos
DB_PORT=3306
DB_NAME=usite_whatsapp_bot
DB_USER=usite_whatsapp_user
DB_PASS=<password>
DB_CHARSET=utf8mb4
```
### 2.2 Configuración de WhatsApp (en tabla `system_config`)
| `config_key` | Descripción | Ejemplo |
|----------------------|-----------------------------------------------------------------|--------------------------------------------------|
| `whatsapp_token` | Token de acceso permanente de la App de Meta | `EAABz...` |
| `phone_number_id` | ID del número de teléfono de la cuenta de WhatsApp Business | `123456789012345` |
| `whatsapp_api_url` | URL base de la Graph API | `https://graph.facebook.com/v22.0/` |
| `webhook_verify_token` | Token secreto para verificar el webhook (GET de Meta) | `mi_token_secreto` |
| `bot_enabled` | Si el bot responde automáticamente (`1`/`0`) | `1` |
| `business_hours_*` | Horarios de atención (ver sección 8) | — |
| `terms_message` | Mensaje de términos y condiciones que se envía al usuario | texto libre |
---
## 3. API de WhatsApp consumida
**Base URL:** `https://graph.facebook.com/v22.0/{phone_number_id}/`
**Autenticación:** Header `Authorization: Bearer {whatsapp_token}`
**Formato:** JSON (Content-Type: `application/json`) salvo para subida de archivos (multipart/form-data).
### 3.1 Enviar mensajes — `POST /{phone_number_id}/messages`
Todos los tipos de mensaje tienen el campo común:
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX"
}
```
---
#### 3.1.1 Mensaje de texto
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "text",
"text": {
"body": "Hola, ¿en qué te podemos ayudar?"
}
}
```
---
#### 3.1.2 Mensaje de plantilla (template)
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "template",
"template": {
"name": "nombre_plantilla",
"language": { "code": "es" },
"components": [
{
"type": "header",
"parameters": [
{ "type": "text", "text": "Valor del header" }
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "parameter_name": "nombre", "text": "Juan" },
{ "type": "text", "parameter_name": "fecha", "text": "20/04/2026" }
]
}
]
}
}
```
> **Nota sobre parámetros nombrados vs posicionales:**
> - Si la plantilla usa variables `{{nombre}}` (nombradas): incluir `"parameter_name": "nombre"`.
> - Si la plantilla usa variables `{{1}}`, `{{2}}` (posicionales): omitir `parameter_name`, usar solo `"type": "text", "text": "valor"` en orden.
---
#### 3.1.3 Mensaje interactivo — Botones
```json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "57300XXXXXXX",
"type": "interactive",
"interactive": {
"type": "button",
"header": { "type": "text", "text": "Encabezado opcional" },
"body": { "text": "Selecciona una opción:" },
"footer": { "text": "Pie de página opcional" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "btn_1", "title": "Opción 1" } },
{ "type": "reply", "reply": { "id": "btn_2", "title": "Opción 2" } }
]
}
}
}
```
> Máximo **3 botones**. El `title` no puede superar 20 caracteres.
---
#### 3.1.4 Mensaje interactivo — Lista
```json
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "57300XXXXXXX",
"type": "interactive",
"interactive": {
"type": "list",
"body": { "text": "Elige una opción de la lista:" },
"action": {
"button": "Ver opciones",
"sections": [
{
"title": "Sección 1",
"rows": [
{ "id": "row_1", "title": "Opción 1", "description": "Descripción opcional" },
{ "id": "row_2", "title": "Opción 2" }
]
}
]
}
}
}
```
---
#### 3.1.5 Mensaje de imagen
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "image",
"image": {
"link": "https://ejemplo.com/imagen.jpg",
"caption": "Pie de foto opcional"
}
}
```
---
#### 3.1.6 Mensaje de video
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "video",
"video": {
"link": "https://ejemplo.com/video.mp4",
"caption": "Descripción del video"
}
}
```
---
#### 3.1.7 Mensaje de audio
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "audio",
"audio": {
"link": "https://ejemplo.com/audio.mp3"
}
}
```
> Para notas de voz, el archivo debe ser `.ogg` con códec **OPUS** y subirse primero al media endpoint.
---
#### 3.1.8 Mensaje de documento
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "document",
"document": {
"link": "https://ejemplo.com/archivo.pdf",
"filename": "resultados.pdf",
"caption": "Tus resultados de laboratorio"
}
}
```
---
#### 3.1.9 Marcar mensaje como leído — `POST /{phone_number_id}/conversations`
```json
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.XXXXX"
}
```
---
#### 3.1.10 Enviar reacción a un mensaje
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "reaction",
"reaction": {
"message_id": "wamid.XXXXX",
"emoji": "👍"
}
}
```
---
### 3.2 Subir archivo multimedia — `POST /{phone_number_id}/media`
**Content-Type:** `multipart/form-data`
Campos del formulario:
| Campo | Valor |
|---------------------|------------------------------------------|
| `messaging_product` | `whatsapp` |
| `file` | Archivo binario |
| `type` | MIME type (ej: `image/jpeg`, `video/mp4`) |
**Respuesta exitosa:**
```json
{ "id": "1234567890123456" }
```
Una vez obtenido el `id`, se puede usar en mensajes así:
```json
{
"messaging_product": "whatsapp",
"to": "57300XXXXXXX",
"type": "image",
"image": { "id": "1234567890123456" }
}
```
---
### 3.3 Obtener URL de un media — `GET /{media_id}`
**Respuesta:**
```json
{
"url": "https://lookaside.fbsbx.com/whatsapp_business/attachments/?mid=...",
"mime_type": "image/jpeg",
"sha256": "...",
"file_size": 12345,
"id": "1234567890123456",
"messaging_product": "whatsapp"
}
```
Luego descargar esa URL con el mismo Bearer token.
---
### 3.4 Gestión de plantillas — `GET /{waba_id}/message_templates`
```
GET https://graph.facebook.com/v22.0/{WABA_ID}/message_templates
Authorization: Bearer {token}
```
**Parámetros opcionales:** `?name=nombre_plantilla&status=APPROVED`
---
## 4. Webhook — Recepción de mensajes
### 4.1 Verificación del webhook (GET)
Meta envía un GET para verificar el endpoint:
```
GET /api/webhook.php?hub.mode=subscribe&hub.verify_token=TOKEN&hub.challenge=CHALLENGE
```
El sistema debe responder con el valor de `hub.challenge` si `hub.verify_token` coincide con `WEBHOOK_VERIFY_TOKEN`.
---
### 4.2 Payload de mensaje entrante (POST)
```json
{
"object": "whatsapp_business_account",
"entry": [
{
"id": "WABA_ID",
"changes": [
{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "57300XXXXXXX",
"phone_number_id": "PHONE_NUMBER_ID"
},
"contacts": [
{
"profile": { "name": "Nombre del Contacto" },
"wa_id": "57300XXXXXXX"
}
],
"messages": [
{
"from": "57300XXXXXXX",
"id": "wamid.XXXXXXXXXXXXX",
"timestamp": "1713900000",
"type": "text",
"text": { "body": "Hola" }
}
]
}
}
]
}
]
}
```
**Tipos de mensaje posibles en el campo `type`:**
| `type` | Estructura del mensaje |
|--------------|-------------------------------------------------------------|
| `text` | `message.text.body` |
| `image` | `message.image.id`, `message.image.mime_type` |
| `video` | `message.video.id`, `message.video.mime_type` |
| `audio` | `message.audio.id`, `message.audio.voice` (bool) |
| `document` | `message.document.id`, `document.filename`, `document.mime_type` |
| `sticker` | `message.sticker.id` |
| `location` | `message.location.latitude`, `message.location.longitude` |
| `interactive`| `message.interactive.type` = `list_reply` o `button_reply` |
| `reaction` | `message.reaction.emoji`, `message.reaction.message_id` |
**Respuesta de acceso interactivo:**
```json
{
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "row_1",
"title": "Opción 1",
"description": "descripción"
}
}
}
```
---
### 4.3 Normalización interna de mensajes interactivos
El webhook normaliza las respuestas de lista/botón a texto plano para que el BotService las procese como si fueran texto:
- Si `title` empieza con un número (`"1. Opción"`), se extrae solo el número.
- Si no, se usa el `title` completo.
---
## 5. Flujo de procesamiento de mensajes
```
WhatsApp Cloud API
│
▼
POST /api/webhook.php
│
├─ Verificar duplicado (por message_id en conversations)
├─ Obtener/crear usuario en tabla `users`
├─ Guardar nombre del contacto si no tenía
│
▼
WhatsAppWebhook::processConversations()
│
├─ Extraer tipo de mensaje y contenido
├─ Guardar mensaje en tabla `conversations` (direction: incoming)
│
▼
BotService::processMessage($user, $messageText, $messageType)
│
├─ 1. Adquirir advisory lock por usuario (MySQL GET_LOCK) → evita race conditions
├─ 2. Si usuario bloqueado → descartar
├─ 3. Si usuario in_service (atendido por asesor) → descartar
├─ 4. maybeResetConversationAfterIdle() → reinicia si inactividad > 6h
├─ 5. Flujo de Términos:
│ ├─ Si terms_pending → processTermsResponse()
│ └─ Si needsTermsAcceptance() → sendTermsMessage()
├─ 6. Si 'isNewUser' → sendWelcomeMessage()
├─ 7. Si usuario escribe "enviado/a/os/as" → requestAdvisor()
├─ 8. processSpecialCommands() (MENU, ATRÁS, ASESOR, etc.)
├─ 9. Si on_hold activo y no expiró → notificar y retornar
├─10. Si advisor_requested activo → solo navegación explícita
├─11. Si bot_paused_until activo → solo navegación explícita
├─12. Si bot_enabled=false → solo comandos explícitos
├─13. Si current_menu_id → processMenuSelection()
└─14. Fallback → sendDefaultNoMatch()
```
---
## 6. Comandos especiales del bot
Los usuarios pueden escribir estas palabras clave en cualquier momento:
| Palabra clave | Acción |
|----------------------------------------|--------------------------------------------|
| `menu`, `menú`, `inicio` | Mostrar menú principal |
| `atras`, `atrás`, `volver`, `back` | Retroceder al menú anterior |
| `asesor`, `agente`, `humano` | Solicitar atención humana |
| `enviado`, `enviada`, `enviados`, `enviadas` | Indicar que se envió documentación — transfiere a asesor |
| Número (`1`, `2`, `3`…) | Seleccionar opción de menú activo |
---
## 7. Base de datos — Tablas principales del bot
### 7.1 `users` — Usuarios (contactos de WhatsApp)
| Campo | Tipo | Descripción |
|---------------------|-----------------------|----------------------------------------------------|
| `id` | INT AUTO_INCREMENT | Clave primaria |
| `phone_number` | VARCHAR(20) UNIQUE | Número en formato internacional sin `+` (ej: `573001234567`) |
| `name` | VARCHAR(100) | Nombre del contacto (viene del perfil de WhatsApp) |
| `status` | ENUM | `active`, `blocked`, `inactive` |
| `current_menu_id` | INT NULL | FK → `menus.id` — menú donde está el usuario |
| `current_step` | INT DEFAULT 0 | Paso dentro del flujo actual |
| `session_data` | TEXT (JSON) | Datos temporales de sesión |
| `welcome_sent_at` | DATETIME | Última vez que se envió el mensaje de bienvenida |
| `in_service` | TINYINT(1) | `1` = está siendo atendido por un asesor |
| `in_service_by` | INT NULL | FK → `admin_users.id` — asesor que lo atiende |
| `on_hold` | TINYINT(1) | `1` = el asesor lo puso en espera |
| `bot_paused_until` | DATETIME NULL | El bot está pausado hasta esta fecha/hora |
| `advisor_requested` | TINYINT(1) | `1` = el usuario solicitó asesor |
| `bot_enabled` | TINYINT(1) DEFAULT 1 | Si el bot responde a este usuario |
| `terms_pending` | TINYINT(1) | `1` = esperando respuesta de términos |
| `terms_accepted_at` | DATETIME | Cuándo aceptó los términos |
| `terms_version_id` | INT NULL | FK → `terms_versions.id` |
| `created_at` | TIMESTAMP | Fecha de creación |
| `updated_at` | TIMESTAMP | Última actualización |
---
### 7.2 `conversations` — Mensajes
| Campo | Tipo | Descripción |
|--------------------------|-----------------|-----------------------------------------------------------|
| `id` | INT | Clave primaria |
| `user_id` | INT | FK → `users.id` |
| `message_id` | VARCHAR(255) | ID único del mensaje en WhatsApp (`wamid.XXX`) |
| `reply_to_message_id` | VARCHAR(255) | ID del mensaje al que responde |
| `reaction_to_message_id` | VARCHAR(255) | ID del mensaje al que se reaccionó |
| `reaction_emoji` | VARCHAR(64) | Emoji de la reacción |
| `direction` | ENUM | `incoming` (usuario→bot) / `outgoing` (bot→usuario) |
| `message_type` | VARCHAR(32) | `text`, `image`, `video`, `audio`, `document`, `reaction`|
| `content` | TEXT | Contenido del mensaje (texto o JSON para multimedia/sistema) |
| `media_url` | TEXT | URL pública del archivo |
| `whatsapp_media_id` | VARCHAR(255) | ID del media en WhatsApp |
| `local_file` | VARCHAR(255) | Ruta local del archivo descargado |
| `local_thumb` | VARCHAR(255) | Ruta local del thumbnail |
| `media_storage` | VARCHAR(50) | Dónde se almacena (`local`, `whatsapp`, etc.) |
| `status` | VARCHAR(32) | `received`, `sent`, `delivered`, `read`, `failed` |
| `is_read` | TINYINT(1) | Si el admin marcó la conversación como leída |
| `filename` | VARCHAR(255) | Nombre del archivo adjunto |
| `mime_type` | VARCHAR(100) | MIME type del archivo |
| `created_at` | TIMESTAMP | Fecha del mensaje |
---
### 7.3 `menus` — Menús del bot
| Campo | Tipo | Descripción |
|-----------------|---------------|----------------------------------------------------------|
| `id` | INT | Clave primaria |
| `name` | VARCHAR(255) | Nombre interno del menú |
| `title` | VARCHAR(255) | Título que se muestra al usuario |
| `message` | TEXT | Texto del menú completo |
| `parent_id` | INT NULL | FK → `menus.id` — menú padre (para navegación ATRÁS) |
| `is_main` | TINYINT(1) | `1` = es el menú principal |
| `is_active` | TINYINT(1) | `1` = activo |
| `sort_order` | INT | Orden de presentación |
| `created_at` | TIMESTAMP | |
---
### 7.4 `menu_options` — Opciones de menú
| Campo | Tipo | Descripción |
|-----------------|---------------|----------------------------------------------------------------|
| `id` | INT | Clave primaria |
| `menu_id` | INT | FK → `menus.id` |
| `option_number` | INT | Número que el usuario debe escribir (1, 2, 3…) |
| `title` | VARCHAR(255) | Texto de la opción |
| `action_type` | ENUM | `submenu`, `message`, `template`, `url`, `advisor`, `flow` |
| `action_value` | TEXT | Depends en `action_type`: ID de submenú, texto, nombre de plantilla, URL |
| `is_active` | TINYINT(1) | `1` = activa |
| `sort_order` | INT | Orden |
---
### 7.5 `message_templates` — Plantillas
| Campo | Tipo | Descripción |
|----------------------|---------------|----------------------------------------------------------------|
| `id` | INT | Clave primaria |
| `name` | VARCHAR(255) | Nombre interno |
| `template_name` | VARCHAR(255) | Nombre en Meta (slug, sin espacios) |
| `language_code` | VARCHAR(10) | Idioma (`es`, `en`, etc.) |
| `status` | ENUM | `pending`, `approved`, `rejected`, `paused` |
| `body_text` | TEXT | Cuerpo del template con variables `{{1}}` o `{{nombre}}` |
| `header_type` | ENUM | `text`, `image`, `video`, `document` |
| `header_text` | VARCHAR(255) | Texto del header si aplica |
| `footer_text` | VARCHAR(255) | Pie del mensaje |
| `components` | LONGTEXT JSON | Componentes completos del template tal como los devuelve Meta |
| `example_parameters` | LONGTEXT JSON | Ejemplos de valores para las variables |
| `created_at` | TIMESTAMP | |
| `updated_at` | TIMESTAMP | |
---
### 7.6 `autoresponses` — Respuestas automáticas por keyword
| Campo | Tipo | Descripción |
|-----------------|-|-----------------------------------------------------------------|
| `id` | INT | Clave primaria |
| `trigger_type` | ENUM | `keyword`, `contains`, `exact`, `welcome`, `default` |
| `trigger_value` | TEXT | Palabras clave separadas por coma |
| `response_text` | TEXT | Texto de la respuesta |
| `response_type` | ENUM | `text`, `template`, `menu` |
| `template_name` | VARCHAR(255) | Nombre de la plantilla si `response_type = template` |
| `menu_id` | INT NULL | ID del menú si `response_type = menu` |
| `priority` | INT | Prioridad (mayor número = mayor prioridad) |
| `is_active` | TINYINT(1) | `1` = activa |
---
### 7.7 `scheduled_messages` — Mensajes programados
| Campo | Tipo | Descripción |
|-----------------------|---------------|-----------------------------------------------------------|
| `id` | INT | Clave primaria |
| `user_id` | INT | FK → `users.id` |
| `template_id` | INT NULL | FK → `message_templates.id` |
| `template_name` | VARCHAR(100) | Nombre de la plantilla |
| `template_language` | VARCHAR(10) | Idioma de la plantilla |
| `template_parameters` | LONGTEXT JSON | Parámetros para las variables de la plantilla |
| `message_type` | ENUM | `text`, `template` |
| `message_content` | TEXT | Texto si `message_type = text` |
| `scheduled_date` | DATE | Fecha programada |
| `scheduled_time` | TIME | Hora programada |
| `status` | ENUM | `pending`, `sent`, `failed`, `cancelled` |
| `sent_at` | DATETIME | Cuándo se envió efectivamente |
| `error_message` | TEXT | Error si falló el envío |
| `created_by` | INT NULL | Admin que creó el recordatorio |
| `created_at` | DATETIME | |
---
### 7.8 `system_config` — Configuración del sistema
| Campo | Tipo | Descripción |
|----------------|---------------|------------------------------------|
| `id` | INT | Clave primaria |
| `config_key` | VARCHAR(255) | Clave de configuración (UNIQUE) |
| `config_value` | TEXT | Valor de la configuración |
| `description` | TEXT NULL | Descripción opcional |
| `created_at` | DATETIME | |
| `updated_at` | DATETIME | |
**Claves relevantes para el bot:**
| `config_key` | Descripción |
|--------------------------|------------------------------------------------------|
| `whatsapp_token` | Token de acceso Bearer |
| `phone_number_id` | ID del número de teléfono |
| `whatsapp_api_url` | URL base del API |
| `webhook_verify_token` | Token secreto del webhook |
| `bot_enabled` | Activar/desactivar el bot (`1`/`0`) |
| `welcome_message` | Texto del mensaje de bienvenida |
| `default_no_match` | Mensaje cuando no se entiende la entrada del usuario|
| `advisor_message` | Mensaje al solicitar asesor |
| `terms_message` | Texto de los términos y condiciones |
| `business_hours_enabled` | Si se validan horarios de atención |
| `business_hours_start` | Hora inicio (ej: `06:15`) |
| `business_hours_end` | Hora fin (ej: `17:00`) |
---
### 7.9 `notifications` — Notificaciones internas para asesores
| Campo | Tipo | Descripción |
|-------------|--------------|------------------------------------------|
| `id` | INT | Clave primaria |
| `user_id` | INT | FK → `users.id` |
| `type` | VARCHAR(50) | Tipo de notificación (`new_message`, `advisor_requested`, etc.) |
| `message` | TEXT | Cuerpo de la notificación |
| `is_read` | TINYINT(1) | Si fue leída |
| `created_at`| TIMESTAMP | |
---
### 7.10 `terms_versions` — Versiones de términos y condiciones
| Campo | Tipo | Descripción |
|--------------------|---------------|-------------------------------------------------------|
| `id` | INT | Clave primaria |
| `version` | VARCHAR(20) | Versión (ej: `1.0`, `2.0`) |
| `titulo` | VARCHAR(255) | Título del documento |
| `documento_url` | TEXT | URL pública del PDF de términos |
| `mensaje_aceptacion` | TEXT | Mensaje que se envía al usuario solicitando aceptación |
| `activa` | TINYINT(1) | `1` = versión vigente |
| `forzar_reenvio` | TINYINT(1) | `1` = forzar que todos los usuarios re-acepten |
| `created_at` | TIMESTAMP | |
---
### 7.11 `terms_acceptance` — Aceptación de términos
| Campo | Tipo | Descripción |
|--------------------|---------------|---------------------------------------|
| `id` | INT | Clave primaria |
| `user_id` | INT | FK → `users.id` |
| `terms_version_id` | INT | FK → `terms_versions.id` |
| `phone_number` | VARCHAR(20) | Teléfono del usuario |
| `estado` | ENUM | `pendiente`, `aceptado`, `rechazado` |
| `fecha_envio` | DATETIME | Cuándo se envió la solicitud |
| `fecha_respuesta` | DATETIME NULL | Cuándo respondió el usuario |
---
### 7.12 `admin_users` — Administradores del sistema
| Campo | Tipo | Descripción |
|----------------|---------------|----------------------------------|
| `id` | INT | Clave primaria |
| `username` | VARCHAR(50) | Nombre de usuario (UNIQUE) |
| `password_hash`| VARCHAR(255) | Bcrypt hash de la contraseña |
| `full_name` | VARCHAR(100) | Nombre completo |
| `email` | VARCHAR(100) | Correo electrónico |
| `is_active` | TINYINT(1) | `1` = activo |
| `role_id` | INT NULL | FK → `roles.id` |
| `last_login` | TIMESTAMP | Último login |
---
### 7.13 `webhook_logs` — Logs del webhook
| Campo | Tipo | Descripción |
|---------------|---------------|---------------------------------------|
| `id` | INT | Clave primaria |
| `payload` | LONGTEXT | Body JSON recibido de WhatsApp |
| `response` | TEXT | Respuesta devuelta |
| `status_code` | INT | Código HTTP |
| `created_at` | TIMESTAMP | Fecha del evento |
---
## 8. Formato del número de teléfono
Los números se almacenan y envían **sin el símbolo `+`**, en formato E.164:
- Colombia: `573001234567` (código país 57 + número sin prefijo)
- Argentina: `5491123456789`
El sistema normaliza automáticamente:
- Elimina caracteres no numéricos.
- Si el número tiene 10 dígitos y empieza con `3` → agrega prefijo `57` (Colombia).
- Si ya tiene 12 dígitos → lo usa tal cual.
---
## 9. Lógica de estados del usuario
El bot controla el flujo mediante campos en la tabla `users`:
```
Estado normal:
bot_enabled=1, in_service=0, on_hold=0, advisor_requested=0, bot_paused_until=NULL
→ Bot responde normalmente
En menú:
current_menu_id=<id> → Bot espera número de opción
Atendido por asesor:
in_service=1, in_service_by=<admin_id>
→ Bot NO responde, asesor humano escribe directamente
En espera (hold activo):
on_hold=1, bot_paused_until=<datetime>
→ Bot notifica que está en espera, solo permite MENU/ATRÁS/números
Asesor solicitado:
advisor_requested=1, bot_paused_until=<datetime>
→ Bot espera al asesor, solo permite navegación explícita
Bot pausado:
bot_paused_until=<datetime futura>
→ Bot no responde mensajes libres, solo menús/comandos
Pendiente de términos:
terms_pending=1
→ Bot solo procesa respuesta "acepto" o "rechazo"
Usuario bloqueado:
status='blocked'
→ Todos los mensajes se descartan silenciosamente
```
---
## 10. Estados de conversación (tabla `user_states`)
Estados clave/valor persistentes por usuario (como sesión):
| `state_key` | Descripción |
|----------------|---------------------------------------------------------------|
| `menu_history` | Array JSON con historial de IDs de menús visitados |
| `current_menu` | ID del menú actual |
| `form_data` | Datos temporales de un formulario en curso |
---
## 11. Endpoints internos del sistema (API interna)
Estos endpoints son para el **panel de administración**, no son de WhatsApp. Se implementarían como API REST en el nuevo sistema:
| Método | Ruta interna | Descripción |
|--------|-------------------------------|--------------------------------------------------|
| GET | `/api/get_conversations.php` | Lista de conversaciones con paginación |
| GET | `/api/get_conversation_detail.php?user_id=X` | Mensajes de un usuario |
| POST | `/api/send_message.php` | Enviar mensaje desde el panel |
| POST | `/api/send_reply.php` | Responder a un mensaje |
| POST | `/api/attend.php` | Marcar usuario como "en atención" por asesor |
| POST | `/api/finish_attend.php` | Liberar usuario de la atención |
| POST | `/api/release_hold.php` | Liberar usuario del estado on_hold |
| GET | `/api/get_templates.php` | Lista de plantillas aprobadas |
| POST | `/api/send_broadcast.php` | Enviar mensaje masivo a múltiples usuarios |
| POST | `/api/schedule_message.php` | Programar un mensaje |
| GET | `/api/get_menus.php` | Lista de menús configurados |
| POST | `/api/save_menu.php` | Crear/editar menú |
| GET | `/api/get_settings.php` | Configuración del sistema |
| POST | `/api/save_settings.php` | Guardar configuración |
| GET | `/api/sse_events.php` | Server-Sent Events para tiempo real |
---
## 12. Flujo de términos y condiciones
```
Usuario envía mensaje
│
▼
¿needsTermsAcceptance()?
│ SÍ
▼
sendTermsMessage()
→ Envía texto con el mensaje de términos + URL del documento
→ Guarda users.terms_pending = 1
→ Inserta en terms_acceptance (estado: 'pendiente')
│
Usuario responde
│
processTermsResponse()
├─ Si respuesta contiene "acepto", "si", "sí", "ok", "1" → ACEPTA
│ → Actualiza users.terms_accepted_at, terms_version_id
│ → Actualiza terms_acceptance.estado = 'aceptado'
│ → Envía mensaje de confirmación
└─ Si respuesta contiene "no", "rechazo", "2" → RECHAZA
→ Actualiza terms_acceptance.estado = 'rechazado'
→ Envía mensaje de rechazo
```
---
## 13. Worker de mensajes programados
Un proceso cron (o worker) ejecuta cada minuto:
1. Consulta `scheduled_messages` donde `status = 'pending'` y `scheduled_date + scheduled_time <= NOW()`.
2. Para cada registro:
- Si `message_type = 'template'` → llama a `WhatsAppService::sendTemplateMessage()`.
- Si `message_type = 'text'` → llama a `WhatsAppService::sendTextMessage()`.
3. Actualiza `status = 'sent'` y registra `sent_at`.
4. Si falla → `status = 'failed'` + registra `error_message`.
---
## 14. Diagrama de clases del bot
```
WhatsAppWebhook (api/webhook.php)
│
├──uses──▶ WhatsAppService (services/WhatsAppService.php)
│ ├── sendTextMessage($to, $message)
│ ├── sendTemplateMessage($to, $name, $lang, $bodyParams, $headerParams, $rawComponents)
│ ├── sendInteractiveMessage($to, $body, $buttons, $header, $footer)
│ ├── sendListMessage($to, $body, $buttonText, $sections, $header, $footer)
│ ├── sendImageMessage($to, $url, $caption)
│ ├── sendVideoMessage($to, $url, $caption)
│ ├── sendAudioMessage($to, $url)
│ ├── sendDocumentMessage($to, $url, $filename, $caption)
│ ├── sendReactionMessage($to, $messageId, $emoji)
│ ├── markAsRead($messageId)
│ ├── uploadMedia($filePath, $mimeType) → retorna { id: "..." }
│ └── getMediaUrl($mediaId) → retorna URL temporal
│
└──uses──▶ BotService (services/BotService.php)
│
├──uses──▶ MenuService (services/MenuService.php)
│ └── getMenu($id), getMenuOptions($menuId)
│
├──uses──▶ ConversationStateService (services/ConversationStateService.php)
│ ├── getCurrentMenuId($phone)
│ ├── setCurrentMenu($phone, $menuId)
│ └── getStateData($phone, $key)
│
├──uses──▶ BusinessHoursService (services/BusinessHoursService.php)
│ └── isWithinBusinessHours()
│
└──uses──▶ NLPService (services/NLPService.php)
└── analyze($text) → detección de intenciones básica
```
---
## 15. Checklist de implementación
Para reimplementar el bot en otro sistema/lenguaje:
- [ ] Configurar la App en Meta for Developers con permisos `whatsapp_business_messaging`, `whatsapp_business_management`.
- [ ] Obtener: `Access Token`, `Phone Number ID`, `WABA ID`, `Webhook Verify Token`.
- [ ] Crear endpoint público HTTPS para el webhook (GET para verificación, POST para mensajes).
- [ ] Crear las tablas de base de datos: `users`, `conversations`, `menus`, `menu_options`, `message_templates`, `autoresponses`, `system_config`, `notifications`, `terms_versions`, `terms_acceptance`, `scheduled_messages`, `webhook_logs`.
- [ ] Implementar `WhatsAppService` con los métodos de envío (ver sección 3).
- [ ] Implementar la lógica de estados del usuario (sección 9).
- [ ] Implementar el flujo de menús dinámicos (mensajes numerados).
- [ ] Implementar el flujo de términos y condiciones (sección 12).
- [ ] Implementar sistema de advisory lock por usuario para evitar mensajes duplicados en procesamiento concurrente.
- [ ] Implementar cron/worker para mensajes programados (sección 13).
- [ ] Implementar reinicio de sesión después de 6h de inactividad.
---
## 16. Notas de seguridad
- **Nunca** expongas el `whatsapp_token` en el frontend.
- Validar siempre el `hub.verify_token` en el handshake del webhook.
- Sanear todos los campos de texto antes de almacenar en BD para evitar XSS/SQLi.
- Los mensajes duplicados se detectan por `message_id` único (`wamid.XXX`) — siempre validar antes de procesar.
- Usar advisory locks a nivel de BD para evitar race conditions cuando WhatsApp envía el mismo webhook dos veces en paralelo.