Telegram Message

Telegram Message es un componente de Nappai que te permite interactuar con la API de Telegram Bot. Con él puedes enviar textos, fotos, audios, videos, documentos, contactos, encuestas y también eliminar, fijar o desfijar mensajes. Además, puedes usarlo como una herramienta (tool) dentro de los agentes de IA de Nappai.

¿Cómo funciona?

Cuando activas el componente, Nappai envía una solicitud HTTP a la API de Telegram Bot (https://api.telegram.org). El bot debe estar previamente creado y registrado con BotFather, y su token se guarda en una credencial de tipo Telegram bot API. El componente toma los valores que configures (texto, archivos, ID de chat, etc.) y los envía al endpoint correspondiente según la operación seleccionada. La respuesta de Telegram se devuelve como un objeto JSON que se muestra en la salida Telegram Response.

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 Text: Envía un mensaje de texto a un chat.
Send Photo: Envía una foto.
Send Audio: Envía un archivo de audio.
Send Animation: Envía una animación (GIF).
Send Video: Envía un video.
Send Document: Envía un documento.
Send Contact: Envía la información de contacto de una persona.
Delete Message: Elimina un mensaje existente.
Pin Message: Fija un mensaje en el chat.
Unpin Message: Desfija un mensaje fijado.
Send Poll: Envía una encuesta con opciones de respuesta.

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

Mode: Elige entre un modo simple (usa el chat ID del webhook) o un modo avanzado donde puedes especificar manualmente el chat ID y otros parámetros.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Chat ID: Número único del chat de Telegram donde se enviará el mensaje.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Message ID: Número del mensaje al que quieres responder o con el que quieres interactuar (editar, fijar, eliminar).
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Send Poll, Delete Message, Pin Message, Unpin Message
Message to modify: Identificador del mensaje que deseas editar. Se usa en la operación Send Text cuando se quiere modificar un mensaje existente.
- Visible en: Send Text
Text: Contenido del mensaje que quieres enviar. Puedes incluir emojis y formato básico (negrita, cursiva).
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document
Attachment: Archivo multimedia a adjuntar (foto, video, audio, documento, etc.).
- Visible en: Send Photo, Send Audio, Send Animation, Send Video, Send Document
Phone Number: Número de teléfono que quieres compartir como contacto. Debe estar en formato internacional (+1234567890).
- Visible en: Send Contact
First Name: Primer nombre de la persona cuyo contacto quieres compartir. Obligatorio para enviar contacto.
- Visible en: Send Contact
Last Name: Apellido de la persona cuyo contacto quieres compartir. Opcional.
- Visible en: Send Contact
VCard: Información adicional de contacto en formato vCard. Opcional.
- Visible en: Send Contact
Question: Texto de la pregunta de la encuesta. Debe ser claro y conciso.
- Visible en: Send Poll
Options: Lista de opciones para la encuesta (mínimo 2). Cada una debe ser una posible respuesta.
- Visible en: Send Poll
Is Anonymus: Determina si la encuesta ocultará la identidad de los votantes.
- Visible en: Send Poll
Multiple Answers: Permite que los usuarios seleccionen varias opciones en la encuesta.
- Visible en: Send Poll
Mapping Mode: Interruptor que activa el modo de mapeo. Cuando está activado, se habilita la entrada Mapping Data.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Session ID: Identificador único de la conversación. Ayuda a mantener el contexto y organizar los mensajes por sesión.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Action: Selecciona la acción que quieres realizar en Telegram. Cada opción requiere campos específicos.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Tool Name: Nombre de la herramienta que se mostrará al agente cuando el componente se use como tool.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Tool Description: Descripción detallada de lo que hace esta herramienta. Ayuda al agente a decidir cuándo usarla.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Tools arguments metadata: Metadatos de los argumentos que la herramienta acepta.
- Visible en: Send Text, Send Photo, Send Audio, Send Animation, Send Video, Send Document, Send Contact, Delete Message, Pin Message, Unpin Message, Send Poll
Credential: Selecciona la credencial de tipo Telegram bot API previamente configurada en Nappai.
Para usar el componente, primero debes crear la credencial en la sección de credenciales de Nappai y luego seleccionarla aquí.

Salidas

Telegram Response: Respuesta JSON devuelta por la API de Telegram. Puedes usarla para verificar el éxito de la operación o extraer información adicional (por ejemplo, el ID del mensaje enviado).
Tool: Objeto que permite que el componente actúe como una herramienta (tool) dentro de los agentes de IA de Nappai.

Ejemplo de Uso

Enviar un mensaje de texto

Arrastra el componente Telegram Message al flujo.
Selecciona la operación Send Text.
En Mode, elige Advanced y escribe el Chat ID del grupo o usuario.
En Text, escribe el mensaje que quieres enviar.
En Credential, selecciona la credencial de Telegram bot API que creaste.
Ejecuta el flujo. La salida Telegram Response mostrará el ID del mensaje enviado.

Enviar una foto

Arrastra el componente Telegram Message al flujo.
Selecciona la operación Send Photo.
En Mode, elige Advanced y escribe el Chat ID.
En Attachment, sube la foto que quieres enviar.
En Text, opcionalmente escribe un pie de foto.
En Credential, selecciona la credencial de Telegram bot API.
Ejecuta el flujo. La salida Telegram Response confirmará que la foto se envió correctamente.

Componentes Relacionados

Telegram Bot API Credential – Configura el token de tu bot.
Telegram Webhook – Recibe mensajes entrantes de Telegram y los pasa a Nappai.

Consejos y Mejores Prácticas

Usa el modo avanzado cuando necesites enviar mensajes a chats que no provienen del webhook.
Activa Mapping Mode si quieres procesar varios registros a la vez (por ejemplo, enviar un mensaje a cada usuario de una lista).
Incluye un identificador de sesión (Session ID) para mantener el contexto cuando trabajes con agentes de IA.
Valida los archivos antes de enviarlos: Telegram tiene límites de tamaño (por ejemplo, 50 MB para fotos).
Para encuestas, asegúrate de que la lista de opciones tenga al menos 2 elementos y no más de 10 (límite de Telegram).

Consideraciones de Seguridad

Protege tu token: La credencial de Telegram bot API debe guardarse como secreto y no compartirse públicamente.
Limita los permisos del bot: Configura en BotFather solo los permisos que realmente necesites (por ejemplo, enviar mensajes, leer mensajes, etc.).
Revisa los logs: La salida Telegram Response puede contener información sensible; evita exponerla en interfaces públicas.
Manejo de errores: Si la API devuelve un error, verifica el código de estado y el mensaje para identificar problemas como “chat not found” o “file too large”.