WhatsApp Business Webhook

El componente WhatsApp Business Webhook es el punto de conexión principal para recibir mensajes de WhatsApp en tu sistema de automatización Nappai. Su función principal es actuar como un “escucha” permanente: se queda atento a cualquier mensaje, imagen o archivo que los usuarios envíen a tu número de WhatsApp Business y los transforma en datos listos para ser procesados por el resto de tu flujo de trabajo.

Es ideal para crear chatbots, automatizar respuestas a clientes o guardar registros de conversaciones directamente en tus bases de datos o aplicaciones de gestión.

¿Cómo funciona?

Este componente no requiere que pulses un botón de “ejecutar” para empezar a trabajar. Al activarlo en tu grafo de flujo, inicia un servidor en segundo plano que permanece en estado de espera.

Escucha Activa: Cuando envías un mensaje a la cuenta de WhatsApp configurada, el servicio de Meta (Facebook) envía una notificación inmediata a tu sistema a través de una conexión segura (HTTP).
Verificación: El componente valida automáticamente que la solicitud sea legítima y segura, asegurando que solo acepte mensajes reales y autorizados.
Clasificación Inteligente:
- Si recibes un mensaje de texto, el sistema lo extrae y lo prepara para que otras herramientas (como un Asistente de IA) puedan leerlo y responderlo.
- Si recibes un archivo multimedia (como una foto o un PDF), el componente identifica el tipo de archivo y extrae la información necesaria para que pueda ser descargado o analizado.
Entrega de Datos: Finalmente, los datos procesados se “empacan” en dos salidas claras para que puedas conectar el flujo hacia donde necesites.

Conexión y Credenciales

Para que este componente pueda hablar con WhatsApp, es fundamental que primero configures la seguridad en Nappai.

Este componente requiere configurar previamente una credencial en el panel de Nappai para poder interactuar con el servicio de WhatsApp Business:

Dirígete a la sección de Credenciales en tu panel de Nappai.
Crea una nueva credencial del tipo WhatsApp Business. Para obtener los datos necesarios (API Key, Number Identifier y Verification Token), sigue la guía oficial de Meta proporcionada en la documentación de la credencial.
En tu flujo de trabajo, selecciona la credencial que acabas de crear en el campo Credential de este nodo.

Entradas

A continuación, se detallan los campos disponibles para configurar el comportamiento de este nodo. Ten en cuenta que las credenciales (API Key, Tokens, etc.) se gestionan mediante la selección de la credencial previa y no requieren ser ingresadas manualmente en estos campos.

App ID: Identificador único de tu aplicación en el ecosistema de Facebook/WhatsApp Business. Es necesario para identificar quién envía la solicitud.
App Secret: Clave secreta que, junto con el App ID, autentica la seguridad de la conexión.
Verify Token: Un código secreto que utiliza WhatsApp para verificar que eres el dueño del webhook y que los datos no han sido alterados.
Phone Number ID: El identificador numérico de tu número de WhatsApp Business. Es necesario para saber a qué número específico llegarán los mensajes.
Access Token: La llave de acceso con permisos específicos para leer los mensajes entrantes en nombre de tu negocio.
Verbose: Opción que permite activar registros de actividad detallados. Útil si estás depurando y quieres ver paso a paso qué está sucediendo en el sistema.

Salidas

El componente entrega los datos procesados a través de dos canales principales. Dependiendo del tipo de mensaje recibido, el sistema enviará los datos por una u otra salida para que puedas conectarlos a nodos posteriores (como un Asistente de IA o una Base de Datos).

Message: Esta salida se activa cuando el usuario envía un mensaje de texto o una interacción simple. Proporciona el contenido del mensaje en formato de texto plano, listo para ser leído por un modelo de lenguaje (LLM) o procesado por reglas lógicas.
Media: Esta salida se activa cuando el usuario envía un archivo (imagen, video, documento o audio). Proporciona los metadatos del archivo, como su URL, tipo de archivo o nombre, permitiendo que otros nodos descarguen y analicen el contenido adjunto.

Ejemplo de Respuesta JSON

A continuación, se muestra un ejemplo simplificado de cómo el componente organiza los datos de entrada para que puedas mapearlos en los nodos siguientes.

Ejemplo para Mensaje de Texto: json { “message”: { “text”: “Hola, necesito ayuda con mi pedido #1234”, “sender”: “Cliente”, “timestamp”: “2023-10-27T10:00:00Z” } }

Ejemplo para Archivo Multimedia: json { “media”: { “file_url”: “https://example.com/imagen_firma.jpg”, “mime_type”: “image/jpeg”, “file_name”: “factura_client_01.jpg”, “size”: 10240 } }

Conectividad

Este componente es el “inicio” del flujo para cualquier interacción entrante. Lógicamente, se conecta a nodos que puedan “leer” o “actuar” sobre esa información:

Lingua AI / Chat Models: Es muy común conectar la salida Message a un asistente de IA para que lea el mensaje del cliente y genere una respuesta automática.
Database / CRM Nodes: Puedes conectar la salida Message o Media a nodos de almacenamiento para guardar un historial de conversaciones o archivos adjuntos en tu sistema de gestión.
Logic/Condition Nodes: Si deseas responder de forma diferente según el tipo de mensaje, puedes conectar la salida a un nodo de lógica para decidir el siguiente paso.

Ejemplo de Uso

Escenario: Bot de Atención al Cliente

Coloca el nodo WhatsApp Business Webhook al inicio de tu flujo.
Conecta su salida Message a un nodo de LLM (como ChatGPT o un modelo local) con la instrucción: “Responde de manera amable a la queja del cliente”.
Conecta la salida del LLM a un nodo de WhatsApp Business Message Sender para responder automáticamente al cliente en WhatsApp.
Al enviar un texto desde tu WhatsApp al número configurado, el webhook recibirá el mensaje, el LLM generará la respuesta y el sistema te la enviará de vuelta automáticamente.

Consejos y Mejores Prácticas

Seguridad de Tokens: Nunca compartas tu Access Token o App Secret públicamente. Guárdalos siempre en la sección de Credenciales de Nappai para mantenerlos seguros.
Manejo de Errores: Si tu número de WhatsApp tiene restricciones de verificación, asegúrate de que el Phone Number ID sea correcto; de lo contrario, los webhooks podrían ser rechazados por Meta.
Uso de Verbose: Utiliza la opción “Verbose” solo cuando estés configurando o corrigiendo errores. En producción, es mejor mantenerla desactivada para mantener el sistema ligero y rápido.
Gestión de Medios: Si tu flujo va a procesar muchas imágenes o documentos grandes, asegúrate de que el nodo siguiente esté preparado para manejar archivos binarios y no solo texto.

Consideraciones de Seguridad

Autenticación Obligatoria: Este componente está diseñado para verificar la procedencia de los mensajes. Asegúrate de que el Verify Token coincida exactamente con el que configuraste en la consola de desarrolladores de Facebook.
Datos Sensibles: Los mensajes recibidos pueden contener información personal de tus clientes. Asegúrate de cumplir con las normativas de privacidad de datos (como GDPR o leyes locales) al almacenar o procesar estos datos en Nappai.
Acceso Restringido: El Access Token debe tener únicamente los permisos necesarios (lectura de mensajes). No otorgues permisos de escritura a menos que sea estrictamente necesario para tu flujo de trabajo.