Toolkit de Telegram

El Toolkit de Telegram permite a agentes y flujos de trabajo interactuar con bots de Telegram. Soporta envío y edición de mensajes, envío de medios, gestión de miembros de chat, generación de enlaces de invitación y registro de webhooks para desencadenar flujos de trabajo a partir de mensajes entrantes. Los bots de Telegram y sus credenciales se gestionan a través de un bot de Telegram llamado @BotFather — no hay consola de desarrollador web.

Prerrequisitos

Requisito	Detalle
Cuenta de Telegram	Requerido para interactuar con @BotFather

Paso 1 — Crear un Bot de Telegram

Abra @BotFather

Abra Telegram e inicie una conversación con @BotFather.

Cree un nuevo bot

Envíe el comando /newbot y siga las instrucciones:

Instrucción	Detalle
Nombre del bot	Un nombre visible legible por humanos (por ejemplo, `Mi Aplicación`)
Nombre de usuario	Debe ser único y terminar en `bot` (por ejemplo, `miapp_bot`)

Copie su token de bot

BotFather responderá con un mensaje de éxito que contiene su token de bot — se ve como 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ. Cópielo y guárdelo de forma segura.

Configure una imagen de perfil que coincida con el logotipo de su aplicación usando el comando /setuserpic en BotFather. Una imagen reconocible hace que su bot se vea profesional y confiable para los usuarios.

Paso 2 — Agregue el Token a EK

Workflow Builder
Agent Builder

En el flujo de trabajo, agregue un paso del toolkit de Telegram.
Haga clic en Seleccionar una Conexión → Crear una Conexión.
Ingrese un Nombre de Conexión y pegue su token de bot.
Haga clic en Guardar.

Gestión de su Token

Su token de bot es la clave maestra de su bot. No lo comparta, no lo envíe a repositorios públicos ni lo exponga en código del lado del cliente.

Si su token se filtra accidentalmente, revóquelo inmediatamente:

Envíe un mensaje a @BotFather
Envíe /mybots
Seleccione su bot
Toque API Token → Revocar token actual

Se generará un token nuevo. Actualice la conexión en EK con el nuevo valor.

Herramientas Disponibles

Herramienta	Descripción
Nuevo Mensaje (Activador)	Inicie un flujo de trabajo cuando se envíe un mensaje a su bot
Enviar Mensaje de Texto	Envíe un mensaje de texto de su bot a cualquier chat
Enviar Medios	Envíe una foto, video, sticker o GIF animado
Editar Texto de Mensaje	Actualice el texto de un mensaje enviado previamente
Eliminar Mensaje	Elimine un mensaje de un chat
Obtener Info del Chat	Recupere metadatos sobre un chat
Obtener Miembro del Chat	Consulte el estado de membresía de un usuario en un chat
Crear Enlace de Invitación	Genere un enlace de invitación para un grupo o canal
Registrar Webhook	Indique a Telegram que reenvíe los mensajes del bot a su flujo de trabajo
Desregistrar Webhook	Elimine el webhook y deje de recibir mensajes

Activador — Nuevo Mensaje

Inicia un flujo de trabajo automáticamente cada vez que alguien envía un mensaje a su bot de Telegram. Configuración:

Agregue el activador

Agregue un activador Nuevo Mensaje como primer paso de su flujo de trabajo. Copie la URL /tool-webhook/{workflow-id} del panel de configuración del activador.

Registre el webhook

Use el paso Registrar Webhook para indicar a Telegram que envíe mensajes a esa URL. Ejecútelo una vez — vea Registrar Webhook más abajo.

Pruebe

Envíe un mensaje de prueba a su bot. El flujo de trabajo se activará y todos los datos del mensaje estarán disponibles como variables.

Variables de activador disponibles:

Variable	Descripción
`{{ trigger.body.message.text }}`	El texto del mensaje que envió el usuario
`{{ trigger.body.message.chat.id }}`	El ID del chat — use esto como ID de Chat en todos los pasos de envío
`{{ trigger.body.message.from.id }}`	El ID de usuario de Telegram del remitente
`{{ trigger.body.message.from.first_name }}`	El nombre del remitente
`{{ trigger.body.message.from.username }}`	El nombre de usuario del remitente (puede estar vacío)
`{{ trigger.body.message.message_id }}`	El ID del mensaje entrante
`{{ trigger.body.update_id }}`	El ID de actualización único de Telegram

Acciones de Mensajería

Enviar Mensaje de Texto

Envía un mensaje de texto de su bot a cualquier chat de Telegram. Entradas principales:

Entrada	Descripción
Chat ID	El chat al que enviar. Para la persona que activó el flujo de trabajo, use `{{ trigger.body.message.chat.id }}`. Para un grupo o canal fijo, pegue su ID numérico.
Mensaje	El texto a enviar. Mezcle texto estático con variables, por ejemplo `Hola {{ trigger.body.message.from.first_name }}, su solicitud ha sido recibida.`
Formato	Deje en blanco para texto plano. Establezca en `HTML` para `<b>negrita</b>` / `<i>cursiva</i>`. Establezca en `MarkdownV2` para Markdown (los caracteres especiales se escapan automáticamente).
Deshabilitar Vista Previa de Página Web	Establezca en `true` para suprimir vistas previas de enlaces
ID de Hilo de Mensaje	Opcional — solo relevante para supergrupos de Foro
Marcado de Respuesta	Opcional — un objeto JSON para teclados en línea o teclados de respuesta personalizados

Referencia de la salida en pasos posteriores:

ID de Mensaje (necesario para Editar o Eliminar después): {{ step.output.message_id }}
Chat ID: {{ step.output.chat_id }}

Enviar Medios

Envía una foto, video, sticker o GIF animado a un chat de Telegram. Entradas principales:

Entrada	Descripción
Chat ID	El chat al que enviar
Tipo de Medio	Debe ser exactamente uno de: `photo`, `video`, `sticker`, `animation`
URL del Medio	Una URL HTTPS accesible públicamente al archivo — Telegram lo obtiene directamente
ID del Medio	Alternativamente, un `file_id` de Telegram de un archivo cargado previamente. Proporcione URL del Medio o ID del Medio, no ambos.
Pie de Foto	Texto opcional mostrado debajo del medio. Soporta HTML/MarkdownV2 a través de Formato.
Formato	Modo de análisis para el pie de foto
ID de Hilo de Mensaje	Opcional — para temas de supergrupos de foro

Si no se proporciona URL del Medio ni ID del Medio, el paso devuelve un error. La URL debe ser accesible públicamente — las URLs locales o privadas no funcionarán.

Editar Texto de Mensaje

Actualiza el texto de un mensaje enviado previamente por su bot. Entradas principales:

Entrada	Descripción
Chat ID	El chat donde está el mensaje original
ID de Mensaje	El `message_id` de la salida de Enviar Mensaje de Texto — `{{ step.output.message_id }}`
Texto	El nuevo contenido del mensaje
Formato	Modo de análisis para el nuevo texto (en blanco = texto plano, `HTML` o `MarkdownV2`)

Ejemplo de caso de uso: Envíe primero “Procesando su solicitud…”. Ejecute la lógica del flujo de trabajo. Luego edite ese mensaje con el resultado final — el usuario ve un mensaje en lugar de dos.

Eliminar Mensaje

Elimina un mensaje de un chat. Entradas principales:

Entrada	Descripción
Chat ID	El chat que contiene el mensaje
ID de Mensaje	El `message_id` del mensaje a eliminar

Los bots solo pueden eliminar sus propios mensajes a menos que el bot sea administrador en el chat. Telegram también impone un límite de tiempo — los mensajes de más de 48 horas generalmente no pueden ser eliminados por bots.

Acciones de Chat y Miembros

Obtener Info del Chat

Recupera metadatos sobre un chat. Entradas principales:

Entrada	Descripción
Chat ID	El chat a consultar

Referencia de valores en pasos posteriores:

Título del chat: {{ step.output.title }}
Descripción: {{ step.output.description }}
Enlace de invitación: {{ step.output.invite_link }}

Obtener Miembro del Chat

Consulta un usuario específico dentro de un chat y devuelve su estado de membresía y rol. Entradas principales:

Entrada	Descripción
Chat ID	El chat a consultar
ID de Usuario	El ID de usuario de Telegram a consultar. Para la persona que activó el flujo de trabajo, use `{{ trigger.body.message.from.id }}`.

Referencia de valores en pasos posteriores:

Estado: {{ step.output.status }}
Nombre de usuario: {{ step.output.username }}

Posibles valores de estado: creator, administrator, member, restricted, left, kicked Ejemplo de caso de uso: Verifique {{ step.output.status }} — si es igual a left o kicked, omita el envío del mensaje y maneje el error en su lugar.

Crear Enlace de Invitación

Genera un nuevo enlace de invitación para un grupo o canal.

El bot debe ser administrador con el permiso “Invitar Usuarios” en el chat objetivo.

Entradas principales:

Entrada	Descripción
Chat ID	El grupo o canal
Nombre	Etiqueta opcional para el enlace (hasta 32 caracteres), visible en el panel de administración de Telegram
Fecha de Expiración	Opcional. Una cadena ISO-8601 cuando el enlace expira, por ejemplo `2026-12-31T23:59:59Z`. Se convierte internamente a un timestamp unix.
Límite de Miembros	Opcional. Número máximo de personas que pueden unirse a través de este enlace (1–99,999)

Referencia del enlace en pasos posteriores:

URL de Invitación: {{ step.output.invite_link }}

expire_date en la salida es un timestamp unix (segundos enteros), no formato ISO. creates_join_request será true si el chat requiere aprobación de administrador para nuevos miembros.

Acciones de Configuración de Webhook

Estos dos pasos conectan un activador de Nuevo Mensaje con su bot. Ejecútelos una vez por flujo de trabajo.

Registrar Webhook

Indica a Telegram que comience a reenviar mensajes de su bot a la URL de su flujo de trabajo. Entradas principales:

Entrada	Descripción
URL	La URL `/tool-webhook/{workflow-id}` del panel del activador de Nuevo Mensaje
Actualizaciones Permitidas	Establezca en `[\"message\"]` para recibir solo mensajes regulares (recomendado). Deje en blanco para usar el mismo predeterminado.
Token Secreto	Opcional pero recomendado. Cualquier cadena aleatoria (por ejemplo, `my-secret-abc123`). Telegram la incluye en el encabezado de cada solicitud webhook para que pueda verificar que las solicitudes son genuinas.
Descartar Actualizaciones Pendientes	Establezca en `true` para ignorar mensajes que llegaron antes de que se registrara el webhook

Copie la URL del activador

Cree un flujo de trabajo con un activador de Nuevo Mensaje. Copie la URL /tool-webhook/{workflow-id} del panel del activador.

Agregue Registrar Webhook

En un flujo de trabajo único o prueba manual separada, agregue un paso Registrar Webhook y complete las entradas anteriores.

Ejecútelo una vez

Ejecute el paso. Luego envíe un mensaje a su bot — su flujo de trabajo principal ahora debería activarse.

Alternativamente, registre a través de curl para una configuración rápida única:

curl -X POST "https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-domain.com/tool-webhook/<YOUR_WORKFLOW_ID>",
    "allowed_updates": ["message"],
    "secret_token": "my-secret-abc123"
  }'

Una respuesta exitosa:

{ "ok": true, "result": true, "description": "Webhook was set" }

Un bot de Telegram solo puede tener un webhook activo a la vez. Registrar una nueva URL reemplaza cualquier anterior.

Desregistrar Webhook

Elimina el webhook y deja que Telegram deje de enviar mensajes a su flujo de trabajo. Entradas principales:

Entrada	Descripción
Descartar Actualizaciones Pendientes	Establezca en `true` para descartar cualquier mensaje en cola mientras el webhook estaba activo

Desregitre el webhook cuando retire o archive un flujo de trabajo. Si deja el webhook registrado pero el flujo de trabajo inactivo, Telegram seguirá enviando solicitudes que quedarán sin respuesta.

Solución de Problemas

Síntoma	Causa Probable	Solución
El flujo de trabajo no se activa con nuevos mensajes	Webhook no registrado o apuntando a URL incorrecta	Ejecute Registrar Webhook con la URL del activador correcta
`401 Unauthorized`	Token de bot inválido o revocado	Verifique el token o genere uno nuevo a través de @BotFather
Medios no entregados	URL no accesible públicamente	Use una URL HTTPS pública — las URLs locales o privadas no funcionarán
No se puede eliminar un mensaje	El mensaje tiene más de 48 horas o el bot no es administrador	Los bots solo pueden eliminar mensajes recientes a menos que tengan privilegios de administrador
`creates_join_request: true` en enlace de invitación	El chat requiere aprobación de administrador para nuevos miembros	Este es un comportamiento esperado — los usuarios deben ser aprobados antes de unirse
Mensajes viejos activan el flujo de trabajo	Actualizaciones pendientes no eliminadas durante el registro del webhook	Registre nuevamente con `Descartar Actualizaciones Pendientes` establecido en `true`

Get Started!

Offerings

Chat

Agents

Knowledge Base

Workflows

Interfaces

Public Chatbot

Project Settings

My Account

Platform Admin

SDK

General Information

Prerrequisitos

Paso 1 — Crear un Bot de Telegram

Paso 2 — Agregue el Token a EK

Gestión de su Token

Herramientas Disponibles

Activador — Nuevo Mensaje

Acciones de Mensajería

Enviar Mensaje de Texto

Enviar Medios

Editar Texto de Mensaje

Eliminar Mensaje

Acciones de Chat y Miembros

Obtener Info del Chat

Obtener Miembro del Chat

Crear Enlace de Invitación

Acciones de Configuración de Webhook

Registrar Webhook

Desregistrar Webhook

Solución de Problemas

​Prerrequisitos

​Paso 1 — Crear un Bot de Telegram

​Paso 2 — Agregue el Token a EK

​Gestión de su Token

​Herramientas Disponibles

​Activador — Nuevo Mensaje

​Acciones de Mensajería

​Enviar Mensaje de Texto

​Enviar Medios

​Editar Texto de Mensaje

​Eliminar Mensaje

​Acciones de Chat y Miembros

​Obtener Info del Chat

​Obtener Miembro del Chat

​Crear Enlace de Invitación

​Acciones de Configuración de Webhook

​Registrar Webhook

​Desregistrar Webhook

​Solución de Problemas

Prerrequisitos

Paso 1 — Crear un Bot de Telegram

Paso 2 — Agregue el Token a EK

Gestión de su Token

Herramientas Disponibles

Activador — Nuevo Mensaje

Acciones de Mensajería

Enviar Mensaje de Texto

Enviar Medios

Editar Texto de Mensaje

Eliminar Mensaje

Acciones de Chat y Miembros

Obtener Info del Chat

Obtener Miembro del Chat

Crear Enlace de Invitación

Acciones de Configuración de Webhook

Registrar Webhook

Desregistrar Webhook

Solución de Problemas