Twilio WhatsApp

Twilio WhatsApp es un componente de Nappai que permite enviar y gestionar mensajes de WhatsApp a través de la API de Twilio. Con él puedes enviar mensajes de texto, multimedia y también consultar, listar o eliminar mensajes previamente enviados.

¿Cómo funciona?

El componente se conecta a la API de Twilio usando una credencial de tipo Twilio WhatsApp Integration. Cuando seleccionas una operación, el componente construye la solicitud HTTP correspondiente y la envía a Twilio. Los resultados (por ejemplo, el SID del mensaje enviado o la lista de mensajes) se devuelven como datos que pueden ser usados por otros componentes del flujo.

Operaciones

Este componente ofrece varias operaciones que puedes seleccionar según lo que necesites hacer. Solo puedes usar una operación a la vez:

Send Message: Envía un nuevo mensaje de WhatsApp con texto y/o media.
Fetch Message: Obtiene los detalles de un mensaje existente usando su SID.
List Messages: Recupera una lista de mensajes enviados o recibidos, con filtros opcionales.
Delete Message: Elimina un mensaje existente usando su SID.

Para usar el componente, primero selecciona la operación que necesitas en el campo “Operation” (Operación).

Entradas

Modo de Mapeo (Mapping Mode)

Este componente cuenta con un modo especial llamado “Mapping Mode” (Modo de Mapeo). Cuando activas este modo mediante el interruptor, se habilita una entrada adicional llamada “Mapping Data” y cada campo de entrada te ofrece tres formas diferentes de proporcionar datos:

Fixed (Fijo): Escribes el valor directamente en el campo.
Mapped (Mapeado): Conectas la salida de otro componente para usar su resultado como valor.
Javascript: Escribes código Javascript para calcular el valor dinámicamente.

Esta flexibilidad te permite crear flujos de trabajo más dinámicos y conectados.

Campos de Entrada

Los siguientes campos están disponibles para configurar este componente. Cada campo puede estar visible en diferentes operaciones:

Operation: Elige qué quieres hacer: enviar un nuevo mensaje, obtener uno existente o listar mensajes.
- Visible en: Send Message, Fetch Message, List Messages, Delete Message
Message: Contenido de texto del mensaje.
- Visible en: Send Message
Filter: From (optional): Filtra la lista de mensajes por remitente exacto (ej. whatsapp:+14155238886).
- Visible en: List Messages
Filter: To (optional): Filtra la lista de mensajes por destinatario exacto (ej. whatsapp:+521XXXXXXXXXX).
- Visible en: List Messages
Mapping Mode: Habilita el modo de mapeo para procesar múltiples registros en lote.
- Visible en: Send Message, Fetch Message, List Messages, Delete Message
Message SID: El SID único de un mensaje para obtenerlo.
- Visible en: Fetch Message
Message SID to Delete: SID del mensaje que quieres eliminar.
- Visible en: Delete Message
Only inbound?: Si se activa, List Messages devolverá solo mensajes recibidos.
- Visible en: List Messages
Page Size: Número de mensajes a listar (1–1000). El valor por defecto es 50.
- Visible en: List Messages
Silent Errors: Si se activa, los errores se registran pero no lanzan excepciones.
- Visible en: Send Message
Type Operation: Tipo de operación: enviar un nuevo mensaje.
- Visible en: Send Message
Media URL: URL pública del archivo multimedia a enviar (imagen, audio, video, etc.). Opcional.
- Visible en: Send Message
Tool Name: Nombre del tool que se mostrará al agente cuando el componente se conecte como herramienta.
- Visible en: Send Message, Fetch Message, List Messages, Delete Message
Tool Description: Descripción detallada de lo que hace esta herramienta.
- Visible en: Send Message, Fetch Message, List Messages, Delete Message
Tools arguments metadata: Define los metadatos de los argumentos para las herramientas.
- Visible en: Send Message, Fetch Message, List Messages, Delete Message

Nota: La credencial de Twilio se selecciona en el campo “Credential” del componente. No aparece en la lista de entradas porque ya está preconfigurada en la sección de credenciales de Nappai.

Salidas

Data: Resultado de la operación (por ejemplo, el SID del mensaje enviado o la lista de mensajes).
Tool: Información que permite que el componente actúe como una herramienta para agentes de IA.

Ejemplo de Uso

Enviar un mensaje

Selecciona la operación Send Message.
Ingresa el número de teléfono del destinatario en el campo Number To (no listado explícitamente, pero se asume que es parte de la configuración de Twilio).
Escribe el texto del mensaje en Message.
Si quieres enviar una imagen, coloca la URL pública en Media URL.
Activa Silent Errors si no quieres que el flujo se detenga por errores.
Ejecuta el flujo y revisa la salida Data para confirmar que el mensaje fue enviado.

Listar mensajes recibidos

Selecciona la operación List Messages.
Marca Only inbound? para filtrar solo mensajes recibidos.
Ajusta Page Size si necesitas más de 50 resultados.
Ejecuta el flujo y utiliza la salida Data para procesar la lista de mensajes.

Componentes Relacionados

TwilioWhatsAppComponent: Versión base que maneja la lógica de Twilio; Twilio WhatsApp hereda su funcionalidad.
Nappai Credential Manager: Permite crear y gestionar la credencial Twilio WhatsApp Integration.

Consejos y Mejores Prácticas

Usa Mapping Mode cuando necesites enviar mensajes a varios contactos en un solo flujo.
Mantén las URLs de media públicas y accesibles; Twilio necesita poder descargar el archivo.
Configura Silent Errors en tareas de envío masivo para evitar interrupciones.
Revisa los límites de la API de Twilio (por ejemplo, número máximo de mensajes por minuto) para evitar bloqueos.
Guarda los SIDs de los mensajes enviados si planeas consultarlos o eliminarlos más tarde.

Consideraciones de Seguridad

La credencial Twilio WhatsApp Integration contiene datos sensibles (Account SID, Auth Token, Phone Number). Asegúrate de que solo usuarios autorizados tengan acceso a la sección de credenciales.
No compartas las URLs de media que contengan información confidencial.
Si usas Silent Errors, revisa los logs periódicamente para detectar problemas que no se hayan mostrado como excepciones.