Saltar a contenido

Enviar Mensaje de Telegram

🤖 Nodo: Enviar Mensaje de Telegram

Este nodo te permite enviar mensajes de Telegram automáticamente desde tus automatizaciones. Utiliza la API de Telegram Bot para enviar mensajes, archivos multimedia y botones interactivos a usuarios o grupos de Telegram.

🔧 Configuración Inicial: Crear un Bot de Telegram

Antes de poder usar este nodo, necesitas crear un bot de Telegram y obtener tu Token de Bot. Sigue estos pasos:

Paso 1: Abrir BotFather

  1. Abre Telegram en tu teléfono móvil o computadora.
  2. Busca y abre @BotFather (el bot oficial para crear bots).
  3. Enlace directo: https://web.telegram.org/k/#@BotFather

Paso 2: Crear tu Bot

  1. Envía el comando /newbot a BotFather.
  2. BotFather te pedirá que elijas un nombre para tu bot (este es el nombre que verán los usuarios).
  3. Ejemplo: Netsocs Arrive Telegram Bot
  4. Luego BotFather te pedirá que elijas un nombre de usuario para tu bot (debe terminar en "bot").
  5. Ejemplo: netsocs_arrive_bot
  6. Una vez creado, BotFather te enviará un mensaje con tu Token de Bot.
  7. Ejemplo: 7767979311:AAHEFLKJSDFLKJSDFxxx

⚠️ Importante: Guarda este token en un lugar seguro. Cualquiera con este token puede controlar tu bot.

Paso 3: Iniciar una Conversación con tu Bot

Este paso es obligatorio si quieres enviar mensajes usando el campo username:

  1. Busca tu bot usando el nombre de usuario que creaste (ej: @netsocs_arrive_bot).
  2. Abre el chat con tu bot.
  3. Haz clic en el botón "Start" o envía el comando /start.

¿Por qué es necesario esto? Los bots de Telegram solo pueden enviar mensajes a usuarios que han iniciado una conversación con ellos primero. Esta es una medida de seguridad de Telegram.

⚙️ Configuración del Nodo

Una vez que hayas creado tu bot y obtenido el Token de Bot, puedes configurar el nodo. A continuación explicamos cada campo del formulario:

Formulario de configuración del nodo Telegram

📋 Campos de Configuración

La configuración del nodo es un objeto JSON con la siguiente estructura:

{
  "botToken": "77679793111:AAKSDJFKLSDFXXX",
  "chatId": "",
  "commands": [
    {
      "command": "option1",
      "description": "Opción 1",
      "callbackData": "option_1"
    }
  ],
  "mediaFile": "",
  "mediaURL": "",
  "text": "Detección LPR",
  "username": "Netsocs Arrive Telegram Bot",
  "waitResponse": false,
  "waitTime": 30
}

1. botToken ⚠️ (Obligatorio)

¿Qué es?
El token de autenticación de tu bot de Telegram. Es la "contraseña" que permite al sistema enviar mensajes a través de tu bot.

¿Dónde lo obtengo?
Recibes este token de BotFather cuando creas tu bot (ver sección "Configuración Inicial" arriba).

Formato:
Una cadena larga de números y letras separada por dos puntos.

Ejemplo:

"botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx"

⚠️ Seguridad: Nunca compartas tu Token de Bot con nadie. Cualquiera con este token puede controlar tu bot.

2. chatId (Opcional)

¿Qué es?
El identificador único del chat donde se enviará el mensaje. Puede ser un ID de usuario o un ID de grupo.

¿Cuándo usarlo?
Usa chatId cuando conoces el ID numérico del destinatario. Esto es útil para enviar a usuarios o grupos específicos.

Formato:
Una cadena numérica (puede ser positiva o negativa para grupos).

Ejemplo:

"chatId": "123456789"

Para grupos:

"chatId": "-987654321"

Nota: Puedes usar chatId O username, pero al menos uno es obligatorio. Si proporcionas ambos, chatId tiene prioridad.

¿Cómo obtener un chatId? - Para usuarios: Deben enviar un mensaje a tu bot, luego puedes obtener su chatId desde la API de Telegram. - Para grupos: Añade tu bot al grupo, luego usa la API de Telegram para obtener el chatId del grupo.

3. username (Opcional)

¿Qué es?
El nombre de usuario de Telegram del destinatario (sin el símbolo @).

¿Cuándo usarlo?
Usa username cuando quieras enviar un mensaje a un usuario específico por su nombre de usuario en lugar de su ID numérico.

Formato:
Cadena de texto que representa el nombre de usuario (sin @).

Ejemplo:

"username": "juan_perez"

⚠️ Requisitos Importantes:

  • El destinatario debe haber iniciado una conversación con tu bot primero (hacer clic en "Start" o enviar /start).
  • Si el usuario nunca ha interactuado con tu bot, el mensaje fallará.
  • Puedes usar chatId O username, pero al menos uno es obligatorio.

4. text ⚠️ (Obligatorio)

¿Qué es?
El mensaje de texto que se enviará al destinatario.

Formato:
Cualquier cadena de texto. Puedes incluir emojis, saltos de línea y formato de Telegram.

Ejemplo:

"text": "¡Hola! Este es un mensaje automatizado de Netsocs."

Con saltos de línea:

"text": "Detección LPR\nPlaca del vehículo: ABC123\nHora: 14:30"

Con variables (avanzado):

"text": "Alerta: {{eventType}} detectado en {{location}}"

5. commands (Opcional)

¿Qué es?
Un array de botones interactivos que aparecerán debajo de tu mensaje. Estos botones permiten a los destinatarios responder con opciones predefinidas.

Formato:
Array de objetos, donde cada objeto tiene: - command: La etiqueta del botón (lo que ve el usuario) - description: Una descripción de lo que hace el botón - callbackData: Los datos que se enviarán cuando se haga clic en el botón

Ejemplo:

"commands": [
  {
    "command": "opcion1",
    "description": "Opción 1",
    "callbackData": "option_1"
  },
  {
    "command": "opcion2",
    "description": "Opción 2",
    "callbackData": "option_2"
  }
]

Nota: Si no quieres enviar botones, puedes dejar este campo como un array vacío [] u omitirlo por completo.

6. mediaFile (Opcional)

¿Qué es?
La ruta a un archivo local en el servidor que quieres enviar como adjunto (imagen, video, documento, etc.).

Formato:
Cadena con la ruta del archivo en el servidor.

Ejemplo:

"mediaFile": "/ruta/al/archivo/local/imagen.jpg"

Nota: Este campo es para archivos almacenados en el servidor de Netsocs. Si quieres enviar un archivo desde una URL, usa mediaURL en su lugar.

7. mediaURL (Opcional)

¿Qué es?
Una URL pública a una imagen, video o documento que quieres enviar como adjunto.

Formato:
URL completa (debe ser públicamente accesible en internet).

Ejemplo:

"mediaURL": "https://ejemplo.com/foto.jpg"

Nota: La URL debe ser públicamente accesible. URLs privadas o archivos detrás de autenticación no funcionarán.

8. waitResponse (Opcional)

¿Qué es?
Un indicador booleano que determina si la automatización debe esperar una respuesta del destinatario.

Formato:
true o false

¿Cuándo usarlo? - Establece en true si quieres que la automatización espere a que el usuario haga clic en un botón (de commands) antes de continuar. - Establece en false (predeterminado) si solo quieres enviar el mensaje y continuar inmediatamente.

Ejemplo:

"waitResponse": true

Nota: Si se establece en true, también debes definir commands (botones) y establecer un waitTime apropiado.

9. waitTime (Opcional)

¿Qué es?
El tiempo máximo (en segundos) que la automatización esperará una respuesta del destinatario.

Formato:
Número (entero)

¿Cuándo usarlo?
Este campo solo importa si waitResponse está establecido en true. Define cuánto tiempo esperará el sistema antes de tiempo de espera agotado.

Ejemplo:

"waitTime": 30

Esto significa que el sistema esperará hasta 30 segundos para que el usuario responda.

Predeterminado: Si no se especifica, el predeterminado es típicamente 30 segundos.

✅ Resumen de Campos Obligatorios

Los campos marcados con ⚠️ son obligatorios y deben completarse para que el nodo funcione:

  • ✅ botToken - Tu token de bot de Telegram (de BotFather)
  • ✅ text - El texto del mensaje a enviar
  • ✅ chatId O username - Al menos un identificador de destinatario (chatId o username)
  • ⭕ commands - Botones interactivos (opcional)
  • ⭕ mediaFile - Adjunto de archivo local (opcional)
  • ⭕ mediaURL - Adjunto de archivo desde URL (opcional)
  • ⭕ waitResponse - Esperar respuesta del usuario (opcional, predeterminado: false)
  • ⭕ waitTime - Tiempo máximo de espera en segundos (opcional, predeterminado: 30)

🎯 Ejemplos de Configuración Completa

Ejemplo 1: Mensaje de Texto Simple

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "chatId": "123456789",
  "text": "¡Hola! Este es un mensaje de prueba de la automatización de Netsocs."
}

Ejemplo 2: Mensaje con Botones Interactivos

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "username": "juan_perez",
  "text": "Detección LPR: Vehículo ABC123 detectado en Puerta Principal",
  "commands": [
    {
      "command": "Permitir Entrada",
      "description": "Dar acceso al vehículo",
      "callbackData": "allow_entry"
    },
    {
      "command": "Denegar Entrada",
      "description": "Bloquear el vehículo",
      "callbackData": "deny_entry"
    }
  ],
  "waitResponse": true,
  "waitTime": 60
}

Ejemplo 3: Mensaje con Imagen desde URL

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "chatId": "123456789",
  "text": "¡Intrusión detectada! Ver imagen capturada a continuación:",
  "mediaURL": "https://ejemplo.com/seguridad/captura.jpg"
}

Ejemplo 4: Mensaje con Archivo Local

{
  "botToken": "7767979311:AAHEFLKJSDFLKJSDFxxx",
  "username": "equipo_seguridad",
  "text": "Reporte diario adjunto",
  "mediaFile": "/var/reportes/reporte-diario.pdf"
}

🔍 Solución de Problemas

El mensaje no se está enviando

  1. Verifica tu Token de Bot:
  2. Asegúrate de haber copiado el token completo de BotFather.

  3. El token debe verse así: 1234567890:ABCdefGHIjklMNOpqrsTUVwxyz

  4. Verifica el identificador del destinatario:

  5. Si usas username, asegúrate de que el usuario haya iniciado una conversación con tu bot.

  6. Si usas chatId, verifica que el ID sea correcto.

  7. Prueba tu bot manualmente:

  8. Intenta enviar un mensaje a tu bot desde Telegram.
  9. Si tu bot no responde, puede haber un problema con tu Token de Bot.

Error: "Forbidden: bot was blocked by the user"

Causa: El usuario ha bloqueado tu bot en Telegram.

Solución: El usuario necesita desbloquear tu bot e iniciar una nueva conversación.

Error: "Bad Request: chat not found"

Causa: El chatId o username es incorrecto, o el usuario nunca ha interactuado con tu bot.

Solución: - Verifica que el chatId o username sea correcto. - Si usas username, asegúrate de que el usuario haya enviado /start a tu bot al menos una vez.

Los botones no aparecen

  1. Verifica el formato de commands:
  2. Asegúrate de que el campo commands sea un array de objetos.

  3. Cada objeto debe tener las propiedades command, description y callbackData.

  4. Verifica la sintaxis JSON:

  5. Asegúrate de que tu JSON esté correctamente formateado (sin comas faltantes, corchetes, etc.).

El archivo multimedia no se está enviando

  1. Para mediaURL:
  2. Verifica que la URL sea públicamente accesible.

  3. Intenta abrir la URL en tu navegador para confirmar que funciona.

  4. Para mediaFile:

  5. Verifica que el archivo exista en el servidor.
  6. Verifica que el sistema Netsocs tenga permiso para leer el archivo.

📚 Información Adicional

  • Documentación de la API de Telegram Bot: Para características avanzadas, consulta la documentación oficial de la API de Telegram Bot.
  • Límites de Mensajes: Telegram tiene límites en la longitud de mensajes (4096 caracteres) y tamaños de archivo (hasta 50 MB para la mayoría de tipos de archivo).
  • Privacidad del Bot: Por defecto, los bots en grupos solo pueden ver mensajes que son respuestas directas a ellos o comandos que comienzan con /. Puedes cambiar esto en la configuración de BotFather.
  • Manejo de Respuestas: Si waitResponse es true, la automatización capturará los datos del clic del botón (callbackData) y podrá usarlos en nodos posteriores.

🔒 Mejores Prácticas de Seguridad

  1. Protege tu Token de Bot:
  2. Nunca confirmes tu Token de Bot en control de versiones (Git).

  3. Guárdalo de forma segura en variables de entorno o archivos de configuración con acceso restringido.

  4. Valida los identificadores de destinatarios:

  5. Asegúrate de enviar mensajes solo a usuarios autorizados.

  6. Limita los permisos del bot:

  7. Solo otorga a tu bot los permisos mínimos necesarios.

  8. Monitorea la actividad del bot:

  9. Revisa regularmente la actividad de tu bot en busca de comportamientos sospechosos.