Bot de WhatsApp de Ayuda Sismo — Venezuela 2026

Un chatbot de WhatsApp ligero, seguro y optimizado para producción, diseñado para coordinar la asistencia humanitaria y la localización de personas tras el terremoto de Venezuela de 2026.

El bot consume directamente las APIs públicas de Localizados Venezuela, SOS Venezuela y AcopioVE en tiempo real, ofreciendo información consolidada de forma instantánea sin requerir bases de datos locales ni almacenamiento de estado sensible en el chat.

Características Clave

• Búsqueda Dual y Fusión Inteligente (Smart Fusion):

  • Al buscar una persona por nombre o cédula, el bot consulta de forma paralela (mediante Promise.allSettled tolerante a fallos) la API oficial de Localizados Venezuela y la API comunitaria de SOS Venezuela.
  • Algoritmo de De-duplicación: Unifica las respuestas duplicadas utilizando coincidencia exacta sobre el nombre normalizado (removiendo mayúsculas, acentos y espacios innecesarios).
  • Priorización de Estatus: Otorga prioridad absoluta al estado de Localizado (Confirmado) si una persona figura en un centro médico o albergue oficial, enriqueciendo la ficha con reportes comunitarios de búsqueda previa de la red SOS, observaciones clínicas y enlaces de consulta de ambas plataformas.

• Integración de APIs en Tiempo Real:

  • Localizados Venezuela: Consulta de personas localizadas en centros de salud y refugios autorizados.
  • SOS Venezuela: Registro comunitario de personas desaparecidas o reportadas a salvo por familiares.
  • AcopioVE (Refugios y Centros de Donación): Ubica albergues activos y puntos de donación por ciudad, mostrando dirección, estado de ocupación (abierto/lleno) y necesidades inmediatas.
  • ResponseGrid (Necesidades de Ayuda): Consulta en tiempo real las solicitudes activas de insumos, recursos y voluntariado validadas por coordinadores de emergencia.
  • Directorio de Emergencias: Acceso directo al listado oficial de números de primera respuesta del país.

• Búsqueda Inteligente y Sin Falsos Positivos:

  • Por Cédula de Identidad: Sanitiza la entrada y realiza búsquedas de dígitos exactos sobre la API.
  • Por Nombre (Filtrado Estricto de Telegram): Solicita un lote amplio de registros y los filtra localmente en memoria. Exige la coincidencia de todas las palabras clave ingresadas (insensible a acentos/mayúsculas), eliminando coincidencias parciales molestas (por ejemplo, buscar "Carlos Perez" no retornará otros "Carlos" que no sean "Perez").
  • Sanitización de Comandos: Ignora preposiciones gramaticales al inicio de los comandos (refugio en Caracas o acopio de Valencia buscan directamente por la ciudad "Caracas" o "Valencia").

• Caché en Memoria Local:

  • Implementa un sistema interno de caché por TTL (Map nativo de alto rendimiento) para almacenar temporalmente los resultados de las APIs externas:
    • Directorio de Emergencias: 5 minutos.
    • Búsquedas de Refugios: 2 minutos.
    • Centros de Acopio: 2 minutos.
    • Necesidades de Ayuda (ResponseGrid): 2 minutos.
    • Búsquedas de Personas (Búsqueda Dual): 1 minuto.
  • Esto acelera los tiempos de respuesta del bot y mitiga completamente el riesgo de bloqueos por Rate Limiting (120 req/min de la API externa) al reutilizar datos de consultas frecuentes de diferentes usuarios.

• Aprovisionamiento Idempotente y Seguro:

  • Al iniciar, comprueba si la sesión del bot ya está configurada en la API de FZap.
  • Realiza un GET /webhook para verificar si la dirección de callback ya existe antes de registrarla, evitando la duplicación de webhooks que causa respuestas duplicadas o triplicadas en los chats.

• Seguridad contra Condiciones de Carrera:

  • Procesa los mensajes entrantes de cada chat secuencialmente mediante una cola de tareas asíncronas (taskQueue) por JID (ID de usuario de WhatsApp), evitando colisiones cuando un usuario envía ráfagas rápidas de mensajes.

• Imagen Docker Altamente Optimizada:

  • Dockerfile basado en imágenes ligeras Alpine.
  • Eliminadas dependencias de compiladores C++ nativos (make, g++, python3) tras remover librerías pesadas como SQLite local.
  • El contenedor corre bajo un usuario sin privilegios (fzap) para garantizar la seguridad del servidor host.

Configuración de Variables de Entorno

Crea un archivo .env en la raíz del proyecto (toma como base .env.example). A continuación se detallan los parámetros necesarios:

Instalación y Despliegue

Paso 1: Configurar el Entorno

1. Copia la plantilla de variables:

   cp .env.example .env
   

2. Completa los valores en el archivo .env de acuerdo a tu servidor.

Paso 2: Compilar e Iniciar los Contenedores

Inicia el entorno usando Docker Compose:

docker compose -f docker-compose-prod.yml up -d --build

[!IMPORTANT] Si estás redesplegando cambios de código del bot en un servidor que ya tiene la sesión de WhatsApp vinculada en el contenedor fzap_api, no apagues ni reinicies el cluster completo. Recompila únicamente el contenedor del bot para preservar la conexión de WhatsApp activa:

docker compose -f docker-compose-prod.yml up -d --build whatsapp_bot_sismo

Paso 3: Emparejar WhatsApp

1. Accede a tu panel de FZap Manager (http://TU_IP:8081).
2. Selecciona la instancia del bot (FZAP_INSTANCE).
3. Escanea el código QR de emparejamiento desde la aplicación móvil de WhatsApp (Dispositivos vinculados -> Vincular un dispositivo).

Comandos del Bot (Uso en WhatsApp)

El bot procesa dinámicamente los siguientes mensajes enviados por los usuarios:

• Menú de Bienvenida y Ayuda: Al enviar hola, ayuda, help, /ayuda, /help o #, se muestra el instructivo del bot.
• Búsqueda de Personas: Envía el nombre completo de la persona o su Cédula de Identidad (mínimo 4 números) para buscar registros confirmados en hospitales y refugios de forma unificada en ambas redes de búsqueda (Localizados VE + SOS Venezuela).
• Búsqueda de Refugios: Envía la palabra refugio sola para ver todos los albergues, o incluye la ciudad (ej: refugio en Caracas o refugio La Guaira) para ver los específicos de una localidad.
• Centros de Donación/Acopio: Envía la palabra acopio o donar seguida de la ciudad (ej: acopio en Valencia) para ubicar centros de recolección de víveres.
• Números de Emergencia: Envía la palabra emergencia o telefono para obtener el directorio telefónico de ayuda.