2254 lines
58 KiB
Plaintext
2254 lines
58 KiB
Plaintext
================================================================================
|
|
DOCUMENTACIÓN COMPLETA
|
|
WhatsApp Bot Manager
|
|
================================================================================
|
|
|
|
Versión: 1.2.0
|
|
PHP: 8.2+
|
|
Estado: Producción
|
|
|
|
Sistema completo de gestión de conversaciones de WhatsApp Business
|
|
Desarrollado por U-Site.app
|
|
|
|
================================================================================
|
|
ÍNDICE
|
|
================================================================================
|
|
|
|
1. Introducción
|
|
2. Manual de Usuario
|
|
3. Documentación Técnica
|
|
4. API REST Completa
|
|
5. Guía de Implementación
|
|
6. Casos de Uso
|
|
7. Entregables del Proyecto
|
|
8. Mantenimiento y Soporte
|
|
|
|
================================================================================
|
|
1. INTRODUCCIÓN
|
|
================================================================================
|
|
|
|
¿Qué es WhatsApp Bot Manager?
|
|
-------------------------------
|
|
|
|
WhatsApp Bot Manager es una plataforma web completa para gestionar
|
|
comunicaciones de WhatsApp Business. Permite a empresas automatizar
|
|
respuestas, gestionar conversaciones en tiempo real, enviar mensajes
|
|
masivos y mantener un control total sobre las interacciones con clientes.
|
|
|
|
|
|
Características Principales
|
|
-----------------------------
|
|
|
|
GESTIÓN DE CONVERSACIONES
|
|
- Interfaz tipo WhatsApp Web responsive
|
|
- Notificaciones en tiempo real con SSE (Server-Sent Events)
|
|
- Soporte completo para multimedia (imágenes, videos, audio, documentos)
|
|
- Búsqueda y filtrado de conversaciones
|
|
- Indicadores de estado de mensajes (enviado, entregado, leído)
|
|
|
|
AUTOMATIZACIÓN INTELIGENTE
|
|
- Bot con respuestas automáticas configurables
|
|
- Plantillas de mensaje aprobadas por WhatsApp
|
|
- Menús interactivos con botones
|
|
- Mensajes masivos con segmentación
|
|
- Quick replies para respuestas rápidas
|
|
|
|
SEGURIDAD Y CONTROL
|
|
- Autenticación basada en base de datos
|
|
- Protección contra ataques de fuerza bruta
|
|
- Registro completo de actividades (logs)
|
|
- Sistema de sesiones seguras
|
|
- Configuración granular de permisos
|
|
|
|
ANÁLISIS Y REPORTES
|
|
- Dashboard con estadísticas en tiempo real
|
|
- Gráficos de mensajes por día/hora
|
|
- Estado de conversaciones (activas, resueltas, pendientes)
|
|
- Exportación de datos a CSV
|
|
- Métricas de rendimiento del bot
|
|
|
|
|
|
Tecnologías Utilizadas
|
|
------------------------
|
|
|
|
Tecnología Versión Uso
|
|
------------------------------------------------------------------------
|
|
PHP 8.2+ Backend y lógica de negocio
|
|
MariaDB 10.11+ Base de datos principal
|
|
Redis 7.0+ Cache y gestión de colas
|
|
JavaScript ES6+ Frontend interactivo
|
|
Bootstrap 5.3.0 UI/UX responsive
|
|
Docker 24.0+ Contenedorización
|
|
Nginx 1.25+ Servidor web
|
|
WhatsApp API v22.0 Integración con WhatsApp
|
|
|
|
|
|
================================================================================
|
|
2. MANUAL DE USUARIO
|
|
================================================================================
|
|
|
|
2.1. Acceso al Sistema
|
|
------------------------
|
|
|
|
Inicio de Sesión
|
|
----------------
|
|
1. Accede a la URL de tu instalación (ej: https://tudominio.com)
|
|
2. Haz clic en "Iniciar Sesión"
|
|
3. Ingresa tus credenciales:
|
|
- Usuario: admin (por defecto)
|
|
- Contraseña: password123 (cámbiala tras el primer acceso)
|
|
|
|
Recuperación de Contraseña
|
|
---------------------------
|
|
1. Haz clic en "¿Olvidaste tu contraseña?"
|
|
2. Ingresa tu correo electrónico registrado
|
|
3. Recibirás un enlace para restablecer tu contraseña
|
|
4. Crea una nueva contraseña segura (mínimo 8 caracteres)
|
|
|
|
|
|
2.2. Panel Principal (Dashboard)
|
|
---------------------------------
|
|
|
|
Vista General
|
|
-------------
|
|
Al iniciar sesión verás el dashboard con:
|
|
|
|
ESTADÍSTICAS GENERALES
|
|
- Total de usuarios
|
|
- Mensajes recibidos (24h)
|
|
- Mensajes enviados (24h)
|
|
- Conversaciones activas
|
|
|
|
GRÁFICO DE MENSAJES
|
|
- Visualización por hora/día
|
|
- Comparativa entrada vs salida
|
|
- Tendencias de uso
|
|
|
|
MENSAJES RECIENTES
|
|
- Últimas 10 conversaciones
|
|
- Vista previa del mensaje
|
|
- Timestamp relativo
|
|
|
|
|
|
2.3. Gestión de Conversaciones
|
|
--------------------------------
|
|
|
|
Interfaz de Chat
|
|
----------------
|
|
La interfaz principal replica WhatsApp Web con:
|
|
|
|
PANEL IZQUIERDO (Lista de Conversaciones)
|
|
- Buscar: Campo de búsqueda por nombre o número
|
|
- Filtros:
|
|
* Todos los mensajes
|
|
* Solo no leídos
|
|
- Lista ordenada por mensaje más reciente
|
|
- Indicadores:
|
|
* Punto azul = conversación no leída
|
|
* Timestamp del último mensaje
|
|
* Vista previa del contenido
|
|
|
|
PANEL PRINCIPAL (Área de Chat)
|
|
- Cabecera:
|
|
* Avatar y nombre del usuario
|
|
* Número de teléfono
|
|
* Botones de acción (editar, eliminar)
|
|
- Área de mensajes:
|
|
* Mensajes propios (derecha, fondo verde claro)
|
|
* Mensajes recibidos (izquierda, fondo blanco)
|
|
* Timestamps en cada mensaje
|
|
* Estados: checkmark enviado, doble checkmark entregado/leído
|
|
- Barra de entrada:
|
|
* Campo de texto para escribir
|
|
* Botón de adjuntar archivos
|
|
* Botón de respuestas rápidas
|
|
* Botón de enviar
|
|
|
|
Enviar Mensajes de Texto
|
|
-------------------------
|
|
1. Selecciona una conversación de la lista
|
|
2. Escribe tu mensaje en el campo inferior
|
|
3. Presiona Enter o haz clic en Enviar
|
|
4. El mensaje aparecerá inmediatamente en el chat
|
|
|
|
Características de texto:
|
|
- Soporte para emojis
|
|
- Formato WhatsApp:
|
|
* *texto* = negrita
|
|
* _texto_ = cursiva
|
|
* ~texto~ = tachado
|
|
* `código` = monoespaciado
|
|
- Saltos de línea con Shift + Enter
|
|
- Envío con Enter
|
|
|
|
|
|
Enviar Archivos Multimedia
|
|
---------------------------
|
|
|
|
IMÁGENES
|
|
1. Haz clic en el botón Adjuntar
|
|
2. Selecciona "Imagen"
|
|
3. Elige una imagen desde tu dispositivo
|
|
4. Opcionalmente agrega un caption (texto)
|
|
5. Haz clic en "Enviar"
|
|
|
|
Formatos soportados: JPG, PNG, GIF, WebP
|
|
Tamaño máximo: 5 MB
|
|
|
|
VIDEOS
|
|
1. Clic en Adjuntar > "Video"
|
|
2. Selecciona un video (máx 16MB)
|
|
3. Agrega caption opcional
|
|
4. Envía
|
|
|
|
Formatos soportados: MP4, AVI, MOV, 3GP
|
|
Tamaño máximo: 16 MB
|
|
|
|
AUDIO
|
|
Opción A - Grabar nota de voz:
|
|
- Mantén presionado el botón del micrófono
|
|
- Habla al micrófono
|
|
- Suelta para enviar automáticamente
|
|
- Desliza para cancelar
|
|
|
|
Opción B - Subir archivo de audio:
|
|
- Clic en Adjuntar > "Audio"
|
|
- Selecciona archivo MP3, WAV, AAC, OGG
|
|
- Envía directamente
|
|
|
|
Tamaño máximo audio: 16 MB
|
|
|
|
DOCUMENTOS
|
|
1. Clic en Adjuntar > "Documento"
|
|
2. Selecciona archivo (PDF, DOC, XLS, etc.)
|
|
3. El sistema detecta el tipo automáticamente
|
|
4. Envía
|
|
|
|
Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP
|
|
Tamaño máximo: 100 MB
|
|
|
|
|
|
Respuestas Rápidas (Quick Replies)
|
|
-----------------------------------
|
|
Las respuestas rápidas te permiten enviar mensajes predefinidos con un
|
|
solo clic:
|
|
|
|
1. Haz clic en el botón Respuestas Rápidas
|
|
2. Se desplegará un panel con dos pestañas:
|
|
- Texto: Respuestas automáticas simples
|
|
- Plantillas: Templates aprobados de WhatsApp
|
|
3. Selecciona la respuesta deseada
|
|
4. Se enviará automáticamente
|
|
|
|
Editar respuestas rápidas:
|
|
1. Ve a Configuración > Respuestas Automáticas
|
|
2. Haz clic en "Nueva Respuesta"
|
|
3. Ingresa:
|
|
- Palabra clave (trigger)
|
|
- Mensaje de respuesta
|
|
- Activa/Desactiva
|
|
4. Guarda los cambios
|
|
|
|
|
|
Plantillas de WhatsApp
|
|
-----------------------
|
|
Las plantillas son mensajes pre-aprobados por Meta que puedes usar:
|
|
|
|
ENVIAR UNA PLANTILLA
|
|
1. En el chat, despliega Respuestas Rápidas
|
|
2. Ve a la pestaña "Plantillas"
|
|
3. Selecciona una plantilla aprobada
|
|
4. Si la plantilla tiene variables, se rellenarán automáticamente
|
|
5. La plantilla se envía instantáneamente
|
|
|
|
GESTIONAR PLANTILLAS
|
|
1. Ve a Configuración > Plantillas de Mensaje
|
|
2. Verás una lista con:
|
|
- Nombre de la plantilla
|
|
- Estado: Aprobada | Pendiente | Rechazada
|
|
- Idioma
|
|
- Fecha de creación
|
|
3. Crear nueva plantilla:
|
|
- Clic en "Nueva Plantilla"
|
|
- Completa el formulario:
|
|
* Nombre: identificador único (sin espacios)
|
|
* Categoría: MARKETING, UTILITY, AUTHENTICATION
|
|
* Idioma: es (Español)
|
|
* Encabezado: Título opcional
|
|
* Cuerpo: Mensaje principal (puede incluir variables {{1}}, {{2}})
|
|
* Pie: Texto al final opcional
|
|
* Botones: Opcionales (CALL_TO_ACTION, QUICK_REPLY)
|
|
- Enviar para aprobación
|
|
- Meta revisará la plantilla (puede tardar 24-48h)
|
|
|
|
IMPORTANTE: Solo puedes enviar plantillas APROBADAS por WhatsApp.
|
|
|
|
|
|
Notificaciones en Tiempo Real
|
|
-------------------------------
|
|
El sistema usa SSE (Server-Sent Events) para actualizaciones en tiempo real:
|
|
|
|
- Nuevos mensajes: Aparecen automáticamente sin recargar
|
|
- Notificaciones de escritura: "Usuario está escribiendo..."
|
|
- Estados de mensaje: Cambios en tiempo real (entregado -> leído)
|
|
- Toasts informativos: Alertas visuales en la esquina superior derecha
|
|
|
|
Estados de conexión:
|
|
- Verde: Conectado
|
|
- Amarillo: Reconectando
|
|
- Rojo: Desconectado
|
|
|
|
Si pierdes conexión, el sistema intentará reconectar automáticamente
|
|
cada 5 segundos.
|
|
|
|
|
|
2.4. Gestión de Usuarios
|
|
--------------------------
|
|
|
|
Listar Usuarios
|
|
---------------
|
|
1. Ve a "Usuarios" en el menú principal
|
|
2. Verás una tabla con:
|
|
- ID del usuario
|
|
- Nombre
|
|
- Número de teléfono
|
|
- Estado (in_service, on_hold, completed)
|
|
- Última interacción
|
|
- Acciones (editar, eliminar, ver chat)
|
|
|
|
Crear/Editar Usuario
|
|
---------------------
|
|
1. Haz clic en "Nuevo Usuario"
|
|
2. Completa el formulario:
|
|
- Nombre: Nombre completo o identificador
|
|
- Teléfono: Número con código de país (ej: 573001234567)
|
|
- Email: Opcional
|
|
- Notas: Información adicional
|
|
3. Guarda
|
|
|
|
Editar: Haz clic en el icono de edición en la fila del usuario.
|
|
|
|
Eliminar Usuario
|
|
----------------
|
|
1. Haz clic en el icono de eliminar
|
|
2. Confirma la acción
|
|
3. ADVERTENCIA: Esto eliminará también todo el historial de conversaciones
|
|
|
|
Exportar Usuarios
|
|
-----------------
|
|
1. Haz clic en "Exportar CSV"
|
|
2. Se descargará un archivo con todos los usuarios y sus datos
|
|
|
|
|
|
2.5. Mensajes Masivos (Broadcast)
|
|
-----------------------------------
|
|
|
|
Enviar Mensaje Masivo
|
|
----------------------
|
|
1. Ve a "Envío Masivo" en el menú
|
|
2. Configura el mensaje:
|
|
- Tipo: Texto o Plantilla
|
|
- Contenido: Escribe el mensaje o selecciona plantilla
|
|
- Filtro de destinatarios:
|
|
* Todos los usuarios
|
|
* Solo usuarios activos (últimas 24h)
|
|
* Lista personalizada (importar CSV)
|
|
3. Vista previa: Revisa cómo se verá el mensaje
|
|
4. Haz clic en "Enviar a todos"
|
|
5. El sistema procesará los envíos en segundo plano
|
|
|
|
Limitaciones de WhatsApp:
|
|
- Solo puedes enviar plantillas aprobadas a usuarios que no te han
|
|
escrito en 24h
|
|
- Respeta la ventana de 24 horas para mensajes libres
|
|
- El sistema controlará automáticamente estos límites
|
|
|
|
Seguimiento de Envíos
|
|
----------------------
|
|
En la sección "Historial de Envíos" puedes ver:
|
|
- Fecha y hora del envío
|
|
- Total de destinatarios
|
|
- Enviados exitosos
|
|
- Fallidos (con motivo)
|
|
- Estado general
|
|
|
|
|
|
2.6. Bot Automatizado
|
|
----------------------
|
|
|
|
Configurar el Bot
|
|
-----------------
|
|
1. Ve a Configuración > Bot Automático
|
|
2. Activa/Desactiva el bot con el interruptor
|
|
3. Configura:
|
|
- Mensaje de bienvenida: Primer mensaje al nuevo usuario
|
|
- Mensaje de ausencia: Respuesta fuera de horario
|
|
- Horario de atención: Define días y horas
|
|
- Palabras clave: Triggers que activan respuestas
|
|
|
|
Respuestas Automáticas
|
|
-----------------------
|
|
|
|
CREAR RESPUESTA AUTOMÁTICA
|
|
1. Ve a Configuración > Respuestas Automáticas
|
|
2. Clic en "Nueva Respuesta"
|
|
3. Configura:
|
|
- Trigger: Palabra o frase que activa la respuesta
|
|
- Mensaje: Respuesta automática
|
|
- Activo: On/Off
|
|
- Prioridad: Orden de evaluación (1 = más alta)
|
|
4. Guarda
|
|
|
|
Ejemplos de uso:
|
|
- Trigger: hola, buenos días, buenas tardes
|
|
Respuesta: ¡Hola! Bienvenido a [Empresa]. ¿En qué puedo ayudarte?
|
|
|
|
- Trigger: horario, horarios, cuando abren
|
|
Respuesta: Nuestro horario de atención es: Lunes a Viernes 9am-6pm
|
|
|
|
- Trigger: precio, cuanto cuesta, costo
|
|
Respuesta: Para información sobre precios, por favor visita [URL]
|
|
|
|
TIPS PARA RESPUESTAS AUTOMÁTICAS EFECTIVAS
|
|
- Usa múltiples triggers: hola,buenos días,buenas tardes,hey
|
|
- Sé claro y conciso: Respuestas cortas son más efectivas
|
|
- Incluye opciones: "Responde 1 para ventas, 2 para soporte"
|
|
- Usa emojis: Hacen la conversación más amigable
|
|
- Escalamiento: Indica cuándo un humano tomará la conversación
|
|
|
|
|
|
Menús Interactivos
|
|
------------------
|
|
Los menús interactivos permiten crear flujos de conversación estructurados:
|
|
|
|
CREAR MENÚ
|
|
1. Ve a Configuración > Menús Interactivos
|
|
2. Clic en "Nuevo Menú"
|
|
3. Configura:
|
|
- Nombre del menú: Identificador interno
|
|
- Mensaje principal: Texto que verá el usuario
|
|
- Opciones (hasta 10):
|
|
* ID: Número o letra
|
|
* Texto: Descripción de la opción
|
|
* Acción: Respuesta o submenu
|
|
4. Guarda
|
|
|
|
Ejemplo de menú principal:
|
|
---------------------------
|
|
Bienvenido a [Empresa]
|
|
|
|
Por favor selecciona una opción:
|
|
|
|
1. Ventas
|
|
2. Soporte técnico
|
|
3. Información general
|
|
4. Hablar con un asesor
|
|
|
|
Responde con el número de tu opción.
|
|
|
|
|
|
2.7. Configuración del Sistema
|
|
--------------------------------
|
|
|
|
Configuración de WhatsApp
|
|
--------------------------
|
|
1. Ve a Configuración > WhatsApp API
|
|
2. Completa los campos:
|
|
|
|
Datos de Meta Business:
|
|
- App ID: ID de tu aplicación de Facebook
|
|
- App Secret: Secreto de la aplicación
|
|
- Business Account ID: ID de tu cuenta de negocio
|
|
- Phone Number ID: ID del número de teléfono de WhatsApp
|
|
- Access Token: Token de acceso permanente
|
|
- Webhook Verify Token: Token para verificar el webhook
|
|
|
|
URLs:
|
|
- API URL: https://graph.facebook.com/v22.0/
|
|
- Webhook URL: https://tudominio.com/api/webhook.php
|
|
|
|
3. Haz clic en "Verificar Configuración"
|
|
4. Si todo está correcto, verás checkmarks en todos los checks
|
|
5. Guarda los cambios
|
|
|
|
Configuración General
|
|
---------------------
|
|
1. Ve a Configuración > General
|
|
2. Ajusta:
|
|
- Nombre de la empresa: Aparece en mensajes automáticos
|
|
- Zona horaria: América/Bogota (por defecto)
|
|
- Idioma: Español (es)
|
|
- Límite de mensajes por minuto: Control de rate limiting
|
|
- Retención de logs: Días que se guardan los registros
|
|
- Activar notificaciones sonoras: Sonido al recibir mensaje
|
|
3. Guarda
|
|
|
|
Gestión de Administradores
|
|
---------------------------
|
|
1. Ve a Configuración > Administradores
|
|
2. Lista de usuarios admin actuales
|
|
3. Crear nuevo admin:
|
|
- Clic en "Nuevo Administrador"
|
|
- Ingresa:
|
|
* Nombre de usuario
|
|
* Email
|
|
* Contraseña (mínimo 8 caracteres)
|
|
* Permisos:
|
|
- Admin completo: Acceso total
|
|
- Operador: Solo gestión de conversaciones
|
|
- Visualizador: Solo lectura
|
|
- Guarda
|
|
4. Eliminar admin: Clic en icono eliminar junto al usuario
|
|
|
|
|
|
2.8. Logs y Auditoría
|
|
----------------------
|
|
|
|
Ver Logs del Sistema
|
|
--------------------
|
|
1. Ve a Logs en el menú principal
|
|
2. Filtros disponibles:
|
|
- Nivel: Error, Warning, Info, Debug
|
|
- Fecha: Rango de fechas
|
|
- Módulo: API, Bot, Webhook, Sistema
|
|
3. Tabla de logs muestra:
|
|
- Timestamp
|
|
- Nivel de severidad
|
|
- Mensaje
|
|
- Contexto (datos adicionales)
|
|
|
|
Logs de Webhook
|
|
----------------
|
|
Los logs de webhook muestran cada interacción con WhatsApp:
|
|
|
|
1. Ve a Logs > Webhook
|
|
2. Cada entrada muestra:
|
|
- Timestamp de recepción
|
|
- Tipo de evento (message, status, etc.)
|
|
- Datos del mensaje (JSON)
|
|
- Respuesta del sistema
|
|
- Tiempo de procesamiento
|
|
|
|
Útil para:
|
|
- Depurar problemas de recepción de mensajes
|
|
- Ver mensajes duplicados
|
|
- Auditar interacciones
|
|
|
|
Exportar Logs
|
|
-------------
|
|
1. Selecciona los filtros deseados
|
|
2. Clic en "Exportar"
|
|
3. Descarga archivo CSV con los logs
|
|
|
|
Limpiar Logs
|
|
------------
|
|
Para liberar espacio:
|
|
1. Ve a Logs > Limpieza
|
|
2. Selecciona:
|
|
- Logs más antiguos de X días
|
|
- Tipo específico
|
|
3. Confirma la eliminación
|
|
|
|
|
|
================================================================================
|
|
3. DOCUMENTACIÓN TÉCNICA
|
|
================================================================================
|
|
|
|
3.1. Arquitectura del Sistema
|
|
-------------------------------
|
|
|
|
DIAGRAMA DE COMPONENTES
|
|
------------------------
|
|
|
|
FRONTEND
|
|
+----------+ +-------------+ +----------------+
|
|
|conversations| chat_window | inicio.html |
|
|
| .php | | .php | (landing) |
|
|
+----------+ +-------------+ +----------------+
|
|
|
|
|
v
|
|
API REST (42 Endpoints)
|
|
+-------------+ +-------------+ +----------------+
|
|
|send_message | |get_messages | | upload_media |
|
|
|send_template| | get_users | | webhook |
|
|
|send_broadcast| | get_stats | | sse_events |
|
|
+-------------+ +-------------+ +----------------+
|
|
|
|
|
v
|
|
CAPA DE SERVICIOS
|
|
+-----------------+ +-------------------+
|
|
| WhatsAppService | | BotService |
|
|
| (comunicación | | (automatización) |
|
|
| con WhatsApp) | | |
|
|
+-----------------+ +-------------------+
|
|
|
|
|
v
|
|
CAPA DE DATOS
|
|
+------------+ +------------+ +---------------+
|
|
| Database | | Redis | | Filesystem |
|
|
| (MariaDB) | | (cache) | | (uploads/) |
|
|
+------------+ +------------+ +---------------+
|
|
|
|
|
v
|
|
INTEGRACIONES EXTERNAS
|
|
+------------------------------------------------------+
|
|
| WhatsApp Business API (Meta Graph API) |
|
|
| https://graph.facebook.com/v22.0/ |
|
|
+------------------------------------------------------+
|
|
|
|
|
|
FLUJO DE MENSAJES
|
|
-----------------
|
|
|
|
Mensaje Entrante (Incoming):
|
|
1. Usuario envía mensaje por WhatsApp
|
|
2. WhatsApp envía webhook POST a /api/webhook.php
|
|
3. Webhook valida firma de Meta
|
|
4. Procesa evento (message, status, etc.)
|
|
5. Guarda mensaje en BD (tabla: conversations)
|
|
6. BotService evalúa si debe responder automáticamente
|
|
7. Si hay respuesta automática -> Envía por WhatsAppService
|
|
8. SSE notifica a frontend conectado
|
|
9. Frontend actualiza UI en tiempo real
|
|
|
|
Mensaje Saliente (Outgoing):
|
|
1. Usuario escribe mensaje en interfaz web
|
|
2. Frontend llama a /api/send_message.php (POST)
|
|
3. API valida sesión y datos
|
|
4. WhatsAppService envía mensaje a Graph API
|
|
5. Graph API retorna ID del mensaje
|
|
6. Se guarda mensaje en BD con estado 'sent'
|
|
7. Respuesta JSON al frontend
|
|
8. Frontend muestra mensaje instantáneamente
|
|
9. Webhook recibe confirmación de entrega/lectura
|
|
10. Actualiza estado en BD y notifica por SSE
|
|
|
|
|
|
3.2. Estructura de Archivos
|
|
-----------------------------
|
|
|
|
whatsapp/
|
|
|-- api/ (API REST Endpoints)
|
|
| |-- webhook.php (Recibe eventos de WhatsApp)
|
|
| |-- send_message.php (Enviar mensaje individual)
|
|
| |-- send_media_message.php (Enviar multimedia)
|
|
| |-- send_template.php (Enviar plantilla)
|
|
| |-- send_broadcast.php (Envío masivo)
|
|
| |-- get_conversations.php (Listar conversaciones)
|
|
| |-- get_user_messages.php (Mensajes de un usuario)
|
|
| |-- get_users.php (Listar usuarios)
|
|
| |-- update_user.php (Actualizar usuario)
|
|
| |-- delete_user.php (Eliminar usuario)
|
|
| |-- upload_media.php (Subir archivos)
|
|
| |-- get_media.php (Obtener URL temporal de media)
|
|
| |-- get_templates.php (Listar plantillas)
|
|
| |-- save_template.php (Guardar plantilla)
|
|
| |-- get_autoresponses.php (Respuestas automáticas)
|
|
| |-- save_autoresponse.php (Guardar respuesta automática)
|
|
| |-- get_stats.php (Estadísticas dashboard)
|
|
| |-- sse_events.php (Server-Sent Events)
|
|
| +-- ... (42 endpoints totales)
|
|
|
|
|
|-- assets/ (Recursos estáticos)
|
|
| |-- css/
|
|
| | +-- main.css
|
|
| |-- js/
|
|
| | |-- chat-common.js (Funciones compartidas de chat)
|
|
| | |-- dashboard.js (Dashboard stats)
|
|
| | +-- admin.js
|
|
| +-- images/
|
|
|
|
|
|-- classes/ (Clases PHP)
|
|
| +-- Database.php (Clase singleton de DB)
|
|
|
|
|
|-- config/ (Configuración)
|
|
| |-- config.php (Configuración principal)
|
|
| +-- .env.example (Plantilla variables de entorno)
|
|
|
|
|
|-- database/ (Scripts SQL)
|
|
| |-- migrations/
|
|
| | |-- 001_initial_schema.sql
|
|
| | |-- 002_add_media_fields.sql
|
|
| | +-- ...
|
|
| +-- backups/ (Backups automáticos)
|
|
|
|
|
|-- docker/ (Configuración Docker)
|
|
| |-- nginx/
|
|
| | +-- default.conf
|
|
| |-- php/
|
|
| | +-- Dockerfile
|
|
| +-- supervisor/
|
|
| +-- supervisord.conf
|
|
|
|
|
|-- services/ (Servicios)
|
|
| |-- WhatsAppService.php (Cliente WhatsApp Business API)
|
|
| |-- BotService.php (Lógica del bot automático)
|
|
| +-- MediaService.php (Gestión multimedia)
|
|
|
|
|
|-- uploads/ (Archivos subidos)
|
|
| |-- images/
|
|
| |-- videos/
|
|
| |-- audio/
|
|
| +-- documents/
|
|
|
|
|
|-- logs/ (Logs del sistema)
|
|
| |-- app.log
|
|
| |-- webhook.log
|
|
| +-- error.log
|
|
|
|
|
|-- tests/ (Tests)
|
|
| |-- ApiTest.php
|
|
| |-- WhatsAppServiceTest.php
|
|
| +-- ...
|
|
|
|
|
|-- conversations.php (Interfaz principal de chat)
|
|
|-- chat_window.php (Ventana de chat)
|
|
|-- inicio.html (Landing page)
|
|
|-- index.php (Dashboard / Redirect)
|
|
|-- login.php (Login)
|
|
|-- logout.php (Logout)
|
|
|-- worker.php (Worker de colas)
|
|
|-- composer.json (Dependencias PHP)
|
|
|-- docker-compose.yml (Orquestación containers)
|
|
|-- .env (Variables de entorno)
|
|
+-- README.md (Documentación básica)
|
|
|
|
|
|
3.3. Base de Datos
|
|
-------------------
|
|
|
|
TABLA: users
|
|
Almacena información de usuarios/contactos de WhatsApp.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
phone_number VARCHAR(50) Número con código de país
|
|
name VARCHAR(255) Nombre del contacto
|
|
email VARCHAR(255) Email (opcional)
|
|
profile_pic_url TEXT URL foto de perfil
|
|
in_service TINYINT(1) 1 si está en conversación activa
|
|
advisor_requested TINYINT(1) 1 si solicitó asesor humano
|
|
on_hold TINYINT(1) 1 si está en espera
|
|
attended_by INT ID del admin que atiende
|
|
last_message_at TIMESTAMP Timestamp último mensaje
|
|
created_at TIMESTAMP Fecha de registro
|
|
updated_at TIMESTAMP Última actualización
|
|
|
|
Índices:
|
|
- idx_phone (phone_number)
|
|
- idx_last_message (last_message_at)
|
|
- idx_in_service (in_service)
|
|
|
|
|
|
TABLA: conversations
|
|
Almacena todos los mensajes (entrantes y salientes).
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
user_id INT ID del usuario
|
|
message_id VARCHAR(255) ID único de WhatsApp
|
|
content TEXT Contenido del mensaje
|
|
direction ENUM 'incoming' o 'outgoing'
|
|
message_type VARCHAR(50) text, image, video, audio, etc.
|
|
status VARCHAR(50) sent, delivered, read, failed
|
|
media_url TEXT URL original de WhatsApp
|
|
whatsapp_media_id VARCHAR(255) ID del media en WhatsApp
|
|
local_file VARCHAR(500) Ruta local del archivo
|
|
local_thumb VARCHAR(500) Ruta de thumbnail
|
|
filename VARCHAR(255) Nombre del archivo
|
|
mime_type VARCHAR(100) Tipo MIME
|
|
media_url_external TEXT URL proxy persistente
|
|
reply_to_message_id VARCHAR(255) ID mensaje al que responde
|
|
reaction_emoji VARCHAR(10) Emoji de reacción
|
|
reaction_to_message_id VARCHAR(255) ID mensaje al que reacciona
|
|
created_at TIMESTAMP Fecha de creación
|
|
|
|
Índices:
|
|
- idx_user_id (user_id)
|
|
- idx_message_id (message_id)
|
|
- idx_direction (direction)
|
|
- idx_created_at (created_at)
|
|
- idx_user_created (user_id, created_at)
|
|
|
|
|
|
TABLA: message_templates
|
|
Plantillas de WhatsApp aprobadas por Meta.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
template_name VARCHAR(255) Nombre de la plantilla
|
|
language_code VARCHAR(10) Código de idioma (es, en)
|
|
category VARCHAR(50) MARKETING, UTILITY, AUTHENTICATION
|
|
header_text TEXT Texto del encabezado
|
|
body_text TEXT Texto del cuerpo
|
|
footer_text TEXT Texto del pie
|
|
buttons TEXT Botones (JSON)
|
|
status VARCHAR(50) pending, approved, rejected
|
|
created_at TIMESTAMP Fecha de creación
|
|
updated_at TIMESTAMP Última actualización
|
|
|
|
Índices:
|
|
- idx_status (status)
|
|
|
|
|
|
TABLA: autoresponses
|
|
Respuestas automáticas del bot.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
trigger_keywords TEXT Palabras clave (separadas por comas)
|
|
response_message TEXT Mensaje de respuesta
|
|
is_active TINYINT(1) 1 si está activa
|
|
priority INT Orden de evaluación
|
|
created_at TIMESTAMP Fecha de creación
|
|
updated_at TIMESTAMP Última actualización
|
|
|
|
Índices:
|
|
- idx_active (is_active)
|
|
|
|
|
|
TABLA: system_config
|
|
Configuración dinámica del sistema.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
config_key VARCHAR(255) Clave de configuración
|
|
config_value TEXT Valor
|
|
config_type VARCHAR(50) string, int, boolean, json
|
|
description TEXT Descripción
|
|
created_at TIMESTAMP Fecha de creación
|
|
updated_at TIMESTAMP Última actualización
|
|
|
|
Índices:
|
|
- idx_key (config_key)
|
|
|
|
|
|
TABLA: admin_users
|
|
Usuarios administradores del panel.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
username VARCHAR(100) Nombre de usuario
|
|
password VARCHAR(255) Contraseña hash
|
|
email VARCHAR(255) Email
|
|
role VARCHAR(50) super_admin, admin, operator, viewer
|
|
is_active TINYINT(1) 1 si está activo
|
|
last_login TIMESTAMP Último inicio de sesión
|
|
created_at TIMESTAMP Fecha de creación
|
|
updated_at TIMESTAMP Última actualización
|
|
|
|
Índices:
|
|
- idx_username (username)
|
|
|
|
|
|
TABLA: webhook_logs
|
|
Auditoría de webhooks recibidos.
|
|
|
|
Campo Tipo Descripción
|
|
------------------------------------------------------------------------
|
|
id INT ID único autoincremental
|
|
event_type VARCHAR(100) Tipo de evento
|
|
payload TEXT Datos del evento (JSON)
|
|
processed TINYINT(1) 1 si fue procesado
|
|
processing_time_ms INT Tiempo de procesamiento
|
|
error_message TEXT Mensaje de error (si aplica)
|
|
created_at TIMESTAMP Fecha de recepción
|
|
|
|
Índices:
|
|
- idx_event_type (event_type)
|
|
- idx_processed (processed)
|
|
- idx_created_at (created_at)
|
|
|
|
|
|
3.4. Servicios Principales
|
|
----------------------------
|
|
|
|
WhatsAppService.php
|
|
Clase que encapsula toda la comunicación con WhatsApp Business API.
|
|
|
|
MÉTODOS PRINCIPALES:
|
|
|
|
1. sendTextMessage($to, $message)
|
|
Envía un mensaje de texto simple.
|
|
|
|
Parámetros:
|
|
- $to: Número de destino con código de país
|
|
- $message: Contenido del mensaje (máx 4096 caracteres)
|
|
|
|
Retorna:
|
|
[
|
|
'success' => true|false,
|
|
'message_id' => 'wamid.XXX...',
|
|
'error' => null|string
|
|
]
|
|
|
|
2. sendTemplateMessage($to, $templateName, $language, $bodyParameters)
|
|
Envía una plantilla de mensaje aprobada.
|
|
|
|
Parámetros:
|
|
- $to: Número destino
|
|
- $templateName: Nombre de la plantilla
|
|
- $language: Código de idioma (es)
|
|
- $bodyParameters: Array de variables
|
|
|
|
3. sendImageMessage($to, $imageUrl, $caption, $isLocalFile)
|
|
Envía una imagen.
|
|
|
|
Formatos soportados: JPG, JPEG, PNG
|
|
Tamaño máximo: 5 MB
|
|
|
|
4. sendVideoMessage($to, $videoUrl, $caption, $isLocalFile)
|
|
Envía un video.
|
|
|
|
Formatos soportados: MP4, 3GPP
|
|
Tamaño máximo: 16 MB
|
|
|
|
5. sendAudioMessage($to, $audioUrl, $isLocalFile)
|
|
Envía audio.
|
|
|
|
Formatos soportados: AAC, MP3, AMR, OGG
|
|
Tamaño máximo: 16 MB
|
|
|
|
6. sendDocumentMessage($to, $documentUrl, $filename, $caption, $isLocalFile)
|
|
Envía un documento.
|
|
|
|
Formatos soportados: PDF, DOC, DOCX, XLS, XLSX, PPT, TXT, ZIP
|
|
Tamaño máximo: 100 MB
|
|
|
|
7. uploadMedia($filePath, $mimeType)
|
|
Sube un archivo a los servidores de WhatsApp.
|
|
|
|
Retorna: media_id para usar en envíos
|
|
|
|
8. downloadMedia($mediaId)
|
|
Descarga un archivo multimedia de WhatsApp.
|
|
|
|
Retorna: ruta local del archivo descargado
|
|
|
|
9. sendInteractiveMessage($to, $bodyText, $buttons, $header, $footer)
|
|
Envía un mensaje con botones interactivos (hasta 3 botones).
|
|
|
|
10. sendListMessage($to, $bodyText, $buttonText, $sections)
|
|
Envía un mensaje con lista interactiva (hasta 10 opciones).
|
|
|
|
|
|
BotService.php
|
|
Servicio de automatización de respuestas.
|
|
|
|
MÉTODOS PRINCIPALES:
|
|
|
|
1. processIncomingMessage($userId, $message)
|
|
Procesa un mensaje entrante y decide si el bot debe responder.
|
|
|
|
Lógica:
|
|
- Verifica si el bot está activado
|
|
- Comprueba si el usuario está siendo atendido por humano
|
|
- Busca respuesta automática que coincida
|
|
- Ejecuta lógica de menús si aplica
|
|
- Envía respuesta si corresponde
|
|
|
|
2. findAutoResponse($message)
|
|
Busca una respuesta automática que coincida con el mensaje.
|
|
|
|
Retorna: Objeto con response_message o null
|
|
|
|
3. sendWelcomeMessage($userId)
|
|
Envía el mensaje de bienvenida configurado.
|
|
|
|
4. isBusinessHours()
|
|
Verifica si está dentro del horario de atención.
|
|
|
|
Retorna: true si está en horario, false fuera de horario
|
|
|
|
|
|
MediaService.php
|
|
Servicio para gestión de archivos multimedia.
|
|
|
|
MÉTODOS PRINCIPALES:
|
|
|
|
1. downloadAndSaveMedia($mediaId, $userId)
|
|
Descarga un media de WhatsApp y lo guarda localmente.
|
|
|
|
Proceso:
|
|
- Obtiene URL temporal del media
|
|
- Descarga el contenido
|
|
- Detecta tipo MIME
|
|
- Genera nombre único
|
|
- Guarda en carpeta correspondiente
|
|
- Genera thumbnail para imágenes/videos
|
|
- Actualiza registro en BD
|
|
|
|
2. generateThumbnail($imagePath, $maxWidth, $maxHeight)
|
|
Genera un thumbnail para imágenes.
|
|
|
|
3. getMediaProxy($messageId)
|
|
Obtiene URL proxy persistente para un media.
|
|
|
|
|
|
3.5. Server-Sent Events (SSE)
|
|
-------------------------------
|
|
|
|
El sistema usa SSE para notificaciones en tiempo real sin WebSockets.
|
|
|
|
FLUJO SSE:
|
|
1. Frontend se conecta a /api/sse_events.php
|
|
2. El backend mantiene la conexión HTTP abierta
|
|
3. Cuando hay un nuevo evento:
|
|
a. Se guarda en Redis (canal: sse_notifications)
|
|
b. worker.php o webhook.php publica evento en canal
|
|
4. sse_events.php lee de Redis y envía al cliente
|
|
5. Frontend recibe evento y actualiza UI
|
|
6. Conexión se mantiene viva con heartbeat cada 15s
|
|
|
|
TIPOS DE EVENTOS SSE:
|
|
|
|
1. new_message
|
|
Nuevo mensaje recibido.
|
|
|
|
Datos:
|
|
{
|
|
"type": "new_message",
|
|
"user_id": 123,
|
|
"message_id": "wamid.XXX",
|
|
"content": "Hola",
|
|
"direction": "incoming",
|
|
"created_at": "2024-01-27 14:30:45"
|
|
}
|
|
|
|
2. message_status
|
|
Cambio de estado de mensaje.
|
|
|
|
Datos:
|
|
{
|
|
"type": "message_status",
|
|
"message_id": "wamid.XXX",
|
|
"status": "read",
|
|
"timestamp": "2024-01-27 14:31:00"
|
|
}
|
|
|
|
3. conversation_update
|
|
Actualización de conversación en lista.
|
|
|
|
Datos:
|
|
{
|
|
"type": "conversation_update",
|
|
"user_id": 123,
|
|
"last_message": "Hola",
|
|
"unread_count": 1
|
|
}
|
|
|
|
4. notification
|
|
Notificación general.
|
|
|
|
Datos:
|
|
{
|
|
"type": "notification",
|
|
"title": "Nuevo mensaje",
|
|
"message": "Juan te ha enviado un mensaje",
|
|
"severity": "info"
|
|
}
|
|
|
|
|
|
================================================================================
|
|
4. API REST COMPLETA
|
|
================================================================================
|
|
|
|
AUTENTICACIÓN
|
|
-------------
|
|
Todos los endpoints (excepto webhook) requieren autenticación mediante
|
|
sesión PHP.
|
|
|
|
Headers requeridos:
|
|
Cookie: PHPSESSID=abc123...
|
|
|
|
Respuesta de error de autenticación:
|
|
{
|
|
"error": "Acceso denegado. Inicia sesión.",
|
|
"code": 401
|
|
}
|
|
|
|
|
|
ENDPOINTS DE MENSAJERÍA
|
|
------------------------
|
|
|
|
POST /api/send_message.php
|
|
Envía un mensaje de texto individual.
|
|
|
|
Request Body:
|
|
{
|
|
"recipient": "573001234567",
|
|
"message": "Hola, este es un mensaje de prueba",
|
|
"reply_to": "wamid.XXX" // Opcional
|
|
}
|
|
|
|
Response Success:
|
|
{
|
|
"success": true,
|
|
"message_id": "wamid.HBgNNTczMDA...",
|
|
"timestamp": "2024-01-27 14:35:20"
|
|
}
|
|
|
|
Response Error:
|
|
{
|
|
"success": false,
|
|
"error": "Recipient not on WhatsApp"
|
|
}
|
|
|
|
|
|
POST /api/send_template.php
|
|
Envía una plantilla de mensaje.
|
|
|
|
Request Body:
|
|
{
|
|
"recipient": "573001234567",
|
|
"template_name": "welcome_message",
|
|
"language": "es",
|
|
"parameters": {
|
|
"body": ["Juan Pérez", "2024-01-27"],
|
|
"header": []
|
|
}
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"message_id": "wamid.XXX..."
|
|
}
|
|
|
|
|
|
POST /api/send_media_message.php
|
|
Envía un mensaje multimedia.
|
|
|
|
Request Body:
|
|
{
|
|
"recipient": "573001234567",
|
|
"media_type": "image",
|
|
"media_url": "https://ejemplo.com/imagen.jpg",
|
|
"caption": "Mira esta imagen",
|
|
"filename": "imagen.jpg" // Requerido para documentos
|
|
}
|
|
|
|
Tipos de media: image, video, audio, document
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"message_id": "wamid.XXX...",
|
|
"media_id": "123456789"
|
|
}
|
|
|
|
|
|
POST /api/send_broadcast.php
|
|
Envía mensaje masivo.
|
|
|
|
Request Body:
|
|
{
|
|
"message": "Hola a todos, este es un anuncio importante",
|
|
"filter": "active",
|
|
"template_name": null
|
|
}
|
|
|
|
Filtros disponibles:
|
|
- all: Todos los usuarios
|
|
- active: Usuarios activos (< 24h)
|
|
- inactive: Usuarios inactivos
|
|
- custom: Lista personalizada (requiere user_ids array)
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"total_sent": 150,
|
|
"failed": 2,
|
|
"details": [
|
|
{"phone": "573001234567", "status": "sent"},
|
|
{"phone": "573009876543", "status": "failed", "error": "Not on WhatsApp"}
|
|
]
|
|
}
|
|
|
|
|
|
ENDPOINTS DE CONVERSACIONES
|
|
----------------------------
|
|
|
|
GET /api/get_conversations.php
|
|
Lista todas las conversaciones.
|
|
|
|
Query Params:
|
|
- page (int): Número de página (default: 1)
|
|
- limit (int): Conversaciones por página (default: 50, max: 100)
|
|
- filter (string): all | unread | active
|
|
|
|
Ejemplo:
|
|
GET /api/get_conversations.php?page=1&limit=20&filter=unread
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"user_id": 123,
|
|
"name": "Juan Pérez",
|
|
"phone_number": "573001234567",
|
|
"last_message": "Hola, necesito ayuda",
|
|
"last_message_time": "2024-01-27 14:30:45",
|
|
"last_message_direction": "incoming",
|
|
"unread_count": 2,
|
|
"in_service": 1,
|
|
"attended_by": null
|
|
}
|
|
],
|
|
"pagination": {
|
|
"current_page": 1,
|
|
"total_pages": 5,
|
|
"total_items": 98,
|
|
"per_page": 20
|
|
}
|
|
}
|
|
|
|
|
|
GET /api/get_user_messages.php
|
|
Obtiene mensajes de un usuario específico.
|
|
|
|
Query Params:
|
|
- user_id (int): ID del usuario (requerido)
|
|
- limit (int): Número de mensajes (default: 50)
|
|
- before (timestamp): Cargar mensajes anteriores (scroll infinito)
|
|
|
|
Ejemplo:
|
|
GET /api/get_user_messages.php?user_id=123&limit=50
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 456,
|
|
"message_id": "wamid.XXX",
|
|
"user_id": 123,
|
|
"content": "Hola, necesito ayuda",
|
|
"direction": "incoming",
|
|
"message_type": "text",
|
|
"status": "read",
|
|
"media_url": null,
|
|
"local_file": null,
|
|
"reply_to_message_id": null,
|
|
"reaction_emoji": null,
|
|
"created_at": "2024-01-27 14:30:45"
|
|
}
|
|
],
|
|
"has_more": true
|
|
}
|
|
|
|
|
|
POST /api/mark_conversation_read.php
|
|
Marca una conversación como leída.
|
|
|
|
Request Body:
|
|
{
|
|
"user_id": 123
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"message": "Conversación marcada como leída"
|
|
}
|
|
|
|
|
|
ENDPOINTS DE USUARIOS
|
|
----------------------
|
|
|
|
GET /api/get_users.php
|
|
Lista todos los usuarios.
|
|
|
|
Query Params:
|
|
- page (int): Número de página
|
|
- limit (int): Usuarios por página
|
|
- search (string): Buscar por nombre o teléfono
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 123,
|
|
"phone_number": "573001234567",
|
|
"name": "Juan Pérez",
|
|
"email": "juan@example.com",
|
|
"in_service": 1,
|
|
"advisor_requested": 0,
|
|
"last_message_at": "2024-01-27 14:30:45",
|
|
"created_at": "2024-01-20 10:00:00"
|
|
}
|
|
],
|
|
"pagination": {...}
|
|
}
|
|
|
|
|
|
POST /api/update_user.php
|
|
Actualiza información de un usuario.
|
|
|
|
Request Body:
|
|
{
|
|
"user_id": 123,
|
|
"name": "Juan Pérez García",
|
|
"email": "juan.perez@example.com"
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"message": "Usuario actualizado correctamente"
|
|
}
|
|
|
|
|
|
DELETE /api/delete_user.php
|
|
Elimina un usuario y todo su historial.
|
|
|
|
Request Body:
|
|
{
|
|
"user_id": 123
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"message": "Usuario eliminado correctamente"
|
|
}
|
|
|
|
|
|
GET /api/export_users.php
|
|
Exporta usuarios a CSV.
|
|
|
|
Response: Archivo CSV descargable
|
|
|
|
|
|
ENDPOINTS DE MULTIMEDIA
|
|
------------------------
|
|
|
|
POST /api/upload_media.php
|
|
Sube un archivo multimedia.
|
|
|
|
Request: multipart/form-data
|
|
- file (file): Archivo a subir
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"media_id": "123456789",
|
|
"media_url": "https://graph.facebook.com/v22.0/123456789",
|
|
"local_file": "uploads/images/20240127_143520_abc123.jpg",
|
|
"mime_type": "image/jpeg",
|
|
"file_size": 245678
|
|
}
|
|
|
|
|
|
GET /api/get_media.php
|
|
Obtiene URL temporal de un media de WhatsApp.
|
|
|
|
Query Params:
|
|
- id (string): Media ID de WhatsApp
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"url": "https://lookaside.fbsbx.com/whatsapp_business/...",
|
|
"mime_type": "image/jpeg",
|
|
"file_size": 245678,
|
|
"sha256": "abc123...",
|
|
"expires_at": "2024-01-27 15:30:00"
|
|
}
|
|
|
|
|
|
ENDPOINTS DE PLANTILLAS
|
|
------------------------
|
|
|
|
GET /api/get_templates.php
|
|
Lista plantillas de mensaje.
|
|
|
|
Query Params:
|
|
- approved_only (0|1): Solo plantillas aprobadas
|
|
- limit (int): Límite de resultados
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"template_name": "welcome_message",
|
|
"language_code": "es",
|
|
"category": "MARKETING",
|
|
"body_text": "Hola {{1}}, bienvenido...",
|
|
"status": "approved",
|
|
"created_at": "2024-01-20 10:00:00"
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
POST /api/save_template.php
|
|
Crea o actualiza una plantilla.
|
|
|
|
Request Body:
|
|
{
|
|
"template_name": "new_template",
|
|
"language_code": "es",
|
|
"category": "MARKETING",
|
|
"header_text": "Oferta Especial",
|
|
"body_text": "Hola {{1}}, tenemos una oferta...",
|
|
"footer_text": "Válido hasta fin de mes",
|
|
"buttons": [
|
|
{"type": "QUICK_REPLY", "text": "Me interesa"}
|
|
]
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"template_id": 5,
|
|
"message": "Plantilla creada. Pendiente de aprobación."
|
|
}
|
|
|
|
|
|
ENDPOINTS DE RESPUESTAS AUTOMÁTICAS
|
|
-------------------------------------
|
|
|
|
GET /api/get_autoresponses.php
|
|
Lista respuestas automáticas.
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": [
|
|
{
|
|
"id": 1,
|
|
"trigger_keywords": "hola,buenos días,hey",
|
|
"response_message": "¡Hola! Bienvenido...",
|
|
"is_active": 1,
|
|
"priority": 1
|
|
}
|
|
]
|
|
}
|
|
|
|
|
|
POST /api/save_autoresponse.php
|
|
Crea o actualiza respuesta automática.
|
|
|
|
Request Body:
|
|
{
|
|
"id": null,
|
|
"trigger_keywords": "precio,costo,cuanto cuesta",
|
|
"response_message": "Nuestros precios varían...",
|
|
"is_active": 1,
|
|
"priority": 5
|
|
}
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"id": 3,
|
|
"message": "Respuesta automática guardada"
|
|
}
|
|
|
|
|
|
ENDPOINTS DE ESTADÍSTICAS
|
|
---------------------------
|
|
|
|
GET /api/get_stats.php
|
|
Obtiene estadísticas del dashboard.
|
|
|
|
Response:
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"total_users": 1250,
|
|
"messages_received_24h": 340,
|
|
"messages_sent_24h": 285,
|
|
"active_conversations": 45,
|
|
"messages_by_hour": [
|
|
{"hour": "00:00", "incoming": 5, "outgoing": 2},
|
|
...
|
|
],
|
|
"messages_by_day": [
|
|
{"date": "2024-01-21", "incoming": 120, "outgoing": 95},
|
|
...
|
|
],
|
|
"top_users": [
|
|
{"user_id": 123, "name": "Juan Pérez", "message_count": 45}
|
|
]
|
|
}
|
|
}
|
|
|
|
|
|
ENDPOINT DE WEBHOOK
|
|
-------------------
|
|
|
|
POST /api/webhook.php
|
|
Recibe eventos de WhatsApp Business API.
|
|
|
|
Verificación (GET):
|
|
GET /api/webhook.php?hub.mode=subscribe&hub.challenge=123456&hub.verify_token=token
|
|
|
|
Response: 123456 (echo del challenge)
|
|
|
|
Eventos recibidos (POST):
|
|
|
|
Nuevo mensaje:
|
|
{
|
|
"object": "whatsapp_business_account",
|
|
"entry": [{
|
|
"changes": [{
|
|
"value": {
|
|
"messaging_product": "whatsapp",
|
|
"messages": [{
|
|
"from": "573001234567",
|
|
"id": "wamid.XXX",
|
|
"timestamp": "1706367000",
|
|
"type": "text",
|
|
"text": {
|
|
"body": "Hola, necesito ayuda"
|
|
}
|
|
}]
|
|
}
|
|
}]
|
|
}]
|
|
}
|
|
|
|
Estado de mensaje:
|
|
{
|
|
"entry": [{
|
|
"changes": [{
|
|
"value": {
|
|
"statuses": [{
|
|
"id": "wamid.XXX",
|
|
"status": "read",
|
|
"timestamp": "1706367100",
|
|
"recipient_id": "573001234567"
|
|
}]
|
|
}
|
|
}]
|
|
}]
|
|
}
|
|
|
|
Tipos de status:
|
|
- sent: Enviado
|
|
- delivered: Entregado
|
|
- read: Leído
|
|
- failed: Fallido
|
|
|
|
|
|
ENDPOINTS SSE
|
|
-------------
|
|
|
|
GET /api/sse_events.php
|
|
Conexión de Server-Sent Events para notificaciones en tiempo real.
|
|
|
|
Headers:
|
|
Content-Type: text/event-stream
|
|
Cache-Control: no-cache
|
|
Connection: keep-alive
|
|
|
|
Eventos enviados:
|
|
event: message
|
|
data: {"type":"new_message","user_id":123,"content":"Hola"}
|
|
|
|
event: heartbeat
|
|
data: {"timestamp":"2024-01-27 14:35:00"}
|
|
|
|
|
|
CÓDIGOS DE ESTADO HTTP
|
|
-----------------------
|
|
|
|
Código Significado
|
|
------------------------------------------------------------------------
|
|
200 Éxito
|
|
201 Creado
|
|
400 Petición inválida
|
|
401 No autenticado
|
|
403 Sin permisos
|
|
404 No encontrado
|
|
405 Método no permitido
|
|
429 Demasiadas peticiones (rate limit)
|
|
500 Error del servidor
|
|
503 Servicio no disponible
|
|
|
|
|
|
================================================================================
|
|
5. GUÍA DE IMPLEMENTACIÓN
|
|
================================================================================
|
|
|
|
5.1. Instalación desde Cero
|
|
-----------------------------
|
|
|
|
REQUISITOS DEL SERVIDOR
|
|
------------------------
|
|
|
|
Mínimos:
|
|
- CPU: 2 cores
|
|
- RAM: 4 GB
|
|
- Disco: 20 GB SSD
|
|
- SO: Ubuntu 22.04 LTS, Debian 11+, CentOS 8+
|
|
|
|
Recomendados para producción:
|
|
- CPU: 4+ cores
|
|
- RAM: 8+ GB
|
|
- Disco: 50+ GB SSD
|
|
- SO: Ubuntu 22.04 LTS
|
|
|
|
|
|
OPCIÓN 1: Docker (Recomendado)
|
|
-------------------------------
|
|
|
|
1. Instalar Docker y Docker Compose
|
|
|
|
Ubuntu/Debian:
|
|
sudo apt update
|
|
sudo apt install -y docker.io docker-compose
|
|
|
|
Verificar instalación:
|
|
docker --version
|
|
docker-compose --version
|
|
|
|
2. Clonar Repositorio
|
|
|
|
git clone https://github.com/tu-usuario/whatsapp.git
|
|
cd whatsapp
|
|
|
|
3. Configurar Variables de Entorno
|
|
|
|
cp .env.example .env
|
|
nano .env
|
|
|
|
Editar .env:
|
|
# Base de datos
|
|
DB_HOST=db
|
|
DB_PORT=3306
|
|
DB_NAME=whatsapp_bot
|
|
DB_USER=whatsapp_user
|
|
DB_PASS=tu_password_seguro
|
|
|
|
# WhatsApp Business API
|
|
WHATSAPP_TOKEN=tu_access_token
|
|
WHATSAPP_PHONE_ID=tu_phone_id
|
|
WHATSAPP_BUSINESS_ACCOUNT_ID=tu_business_account_id
|
|
WHATSAPP_APP_ID=tu_app_id
|
|
WHATSAPP_APP_SECRET=tu_app_secret
|
|
|
|
# Webhook
|
|
WEBHOOK_VERIFY_TOKEN=tu_token_verificacion_webhook
|
|
|
|
# Sistema
|
|
APP_ENV=production
|
|
APP_DEBUG=false
|
|
APP_TIMEZONE=America/Bogota
|
|
|
|
4. Levantar Contenedores
|
|
|
|
Desarrollo:
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
|
Producción:
|
|
docker-compose -f docker-compose.prod.yml up -d
|
|
|
|
5. Verificar Estado
|
|
|
|
docker-compose ps
|
|
|
|
Deberías ver:
|
|
NAME STATUS
|
|
whatsapp-app Up
|
|
whatsapp-db Up
|
|
whatsapp-redis Up
|
|
whatsapp-worker Up
|
|
whatsapp-nginx Up
|
|
|
|
6. Acceder a la Aplicación
|
|
|
|
App: http://tu-servidor:8080 (dev) o http://tu-dominio (prod)
|
|
phpMyAdmin: http://tu-servidor:8084 (dev)
|
|
|
|
7. Configurar en el Panel
|
|
|
|
1. Accede con las credenciales por defecto:
|
|
Usuario: admin
|
|
Password: password123
|
|
2. Cambia la contraseña inmediatamente
|
|
3. Ve a Configuración > WhatsApp API y completa los datos
|
|
4. Verifica la configuración
|
|
|
|
|
|
OPCIÓN 2: Instalación Manual
|
|
------------------------------
|
|
|
|
1. Instalar Stack LAMP
|
|
|
|
Ubuntu 22.04:
|
|
sudo apt update
|
|
sudo apt install -y apache2 mariadb-server php8.2 php8.2-mysql \
|
|
php8.2-curl php8.2-mbstring php8.2-xml php8.2-gd php8.2-zip \
|
|
php8.2-redis redis-server
|
|
|
|
Verificar PHP:
|
|
php -v
|
|
|
|
2. Configurar MariaDB
|
|
|
|
sudo mysql_secure_installation
|
|
|
|
Crear base de datos:
|
|
sudo mysql -u root -p
|
|
|
|
SQL:
|
|
CREATE DATABASE whatsapp_bot CHARACTER SET utf8mb4
|
|
COLLATE utf8mb4_unicode_ci;
|
|
CREATE USER 'whatsapp_user'@'localhost'
|
|
IDENTIFIED BY 'tu_password_seguro';
|
|
GRANT ALL PRIVILEGES ON whatsapp_bot.*
|
|
TO 'whatsapp_user'@'localhost';
|
|
FLUSH PRIVILEGES;
|
|
EXIT;
|
|
|
|
3. Clonar y Configurar Aplicación
|
|
|
|
cd /var/www/html
|
|
sudo git clone https://github.com/tu-usuario/whatsapp.git
|
|
cd whatsapp
|
|
|
|
Permisos:
|
|
sudo chown -R www-data:www-data /var/www/html/whatsapp
|
|
sudo chmod -R 755 /var/www/html/whatsapp
|
|
sudo chmod -R 777 /var/www/html/whatsapp/uploads
|
|
sudo chmod -R 777 /var/www/html/whatsapp/logs
|
|
|
|
Configurar .env:
|
|
cp .env.example .env
|
|
sudo nano .env
|
|
|
|
4. Importar Base de Datos
|
|
|
|
mysql -u whatsapp_user -p whatsapp_bot < \
|
|
database/migrations/001_initial_schema.sql
|
|
mysql -u whatsapp_user -p whatsapp_bot < \
|
|
database/migrations/002_add_media_fields.sql
|
|
|
|
5. Configurar Apache
|
|
|
|
sudo nano /etc/apache2/sites-available/whatsapp.conf
|
|
|
|
Contenido:
|
|
<VirtualHost *:80>
|
|
ServerName tudominio.com
|
|
DocumentRoot /var/www/html/whatsapp
|
|
|
|
<Directory /var/www/html/whatsapp>
|
|
Options -Indexes +FollowSymLinks
|
|
AllowOverride All
|
|
Require all granted
|
|
</Directory>
|
|
|
|
ErrorLog ${APACHE_LOG_DIR}/whatsapp_error.log
|
|
CustomLog ${APACHE_LOG_DIR}/whatsapp_access.log combined
|
|
</VirtualHost>
|
|
|
|
Habilitar sitio:
|
|
sudo a2ensite whatsapp.conf
|
|
sudo a2enmod rewrite
|
|
sudo systemctl restart apache2
|
|
|
|
6. Configurar SSL con Let's Encrypt
|
|
|
|
sudo apt install -y certbot python3-certbot-apache
|
|
sudo certbot --apache -d tudominio.com
|
|
|
|
7. Configurar Worker (Supervisor)
|
|
|
|
sudo apt install -y supervisor
|
|
sudo cp supervisor-whatsapp-worker.conf \
|
|
/etc/supervisor/conf.d/whatsapp-worker.conf
|
|
sudo supervisorctl reread
|
|
sudo supervisorctl update
|
|
sudo supervisorctl start whatsapp-worker:*
|
|
|
|
8. Configurar Cron Jobs
|
|
|
|
sudo crontab -e
|
|
|
|
Agregar:
|
|
# Limpiar logs antiguos (diario a las 3am)
|
|
0 3 * * * cd /var/www/html/whatsapp && \
|
|
php scripts/clean_old_logs.php
|
|
|
|
# Backup de base de datos (diario a las 2am)
|
|
0 2 * * * /usr/bin/mysqldump -u whatsapp_user \
|
|
-p'tu_password' whatsapp_bot > \
|
|
/var/www/html/whatsapp/database/backups/backup_$(date +\%Y\%m\%d_\%H\%M\%S).sql
|
|
|
|
# Limpiar backups antiguos (mantener últimos 7 días)
|
|
0 4 * * * find /var/www/html/whatsapp/database/backups \
|
|
-name "backup_*.sql" -mtime +7 -delete
|
|
|
|
|
|
5.2. Configuración de Producción
|
|
----------------------------------
|
|
|
|
OPTIMIZACIÓN DE PHP
|
|
-------------------
|
|
|
|
Editar /etc/php/8.2/apache2/php.ini:
|
|
|
|
memory_limit = 256M
|
|
post_max_size = 100M
|
|
upload_max_filesize = 100M
|
|
max_execution_time = 300
|
|
max_input_time = 300
|
|
|
|
; Para SSE (Server-Sent Events)
|
|
output_buffering = Off
|
|
implicit_flush = On
|
|
|
|
; Seguridad
|
|
expose_php = Off
|
|
display_errors = Off
|
|
log_errors = On
|
|
error_log = /var/log/php/error.log
|
|
|
|
; Zona horaria
|
|
date.timezone = America/Bogota
|
|
|
|
|
|
OPTIMIZACIÓN DE MariaDB
|
|
------------------------
|
|
|
|
Editar /etc/mysql/mariadb.conf.d/50-server.cnf:
|
|
|
|
[mysqld]
|
|
# Memoria
|
|
innodb_buffer_pool_size = 2G
|
|
innodb_log_file_size = 256M
|
|
|
|
# Conexiones
|
|
max_connections = 200
|
|
|
|
# Charset
|
|
character-set-server = utf8mb4
|
|
collation-server = utf8mb4_unicode_ci
|
|
|
|
# Logs
|
|
slow_query_log = 1
|
|
slow_query_log_file = /var/log/mysql/slow-query.log
|
|
long_query_time = 2
|
|
|
|
# Índices
|
|
innodb_flush_log_at_trx_commit = 2
|
|
innodb_flush_method = O_DIRECT
|
|
|
|
Reiniciar:
|
|
sudo systemctl restart mariadb
|
|
|
|
|
|
FIREWALL
|
|
--------
|
|
|
|
UFW (Ubuntu):
|
|
sudo ufw allow 22/tcp
|
|
sudo ufw allow 80/tcp
|
|
sudo ufw allow 443/tcp
|
|
sudo ufw enable
|
|
sudo ufw status
|
|
|
|
|
|
MONITOREO
|
|
---------
|
|
|
|
Instalar Monit:
|
|
sudo apt install -y monit
|
|
sudo nano /etc/monit/monitrc
|
|
|
|
Configurar:
|
|
set daemon 60
|
|
set logfile /var/log/monit.log
|
|
|
|
check process apache2 with pidfile /var/run/apache2/apache2.pid
|
|
start program = "/usr/sbin/service apache2 start"
|
|
stop program = "/usr/sbin/service apache2 stop"
|
|
if failed host localhost port 80 protocol http then restart
|
|
if 5 restarts within 5 cycles then timeout
|
|
|
|
check process mysql with pidfile /var/run/mysqld/mysqld.pid
|
|
start program = "/usr/sbin/service mysql start"
|
|
stop program = "/usr/sbin/service mysql stop"
|
|
if failed host localhost port 3306 protocol mysql then restart
|
|
if 5 restarts within 5 cycles then timeout
|
|
|
|
check process redis with pidfile /var/run/redis/redis-server.pid
|
|
start program = "/usr/sbin/service redis-server start"
|
|
stop program = "/usr/sbin/service redis-server stop"
|
|
if failed host localhost port 6379 protocol redis then restart
|
|
|
|
Iniciar:
|
|
sudo systemctl enable monit
|
|
sudo systemctl start monit
|
|
|
|
|
|
5.3. Actualización del Sistema
|
|
--------------------------------
|
|
|
|
PROCESO DE ACTUALIZACIÓN
|
|
-------------------------
|
|
|
|
1. Backup completo
|
|
./scripts/backup_all.sh
|
|
|
|
2. Modo mantenimiento
|
|
touch maintenance.lock
|
|
|
|
3. Actualizar código
|
|
git pull origin main
|
|
|
|
4. Ejecutar migraciones
|
|
php scripts/run_migrations.php
|
|
|
|
5. Limpiar cache
|
|
php scripts/clear_cache.php
|
|
|
|
6. Reiniciar servicios
|
|
sudo systemctl restart apache2
|
|
sudo supervisorctl restart whatsapp-worker:*
|
|
|
|
7. Verificar funcionamiento
|
|
php scripts/check_health.php
|
|
|
|
8. Desactivar modo mantenimiento
|
|
rm maintenance.lock
|
|
|
|
|
|
================================================================================
|
|
6. CASOS DE USO
|
|
================================================================================
|
|
|
|
CASO 1: Atención al Cliente Automatizada
|
|
------------------------------------------
|
|
|
|
Escenario: Una empresa de e-commerce quiere automatizar respuestas a
|
|
preguntas frecuentes.
|
|
|
|
Implementación:
|
|
1. Configurar respuestas automáticas con triggers específicos
|
|
2. Crear menú interactivo de opciones principales
|
|
3. Configurar horario de atención para transferencia a humano
|
|
4. Resultado: Reducción de 70% en consultas repetitivas
|
|
|
|
|
|
CASO 2: Campañas de Marketing
|
|
-------------------------------
|
|
|
|
Escenario: Lanzamiento de nueva colección, enviar anuncio a clientes activos.
|
|
|
|
Implementación:
|
|
1. Crear plantilla en Meta con variables dinámicas
|
|
2. Enviar broadcast con filtro de usuarios activos
|
|
3. Seguimiento de métricas (enviados, leídos, interacciones)
|
|
4. Resultado: 300% ROI, 36% tasa de apertura, 9% conversión
|
|
|
|
|
|
CASO 3: Soporte Técnico con Tickets
|
|
-------------------------------------
|
|
|
|
Escenario: Empresa de software que recibe consultas técnicas.
|
|
|
|
Implementación:
|
|
1. Crear sistema de tickets automático
|
|
2. Escalamiento automático según palabras clave
|
|
3. Vinculación de respuestas a tickets
|
|
4. Sistema de calificación de servicio
|
|
5. Resultado: Tiempo de respuesta 15 minutos, satisfacción 4.5/5
|
|
|
|
|
|
CASO 4: Reservas y Citas
|
|
--------------------------
|
|
|
|
Escenario: Clínica médica permite agendar citas por WhatsApp.
|
|
|
|
Implementación:
|
|
1. Menú de especialidades
|
|
2. Sistema de calendario con disponibilidad
|
|
3. Confirmación automática de citas
|
|
4. Recordatorios 24h antes
|
|
5. Resultado: 80% de citas agendadas fuera de horario
|
|
|
|
|
|
CASO 5: Encuestas y Feedback
|
|
------------------------------
|
|
|
|
Escenario: Recopilar feedback post-compra.
|
|
|
|
Implementación:
|
|
1. Envío automático de encuesta 24h después de compra
|
|
2. Procesamiento inteligente de respuestas
|
|
3. Escalamiento de casos negativos
|
|
4. Dashboard de resultados y análisis
|
|
5. Resultado: 350 respuestas en 1 semana, NPS de 72
|
|
|
|
|
|
================================================================================
|
|
7. ENTREGABLES DEL PROYECTO
|
|
================================================================================
|
|
|
|
1. CÓDIGO FUENTE COMPLETO
|
|
- Código PHP backend (42 APIs, servicios, clases)
|
|
- Frontend (HTML, CSS, JavaScript)
|
|
- Configuración Docker (dev y prod)
|
|
- Scripts SQL (esquema, migraciones)
|
|
- Tests automatizados
|
|
|
|
2. DOCUMENTACIÓN COMPLETA
|
|
- README.md
|
|
- DOCUMENTACION_COMPLETA.md (este documento)
|
|
- REPORTE_SISTEMA_COMPLETO.md
|
|
- DEPLOYMENT_GUIDE.md
|
|
- DOCKER_README.md
|
|
- SSE_REALTIME_DOCS.md
|
|
- API_REFERENCE.md
|
|
|
|
3. BASE DE DATOS
|
|
- Esquema completo (schema_complete.sql)
|
|
- Migraciones ordenadas
|
|
- Scripts de mantenimiento
|
|
|
|
4. CONFIGURACIÓN DE SERVIDOR
|
|
- Nginx configuration
|
|
- Apache vhost configuration
|
|
- Supervisor configuration
|
|
- Cron jobs
|
|
|
|
5. SCRIPTS DE UTILIDAD
|
|
- install.php (Instalador interactivo)
|
|
- run_migrations.php
|
|
- clean_old_logs.php
|
|
- backup_database.sh
|
|
- restore_backup.sh
|
|
- check_health.php
|
|
- test_whatsapp_connection.php
|
|
- generate_report.php
|
|
|
|
6. TESTS AUTOMATIZADOS
|
|
- Tests unitarios
|
|
- Tests de integración
|
|
- Coverage reports
|
|
|
|
7. DOCKER COMPOSE
|
|
- docker-compose.dev.yml (Desarrollo)
|
|
- docker-compose.prod.yml (Producción)
|
|
|
|
8. MANUALES DE USUARIO
|
|
- Manual de usuario final (PDF)
|
|
- Manual de administrador (PDF)
|
|
|
|
9. VIDEO TUTORIALES
|
|
- Instalación y configuración inicial (15 min)
|
|
- Configurar WhatsApp Business API (10 min)
|
|
- Gestión de conversaciones (8 min)
|
|
- Crear respuestas automáticas (7 min)
|
|
- Enviar mensajes masivos (6 min)
|
|
- Crear plantillas de WhatsApp (12 min)
|
|
- Administración de usuarios (5 min)
|
|
- Interpretar estadísticas (8 min)
|
|
- Solución de problemas comunes (10 min)
|
|
- Actualización del sistema (7 min)
|
|
|
|
10. LICENCIA Y GARANTÍA
|
|
- 30 días de soporte post-entrega
|
|
- Corrección de bugs sin costo
|
|
- Actualizaciones de seguridad durante 1 año
|
|
- Consultoría técnica (10 horas incluidas)
|
|
|
|
11. ACCESOS Y CREDENCIALES
|
|
- Credenciales de admin por defecto
|
|
- Accesos a servidor (SSH)
|
|
- Credenciales de base de datos
|
|
- Tokens de WhatsApp Business API
|
|
|
|
12. CHECKLIST DE ENTREGA
|
|
- Pre-Entrega
|
|
- Entrega
|
|
- Post-Entrega
|
|
|
|
|
|
================================================================================
|
|
8. MANTENIMIENTO Y SOPORTE
|
|
================================================================================
|
|
|
|
8.1. Tareas de Mantenimiento
|
|
------------------------------
|
|
|
|
DIARIO (Automatizado)
|
|
----------------------
|
|
1. Backup de base de datos (2:00 AM, retención 7 días)
|
|
2. Limpieza de logs (3:00 AM, retención 30 días)
|
|
3. Verificación de salud (cada hora)
|
|
|
|
SEMANAL
|
|
-------
|
|
1. Optimización de base de datos
|
|
2. Revisión de logs de error
|
|
3. Actualización de dependencias
|
|
|
|
MENSUAL
|
|
-------
|
|
1. Auditoría de seguridad
|
|
2. Análisis de uso y optimización
|
|
3. Backup completo
|
|
|
|
|
|
8.2. Monitoreo
|
|
---------------
|
|
|
|
MÉTRICAS CLAVE
|
|
--------------
|
|
Métrica Umbral Acción
|
|
------------------------------------------------------------------------
|
|
CPU > 80% 5 min Escalar recursos
|
|
RAM > 90% 5 min Revisar memory leaks
|
|
Disco > 85% - Limpiar archivos antiguos
|
|
Respuesta API > 2s - Optimizar queries
|
|
Errores > 10/min - Investigar logs
|
|
|
|
|
|
8.3. Solución de Problemas Comunes
|
|
------------------------------------
|
|
|
|
1. MENSAJES NO SE ENVÍAN
|
|
Síntomas: API retorna error 401 o 403
|
|
Solución:
|
|
- Verificar token de acceso
|
|
- Regenerar token si expiró
|
|
- Verificar permisos del token en Meta
|
|
|
|
2. WEBHOOK NO RECIBE EVENTOS
|
|
Síntomas: No llegan mensajes nuevos
|
|
Solución:
|
|
- Verificar URL del webhook en Meta
|
|
- Revisar logs de webhook
|
|
- Verificar suscripción a eventos
|
|
- Probar manualmente con curl
|
|
|
|
3. SSE NO FUNCIONA
|
|
Síntomas: No hay notificaciones en tiempo real
|
|
Solución:
|
|
- Verificar que Redis esté corriendo
|
|
- Revisar configuración PHP (output_buffering=Off)
|
|
- Verificar soporte SSE en navegador
|
|
- Revisar logs del navegador
|
|
|
|
4. MULTIMEDIA NO SE DESCARGA
|
|
Síntomas: Imágenes/videos no se muestran
|
|
Solución:
|
|
- Verificar permisos de carpeta uploads/
|
|
- Verificar espacio en disco
|
|
- Revisar logs de descarga
|
|
- Verificar permisos del token
|
|
|
|
5. ALTO USO DE CPU/RAM
|
|
Síntomas: Sistema lento, timeouts
|
|
Solución:
|
|
- Identificar procesos pesados con top
|
|
- Optimizar consultas lentas
|
|
- Aumentar recursos del servidor
|
|
- Activar cache (Redis/Memcached)
|
|
- Optimizar tablas de base de datos
|
|
|
|
|
|
8.4. Contacto de Soporte
|
|
--------------------------
|
|
|
|
Desarrollado por: U-Site.app
|
|
|
|
Canales de soporte:
|
|
- Email: soporte@u-site.app
|
|
- WhatsApp: +57 XXX XXX XXXX
|
|
- Portal: https://u-site.app/soporte
|
|
- Telegram: @usiteapp_soporte
|
|
|
|
Horario de soporte:
|
|
- Lunes a Viernes: 9:00 AM - 6:00 PM (GMT-5)
|
|
- Emergencias críticas: 24/7 (solo clientes premium)
|
|
|
|
Niveles de soporte:
|
|
- Básico (incluido): Email, respuesta en 24-48h
|
|
- Estándar: Email + WhatsApp, respuesta en 12h
|
|
- Premium: Email + WhatsApp + Teléfono, respuesta en 2h, atención 24/7
|
|
|
|
|
|
================================================================================
|
|
LICENCIA
|
|
================================================================================
|
|
|
|
© 2024-2026 U-Site.app. Todos los derechos reservados.
|
|
|
|
Este software es propiedad de U-Site.app y está protegido por las leyes
|
|
de derechos de autor.
|
|
|
|
Permisos:
|
|
- Uso en producción para el cliente que adquirió la licencia
|
|
- Modificaciones para uso interno
|
|
- Despliegue en múltiples instancias del mismo cliente
|
|
|
|
Prohibido:
|
|
- Redistribución del código fuente
|
|
- Reventa o sublicencia
|
|
- Uso en proyectos de terceros sin autorización
|
|
|
|
Para consultas sobre licenciamiento, contacta: licencias@u-site.app
|
|
|
|
|
|
================================================================================
|
|
CONCLUSIÓN
|
|
================================================================================
|
|
|
|
Este sistema de WhatsApp Bot Manager representa una solución completa y
|
|
profesional para gestión de comunicaciones empresariales vía WhatsApp Business.
|
|
|
|
CARACTERÍSTICAS DESTACADAS:
|
|
- 42 endpoints API REST documentados
|
|
- Interfaz moderna y responsive
|
|
- Tiempo real con SSE
|
|
- Bot inteligente y configurable
|
|
- Soporte multimedia completo
|
|
- Seguridad robusta
|
|
- Docker ready
|
|
- Escalable y mantenible
|
|
|
|
CASOS DE USO VALIDADOS:
|
|
- Atención al cliente automatizada
|
|
- Campañas de marketing masivas
|
|
- Soporte técnico con tickets
|
|
- Reservas y citas
|
|
- Encuestas y feedback
|
|
|
|
PRÓXIMOS PASOS SUGERIDOS:
|
|
1. Revisar la documentación completa
|
|
2. Seguir la guía de instalación
|
|
3. Configurar WhatsApp Business API
|
|
4. Personalizar respuestas automáticas
|
|
5. Capacitar al equipo
|
|
6. Lanzar en producción
|
|
7. Monitorear y optimizar
|
|
|
|
¿Necesitas ayuda? Contacta al equipo de U-Site.app:
|
|
|
|
Website: u-site.app
|
|
Email: contacto@u-site.app
|
|
WhatsApp: +57 XXX XXX XXXX
|
|
|
|
|
|
================================================================================
|
|
Desarrollado con amor por U-Site.app
|
|
Simplificando la comunicación empresarial
|
|
================================================================================
|