Thanks to visit codestin.com
Credit goes to Github.com

Skip to content

JoZeuZ/AlpixChatbot_DF_TW

BranchesTags

Repository files navigation

Bot de WhatsApp Alpix Chile - Twilio/Dialogflow Integration

Status Platform Integración

📋 Tabla de Contenidos

🎯 Descripción del Proyecto

El Bot de WhatsApp Alpix Chile es un asistente virtual inteligente diseñado para automatizar la atención al cliente y generar leads para los cursos de capacitación industrial de Alpix Chile. Especializado en:

  • Cursos IRATA - Certificación en trabajo con cuerdas y acceso por cuerdas
  • Cursos GWO - Certificación para la industria eólica (BST y ART)
  • Promociones combinadas - Ofertas especiales IRATA + GWO
  • FAQ automatizadas - Respuestas a preguntas frecuentes
  • Derivación inteligente - Conexión con asesores humanos cuando es necesario

📊 Métricas de Rendimiento

  • Automatización: ~80% de consultas resueltas sin intervención humana
  • Tiempo de respuesta: < 3 segundos promedio
  • Conversión: Tracking automático de leads en HubSpot
  • Disponibilidad: 24/7 con monitoreo automático

🏗️ Arquitectura del Bot

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   WhatsApp      │    │     Twilio       │    │   Cloud Run     │
│   Business      │◄──►│   WhatsApp API   │◄──►│  (server.js)    │
│                 │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                        │
                       ┌─────────────────┐              │
                       │   Dialogflow    │◄─────────────┤
                       │   (NLU/Intent   │              │
                       │   Recognition)  │              │
                       └─────────────────┘              │
                                                        │
                       ┌─────────────────┐              │
                       │    HubSpot      │◄─────────────┘
                       │   (CRM/Lead     │
                       │   Tracking)     │
                       └─────────────────┘

Componentes Principales

1. Frontend (WhatsApp)

  • Número empresarial: +56 9 5659 4744
  • Interfaz nativa de WhatsApp
  • Soporte para textos, botones interactivos y documentos PDF

2. API Gateway (Twilio)

  • Manejo de mensajes bidireccionales
  • Templates de WhatsApp Business
  • Gestión de medios (PDFs)
  • Webhooks para eventos en tiempo real

3. Lógica de Negocio (Cloud Run)

  • Ruta principal (/): Procesamiento de mensajes de Twilio
  • Ruta fulfillment (/fulfillment): Webhook de Dialogflow
  • Reconocimiento inteligente de intenciones
  • Gestión de contextos y estados de conversación

4. NLU/NLP (Dialogflow)

  • Reconocimiento de intenciones
  • Extracción de entidades
  • Manejo de contextos conversacionales
  • Fallback inteligente

5. CRM Integration (HubSpot)

  • Creación/actualización automática de contactos
  • Tracking de eventos e interacciones
  • Generación de tickets para leads calientes
  • Analytics y reporting

🚀 Funcionalidades Principales

1. Selección de Cursos

  • IRATA (3 niveles): Nivel 1, 2 y 3
  • GWO (2 tipos): BST (Primera vez) y ART (Actualización/Avanzado)
  • Promociones combinadas: PROMO 1 (IRATA + BST) y PROMO 2 (IRATA + BST + ART)

2. Envío Inteligente de PDFs

  • PDFs específicos por curso con información detallada
  • Envío automático tras selección de curso
  • Promociones optimizadas:
    • PROMO 1 → Solo PDF de BST (contiene info completa)
    • PROMO 2 → Solo PDF de ART (contiene info completa)

3. FAQ Dinámicas

  • Precios y métodos de pago
  • Duración y cronogramas
  • Requisitos de inscripción
  • Ubicación y direcciones
  • Respuestas contextualizadas según el curso de interés

4. Navegación Inteligente

  • Reconocimiento de abreviaciones: "L1", "BST", "IRATA"
  • Fallback contextualizado: Ayuda específica según el estado
  • Limpieza automática de contextos
  • Transiciones fluidas entre secciones

5. Derivación a Asesores

  • Links personalizados de WhatsApp con contexto
  • Mensaje pre-escrito con información del curso de interés
  • Escalamiento automático para consultas complejas

⚙️ Configuración del Entorno

Variables de Entorno Requeridas

Crear archivo .env en /twilio/ con:

# === CREDENCIALES TWILIO ===
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# === INTEGRACIÓN HUBSPOT ===
HUBSPOT_API_KEY=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# === CONFIGURACIÓN DIALOGFLOW ===
GOOGLE_APPLICATION_CREDENTIALS=./dialogflow-key.json
PROJECT_ID=alpixchat

# === CONFIGURACIÓN DEL SERVIDOR ===
PORT=8080
NODE_ENV=production

Archivos de Configuración

  1. /twilio/.env - Variables de entorno de producción
  2. /twilio/.env.example - Template de variables (sin valores sensibles)
  3. /twilio/dialogflow-key.json - Credenciales de servicio de Google Cloud
  4. cloudbuild.yaml - Configuración de build para Cloud Run
  5. Dockerfile - Configuración de contenedor

PDFs y Recursos

Todos los PDFs están almacenados en Google Cloud Storage:

// URLs centralizadas en server.js
const IRATA_NIVEL_1_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%201.pdf";
const IRATA_NIVEL_2_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%202.pdf";
const IRATA_NIVEL_3_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%203.pdf";
const BST_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20CURSO%20%20BST.pdf";
const ART_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20CURSO%20ART.pdf";

🚀 Despliegue

Prerrequisitos

  1. Configuración de gcloud CLI

    # Verificar proyecto configurado
gcloud config get-value project

# Configurar proyecto si es necesario
gcloud config set project alpixchat

  2. Habilitación de APIs

    # Habilitar Cloud Build y Cloud Run
gcloud services enable cloudbuild.googleapis.com
gcloud services enable run.googleapis.com

  3. Configuración de Service Account

    • Crear Service Account con rol "Dialogflow API Client"
    • Descargar key JSON y colocar en /twilio/dialogflow-key.json

Despliegue Automático

# Clonar repositorio
git clone [repository-url]
cd dialogflow-integrations

# Configurar variables de entorno
cp twilio/.env.example twilio/.env
# Editar twilio/.env con las credenciales reales

# Desplegar a Cloud Run
gcloud builds submit --config cloudbuild.yaml .

Configuración Manual del Dockerfile

Editar Dockerfile en la raíz:

# Configurar integración específica
ENV INTEGRATION=twilio

Verificación del Despliegue

# Listar servicios activos
gcloud run services list

# Verificar logs
gcloud run services logs tail dialogflow-twilio

# Probar endpoint
curl -X POST https://[SERVICE-URL]/ \
  -H "Content-Type: application/json" \
  -d '{"test": "message"}'

🔄 Flujos de Conversación

Flujo Principal de Selección de Cursos

graph TD
    A[Usuario inicia conversación] --> B[Saludo + Menú principal]
    B --> C{Selección}
    C -->|IRATA| D[Submenú IRATA Niveles]
    C -->|GWO| E[Submenú GWO]
    C -->|Promociones| F[Submenú Promociones]
    C -->|FAQ| G[Preguntas Frecuentes]
    
    D --> D1[Nivel 1] --> H[Envío PDF + FAQ]
    D --> D2[Nivel 2] --> H
    D --> D3[Nivel 3] --> H
    
    E --> E1[BST] --> H
    E --> E2[ART] --> H
    
    F --> F1[PROMO 1: IRATA+BST] --> I[Envío PDF BST + FAQ]
    F --> F2[PROMO 2: IRATA+BST+ART] --> J[Envío PDF ART + FAQ]
    
    H --> K[¿Más información?]
    I --> K
    J --> K
    K -->|Sí| G
    K -->|No| L[Derivar a asesor]
    G --> K
Loading

Estados y Contextos Manejados

Estados Principales:

  1. INICIO - Menú principal
  2. IRATA_MENU - Selección de nivel IRATA
  3. GWO_MENU - Selección BST/ART
  4. PROMO_MENU - Selección de promociones
  5. FAQ_ACTIVE - Modo preguntas frecuentes
  6. CURSO_SELECTED - Curso seleccionado, esperando acción

Contextos de Dialogflow:

  • curso-context (5 turnos) - Mantiene curso seleccionado
  • faq-context (3 turnos) - Contexto de FAQ activo
  • promo-context (5 turnos) - Contexto de promociones

Reconocimiento de Intenciones

// Intenciones principales en Dialogflow
const INTENTS = {
  'curso.irata.nivel1': 'Selección IRATA Nivel 1',
  'curso.irata.nivel2': 'Selección IRATA Nivel 2',
  'curso.irata.nivel3': 'Selección IRATA Nivel 3',
  'curso.gwo.bst': 'Selección GWO BST',
  'curso.gwo.art': 'Selección GWO ART',
  'promocion.1': 'Promoción IRATA + BST',
  'promocion.2': 'Promoción IRATA + BST + ART',
  'faq.precio': 'Preguntas sobre precios',
  'faq.duracion': 'Preguntas sobre duración',
  'faq.requisitos': 'Preguntas sobre requisitos',
  'hablar.asesor': 'Solicitud de asesor humano'
};

📊 Tracking y Analytics

Integración con HubSpot

Eventos Tracked Automáticamente:

  1. Conversación Iniciada

    {
  eventType: 'bot_conversation_started',
  phone: userPhone,
  timestamp: new Date().toISOString()
}

  2. Curso Seleccionado

    {
  eventType: 'course_selected',
  phone: userPhone,
  course: 'IRATA_NIVEL_1', // BST, ART, PROMO_1, PROMO_2
  timestamp: new Date().toISOString()
}

  3. PDF Enviado

    {
  eventType: 'pdf_sent',
  phone: userPhone,
  course: courseName,
  pdfUrl: pdfUrl,
  timestamp: new Date().toISOString()
}

  4. FAQ Consultada

    {
  eventType: 'faq_consulted',
  phone: userPhone,
  question: 'precio', // duracion, requisitos, ubicacion
  course: activeCourse,
  timestamp: new Date().toISOString()
}

  5. Derivación a Asesor

    {
  eventType: 'transferred_to_advisor',
  phone: userPhone,
  course: activeCourse,
  reason: 'manual_request', // complex_query, fallback
  timestamp: new Date().toISOString()
}

Gestión de Contactos:

// Creación/actualización automática de contactos
const contactData = {
  phone: userPhone,
  firstname: extractedName || 'Usuario WhatsApp',
  lastname: 'Bot Alpix',
  lead_source: 'WhatsApp Bot',
  last_interaction: new Date().toISOString(),
  bot_conversation_count: existingCount + 1,
  interested_courses: [courseName],
  bot_last_course_selected: courseName
};

Métricas de Rendimiento

KPIs Principales Monitoreados:

  1. Automatización Rate: % de consultas resueltas sin asesor
  2. Engagement Rate: % de usuarios que seleccionan cursos
  3. Conversion Rate: % de usuarios que consultan FAQ después de seleccionar curso
  4. Bounce Rate: % de usuarios que abandonan en el primer mensaje
  5. PDF Download Rate: % de PDFs enviados exitosamente

Logs Estructurados:

// Formato de logs para analytics
console.log(`[ANALYTICS] ${eventType} | Phone: ${phone} | Course: ${course} | Time: ${timestamp}`);

🔧 Mantenimiento

Gestión de PDFs Centralizada

Todos los enlaces de PDFs están centralizados como variables globales en server.js:

// === CONFIGURACIÓN DE PDFs (CENTRALIZADA) ===
const IRATA_NIVEL_1_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%201.pdf";
const IRATA_NIVEL_2_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%202.pdf";
const IRATA_NIVEL_3_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%203.pdf";
const BST_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20CURSO%20%20BST.pdf";
const ART_PDF_URL = "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20CURSO%20ART.pdf";

Actualización de Contenidos

Para actualizar un PDF:

  1. Subir nuevo PDF a Google Cloud Storage
  2. Actualizar la URL correspondiente en las variables globales
  3. Redesplegar el servicio

Para modificar respuestas FAQ:

  1. Localizar la función correspondiente en server.js
  2. Editar el contenido del mensaje
  3. Verificar que el contexto se mantenga correctamente
  4. Redesplegar

Para agregar nuevos cursos:

  1. Crear nueva variable global para el PDF
  2. Agregar intención en Dialogflow
  3. Implementar lógica en processMessage() y processFulfillmentRequest()
  4. Actualizar menús y FAQ correspondientes

Monitoring y Logs

Verificación de Health Check:

# Verificar estado del servicio
curl https://dialogflow-integrations-twilio-1045549844007.us-central1.run.app/health

# Verificar logs en tiempo real
gcloud run services logs tail dialogflow-twilio --follow

Logs Importantes a Monitorear:

  • [TWILIO_WEBHOOK] - Mensajes entrantes de Twilio
  • [DIALOGFLOW_REQUEST] - Requests a Dialogflow
  • [HUBSPOT_EVENT] - Eventos enviados a HubSpot
  • [PDF_SENT] - PDFs enviados exitosamente
  • [ERROR] - Errores críticos del sistema

Backup y Recovery

Backup de Configuraciones:

# Backup de variables de entorno
cp twilio/.env twilio/.env.backup.$(date +%Y%m%d)

# Backup de credenciales de Dialogflow
cp twilio/dialogflow-key.json twilio/dialogflow-key.backup.json

Recovery Procedure:

  1. Verificar estado del Cloud Run service
  2. Revisar logs para identificar el problema
  3. Rollback a versión anterior si es necesario: 
    gcloud run services update dialogflow-twilio --image=[PREVIOUS_IMAGE]

🚨 Solución de Problemas

Problemas Comunes y Soluciones

1. Bot no responde a mensajes de WhatsApp

Síntomas:

  • Mensajes de WhatsApp no generan respuesta
  • No aparecen logs de webhook en Cloud Run

Diagnóstico:

# Verificar configuración de webhook en Twilio
curl -X GET "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/IncomingPhoneNumbers.json" \
  -u $TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN

Solución:

  1. Verificar que la URL del webhook esté configurada correctamente en Twilio
  2. Verificar que el servicio Cloud Run esté activo
  3. Revisar logs del servicio

2. Dialogflow no reconoce intenciones

Síntomas:

  • Bot responde con fallback genérico
  • Logs muestran intent "Default Fallback Intent"

Diagnóstico:

# Verificar logs de Dialogflow
gcloud run services logs tail dialogflow-twilio | grep DIALOGFLOW

Solución:

  1. Verificar que las credenciales de Dialogflow sean válidas
  2. Entrenar el agente con más ejemplos de entrenamiento
  3. Revisar que el proyecto ID coincida

3. PDFs no se envían correctamente

Síntomas:

  • Error al enviar documentos por WhatsApp
  • Logs muestran errores de media/documentos

Diagnóstico:

# Verificar acceso a Google Cloud Storage
curl -I "https://storage.googleapis.com/alpix_docs_course/PROPUESTA%20IRATA%20NIVEL%201.pdf"

Solución:

  1. Verificar que las URLs de PDFs sean accesibles públicamente
  2. Revisar permisos de Google Cloud Storage
  3. Validar formato y tamaño de archivos PDF

4. Eventos no se registran en HubSpot

Síntomas:

  • Contactos no se crean/actualizan
  • Eventos no aparecen en timeline de HubSpot

Diagnóstico:

# Verificar API key de HubSpot
curl -X GET "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey=$HUBSPOT_API_KEY&count=1"

Solución:

  1. Verificar validez del API key de HubSpot
  2. Revisar permisos del API key (contacts, timeline events)
  3. Verificar formato de datos enviados

5. Contextos de conversación se pierden

Síntomas:

  • Bot "olvida" el curso seleccionado
  • Respuestas fuera de contexto

Diagnóstico:

  • Revisar logs de contextos de Dialogflow
  • Verificar duración de contextos configurada

Solución:

  1. Ajustar duración de contextos en Dialogflow (lifespan)
  2. Implementar almacenamiento de estado en memoria/base de datos
  3. Revisar limpieza de contextos en transiciones

Comandos de Diagnóstico Útiles

# Verificar estado del servicio
gcloud run services describe dialogflow-twilio

# Monitorear logs en tiempo real
gcloud run services logs tail dialogflow-twilio --follow

# Verificar configuración de Twilio
twilio phone-numbers:list

# Test de conectividad a Dialogflow
gcloud auth application-default print-access-token

# Verificar credenciales de HubSpot
curl -X GET "https://api.hubapi.com/contacts/v1/lists/all/contacts/all?hapikey=$HUBSPOT_API_KEY&count=1"

Escalamiento de Problemas

Nivel 1 - Desarrollador:

  • Problemas de código y lógica de negocio
  • Configuración de respuestas y flujos
  • Integración con APIs

Nivel 2 - DevOps/SysAdmin:

  • Problemas de infraestructura (Cloud Run, Twilio)
  • Configuración de networking y webhooks
  • Monitoreo y alertas

Nivel 3 - Vendor Support:

  • Problemas específicos de Twilio WhatsApp API
  • Issues complejos de Dialogflow
  • Problemas de la plataforma HubSpot

📚 Documentación Técnica

Estructura del Proyecto

dialogflow-integrations/
├── twilio/
│   ├── server.js              # Lógica principal del bot
│   ├── package.json           # Dependencias Node.js
│   ├── .env                   # Variables de entorno (no en repo)
│   ├── .env.example           # Template de variables
│   ├── dialogflow-key.json    # Credenciales GCP (no en repo)
│   └── ENV_CONFIG.md          # Documentación de configuración
├── botlib/                    # Librería común Dialogflow
│   ├── dialogflow_session_client.js
│   ├── filter_responses.js
│   ├── json_to_proto.js
│   └── proto_to_json.js
├── cloudbuild.yaml            # Configuración Cloud Build
├── Dockerfile                 # Configuración contenedor
├── README.md                  # Esta documentación
└── CENTRALIZACION-PDFS-COMPLETADO.md  # Docs de centralización PDFs

APIs y Endpoints

Endpoint Principal (/)

  • Método: POST
  • Propósito: Webhook de Twilio para mensajes de WhatsApp
  • Input: Formato webhook de Twilio
  • Output: TwiML response

Endpoint Fulfillment (/fulfillment)

  • Método: POST
  • Propósito: Webhook de Dialogflow
  • Input: Formato fulfillment request de Dialogflow
  • Output: Fulfillment response JSON

Dependencias Principales

{
  "express": "^4.18.0",           // Servidor web
  "twilio": "^3.77.0",            // API de Twilio
  "@google-cloud/dialogflow": "^5.2.0",  // Cliente Dialogflow
  "dotenv": "^16.0.1",            // Variables de entorno
  "axios": "^0.27.2"              // Cliente HTTP para HubSpot
}

Variables de Entorno Completas

# === CREDENCIALES TWILIO ===
TWILIO_ACCOUNT_SID=ACxxxxxxxxxxxxxxxxxxxxxxxxxxxx
TWILIO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# === INTEGRACIÓN HUBSPOT ===
HUBSPOT_API_KEY=pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

# === CONFIGURACIÓN DIALOGFLOW ===
GOOGLE_APPLICATION_CREDENTIALS=./dialogflow-key.json
PROJECT_ID=alpixchat

# === CONFIGURACIÓN DEL SERVIDOR ===
PORT=8080
NODE_ENV=production

# === CONFIGURACIÓN OPCIONAL ===
LOG_LEVEL=info
WEBHOOK_TIMEOUT=30000
MAX_RETRIES=3

Funciones Principales en server.js

processMessage(message, from)

  • Procesa mensajes directos de Twilio
  • Maneja lógica de estados y navegación
  • Envía respuestas directas cuando no requiere NLP

processFulfillmentRequest(req, res)

  • Maneja requests de Dialogflow
  • Procesa intenciones detectadas
  • Gestiona contextos y entidades

sendDocument(to, documentUrl, caption)

  • Envía PDFs través de Twilio
  • Maneja errores de envío de medios
  • Registra eventos en HubSpot

sendHubSpotEvent(eventType, phone, additionalData)

  • Registra eventos en timeline de HubSpot
  • Crea/actualiza contactos automáticamente
  • Maneja rate limiting y retries

generateCourseMenu(), generateFAQMenu(), etc.

  • Generan menús dinámicos de navegación
  • Mantienen consistencia en la experiencia de usuario
  • Facilitan mantenimiento de contenidos

Convenciones de Código

Logging:

console.log(`[ANALYTICS] ${eventType} | Phone: ${phone} | Course: ${course}`);
console.log(`[TWILIO_WEBHOOK] Message from ${from}: ${body}`);
console.error(`[ERROR] ${context}: ${error.message}`);

Manejo de Errores:

try {
  // Operación que puede fallar
} catch (error) {
  console.error(`[ERROR] Context: ${error.message}`);
  // Fallback graceful
  return res.status(500).json({ error: 'Internal server error' });
}

Estados de Conversación:

const STATES = {
  INICIO: 'inicio',
  IRATA_MENU: 'irata_menu',
  GWO_MENU: 'gwo_menu',
  PROMO_MENU: 'promo_menu',
  FAQ_ACTIVE: 'faq_active'
};

📝 Notas de Desarrollo Recientes

Centralización de PDFs (Completado)

  • ✅ Todas las URLs de PDFs centralizadas como variables globales
  • ✅ Eliminación de enlaces hardcodeados en todo el código
  • ✅ Documentación de cambios en CENTRALIZACION-PDFS-COMPLETADO.md

Próximas Mejoras Sugeridas

  • Implementar cache de respuestas frecuentes
  • Agregar métricas de performance avanzadas
  • Implementar A/B testing para diferentes flujos
  • Agregar soporte para múltiples idiomas
  • Implementar chatbot analytics dashboard

Documentación actualizada: Junio 2025 Versión del Bot: 2.1.0 Mantenido por: Equipo Alpix Chile DevOps

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages