Saltearse al contenido
Nappai Documentation

GmailWebhook

Este componente actúa como el “oído” de tu automatización en Nappai, permitiéndole escuchar lo que sucede en tu cuenta de Gmail. En lugar de esperar a que hagas clic en un botón, este nodo puede reaccionar automáticamente cuando llegan nuevos correos, se eliminan mensajes o cambian las etiquetas. Está diseñado para trabajar de forma transparente con el sistema de Google, transformando la información cruda de tus correos en datos listos para que tu asistente de IA (LLM) los entienda y actúe sobre ellos.

¿Cómo funciona?

Imagina que GmailWebhook es un centro de triaje que recibe avisos constantes de tu buzón de correo. Su trabajo es identificar de qué se trata cada aviso y preparar la información de manera ordenada.

  1. Escucha de Eventos: El componente se configura para estar atento a cambios específicos en Gmail, como la llegada de un correo nuevo o la eliminación de uno.
  2. Procesamiento: Cuando llega un aviso, el componente lee la información básica (el “payload”) que envía Google. Esto incluye detalles como quién envió el correo, el asunto y la fecha.
  3. Traducción de Datos: El componente transforma esa información técnica en un formato claro y estructurado. Por ejemplo, si llega un correo nuevo, extraerá el remitente, el asunto y el cuerpo del mensaje para convertirlo en un texto fácil de leer para tu IA.
  4. Entrega: Finalmente, entrega esta información procesada a la siguiente etapa de tu flujo de trabajo, ya sea para analizarla con un modelo de lenguaje, guardarla en una base de datos o responder automáticamente.

Conexión y Credenciales

Para que este componente pueda leer tu correo electrónico, necesitas autorizarlo primero. Esto se hace mediante una credencial segura que conecta Nappai con tu cuenta de Google.

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

  1. Dirígete a la sección de Credenciales en tu panel de Nappai.
  2. Crea una nueva credencial del tipo Google Gmail. Para ello, necesitarás acceder a la Google Cloud Console para obtener las claves de API de tu proyecto.
  3. Una vez tengas tus claves (Client Id y Client Secret), guárdalas en la sección de credenciales de Nappai.
  4. En tu flujo de trabajo, selecciona la credencial que acabas de crear en el campo de entrada Credential de este nodo.

Entradas

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

  • Events: Permite seleccionar qué tipo de cambios en tu buzón quieres monitorear. Si no seleccionas nada, el sistema asumirá que solo te interesan los mensajes nuevos.

    • Message Added: Se activa cuando llega un correo nuevo (recibido o importado).
    • Message Deleted: Se activa solo cuando un correo se elimina permanentemente (desde la Papelera).
    • Label Added: Se activa cuando se aplica una etiqueta (ej. mover a Papelera, marcar como importante).
    • Label Removed: Se activa cuando se quita una etiqueta (ej. archivar, desmarcar como importante).
    • Visible en: N/A

  • Label Filters: Especifica qué etiquetas de Gmail deseas vigilar. Por defecto, solo monitorea el buzón de entrada (INBOX).

    • Visible en: N/A

Salidas

Este componente produce datos estructurados listos para ser consumidos por el resto de tu flujo de automatización. La salida principal se llama Data.

  • Data: Contiene la información procesada del evento de Gmail.
    • Si fue un correo nuevo, incluirá el asunto, el remitente, los destinatarios y el cuerpo del mensaje.
    • Si fue un borrado o cambio de etiqueta, incluirá el ID del mensaje afectado.
    • Este formato es ideal para conectarlo con nodos de IA (LLMs) para análisis, búsqueda o redacción de respuestas.

Ejemplo de Respuesta JSON

Cuando el componente detecta un evento nuevo, produce una estructura de datos similar a la siguiente. Puedes usar los campos dentro de data (como subject o from) para conectar con otros nodos. json { “text”: “[messageAdded] Re: Project Update from alice@example.com”, “data”: { “id”: “18c27db1e57e3a9”, “threadId”: “18c27db1e57e3a9”, “labelIds”: [ “SENT” ], “snippet”: “Hi, Here is the update you requested.”, “historyId”: “123456789”, “payload”: { “partId”: "", “mimeType”: “text/plain”, “filename”: "", “headers”: [ { “name”: “From”, “value”: “Alice Smith alice@example.com” }, { “name”: “Subject”, “value”: “Re: Project Update” }, { “name”: “Date”, “value”: “Mon, 23 Oct 2023 09:00:00 -0700” } ], “body”: { “size”: 20, “data”: “Hi, \n\nHere is the update you requested.\n\nBest,\nAlice” } } } }

Conectividad

Este componente se conecta principalmente hacia adelante en el flujo de trabajo (hacia la derecha en el diagrama), entregando la información procesada a otros nodos. Lógicamente, suele conectarse a:

  1. Nodos de IA (LLMs): Para analizar el contenido del correo electrónico, resumirlo o extraer información clave.
  2. Nodos de Herramientas de Búsqueda: Para verificar información del remitente o del tema del correo.
  3. Nodos de Respuesta de Webhook: Si necesitas confirmar a un usuario externo que se recibió el correo.

No es común que este componente se conecte desde otros nodos hacia él, ya que es un punto de inicio (entry point) basado en eventos externos.

Ejemplo de Uso

Escenario: Automatizar la respuesta a correos de clientes

  1. Coloca el componente GmailWebhook al inicio de tu flujo.
  2. Configura Events seleccionando Message Added.
  3. Conecta la salida Data a un nodo de “Llamada a LLM” (ej. ChatGPT).
  4. En el prompt del LLM, pide: “Analiza el remitente y el asunto del correo en la variable ‘from’ y ‘subject’. Si parece una queja, responde con empatía; si parece una venta, responde agradeciendo”.
  5. Conecta la salida del LLM a un componente que envíe correos (como SendEmail).

Así, cada vez que llegue un correo nuevo, el sistema lo leerá, lo analizará y responderá automáticamente.

Consejos y Mejores Prácticas

  • Filtrado Eficiente: Usa el campo Label Filters para limitar qué correos se procesan. Si tu buzón recibe mucho ruido (spam, noticias), filtra solo por etiquetas específicas como INBOX o etiquetas personalizadas de proyectos importantes para ahorrar costos de API.
  • Manejo de Errores: Ten en cuenta que si un correo es muy grande o tiene un formato extraño, el componente intentará leerlo, pero podría devolver solo el “snippet” (resumen). Asegúrate de que tu nodo siguiente pueda manejar datos incompletos.
  • Validación de Credenciales: Si el componente no reacciona, verifica primero que la credencial de Google tenga los permisos adecuados (acceso a Gmail API) y que esté activa.

Consideraciones de Seguridad

  • Acceso a Datos Sensibles: Este componente otorga a tu flujo de automatización acceso a leer el contenido de tus correos electrónicos. Asegúrate de usar credenciales con el mínimo nivel de permisos necesario (Scope de lectura) si tu flujo no necesita modificar correos.
  • Protección de Credenciales: Nunca compartas ni publiques las credenciales de Google Gmail (Client ID y Secret). Guárdalas siempre en la sección segura de credenciales de Nappai.