Saltearse al contenido
Nappai Documentation

Telegram Data Transformation

⚠️ ADVERTENCIA DE DEPRECACIÓN

Este componente está deprecado y será eliminado en una versión futura de Nappai. Por favor, migra a los componentes alternativos recomendados.

El componente Telegram Data Transformation toma los mensajes que llegan a tu bot de Telegram, los descompone y te permite aplicar transformaciones simples o preparar un paquete de datos listo para ser enviado a otro servicio o herramienta dentro de Nappai.

¿Cómo funciona?

Cuando tu bot recibe un mensaje, Telegram envía un payload (actualización) a tu webhook. Este componente recibe ese payload envuelto en un objeto LangFlow Data.
Internamente, extrae el contenido del mensaje (texto, imágenes, etc.) y, según la operación seleccionada, puede:

  1. Normalizar los datos: limpiar texto, eliminar caracteres especiales o formatear la información de forma consistente.
  2. Preparar el payload de salida: empaquetar los datos transformados en un formato que otras herramientas de Nappai puedan consumir directamente.

Si habilitas el Modo de Mapeo, puedes procesar varios registros a la vez y decidir cómo se proveen los valores de cada campo (fijo, mapeado o mediante código JavaScript).

Para usar el componente, primero debes:

  1. Configurar la credencial Telegram bot API en la sección de credenciales de Nappai (BotFather → token del bot).
  2. Seleccionar esa credencial en el campo Credential del componente.

Operaciones

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

  • Normalize Data: Limpia y estandariza el contenido del mensaje para que sea más fácil de procesar en pasos posteriores.
  • Prepare Output Payload: Empaqueta los datos transformados en un formato listo para ser enviado a otro componente o herramienta.

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:

  • Raw Update: Update payload captured via webhook or integration, wrapped in a LangFlow Data object.
    • Visible en: Normalize Data, Prepare Output Payload
  • Operation: Apply a single transformation to the extracted data.
    • Visible en: Normalize Data, Prepare Output Payload
  • Mapping Mode: Enable mapping mode to process multiple data records in batch
    • Visible en: Normalize Data, Prepare Output Payload
  • Tool Name: The name of the tool that will be used when this component is connected as a tool. This name will be displayed to the agent when it selects tools to use.
    • Visible en: Normalize Data, Prepare Output Payload
  • Tool Description: A detailed description of what this tool does. This description will help the agent understand when and how to use this tool effectively.
    • Visible en: Normalize Data, Prepare Output Payload
  • Tools arguments metadata: Defines the arguments metadata for the tools.
    • Visible en: Normalize Data, Prepare Output Payload

Nota: Este componente requiere una credencial de tipo Telegram bot API. Configúrala primero en la sección de credenciales de Nappai y luego selecciónala en el campo Credential del componente.

Salidas

  • Transformed Data: Tipo de datos Data (método: apply_transformations). Contiene el contenido del mensaje después de la transformación seleccionada.
  • Tool: Tipo de datos Tool (método: to_toolkit). Permite que el resultado sea usado como una herramienta por un agente dentro de Nappai.

Ejemplo de Uso

  1. Normalize Data

    • Configura el componente con la operación Normalize Data.
    • Conecta la entrada Raw Update con el webhook de Telegram.
    • El componente devolverá Transformed Data con el texto limpio y listo para usar en un flujo de análisis de sentimiento.

  2. Prepare Output Payload

    • Selecciona la operación Prepare Output Payload.
    • Define el Tool Name y Tool Description para que un agente pueda invocarlo.
    • El componente producirá un objeto Tool que puede ser enviado a un chatbot o a un servicio externo.

Componentes Relacionados

  • TelegramBaseDataTransformation – Base que maneja la lógica común de transformación de datos de Telegram.
  • Telegram Bot API – Credencial necesaria para autenticar el bot y recibir actualizaciones.

Consejos y Mejores Prácticas

  • Mantén el token seguro: Nunca lo expongas en el código ni lo compartas públicamente.
  • Usa el Modo de Mapeo cuando necesites procesar lotes de mensajes; evita procesar cada mensaje individualmente si el volumen es alto.
  • Prueba la operación “Normalize Data” con mensajes de prueba antes de pasar a producción para asegurarte de que la limpieza se ajusta a tus necesidades.

Consideraciones de Seguridad

  • El token del bot debe guardarse como credencial en Nappai; no lo incluyas en los flujos de datos.
  • Asegúrate de que el webhook de Telegram esté protegido con HTTPS para evitar interceptaciones.
  • Revisa los permisos del bot en BotFather para limitar el acceso solo a los comandos y datos que realmente necesites.