> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Toolkit de Telegram
> Conecte su bot de Telegram a agentes y flujos de trabajo para enviar mensajes, gestionar chats y desencadenar automatizaciones a partir de mensajes entrantes.
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 Telegram e inicie una conversación con [@BotFather](https://t.me/BotFather).
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`) |
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
1. En el flujo de trabajo, agregue un paso del toolkit de Telegram.
2. Haga clic en **Seleccionar una Conexión** → **Crear una Conexión**.
3. Ingrese un **Nombre de Conexión** y pegue su token de bot.
4. Haga clic en **Guardar**.
1. Abra su agente en el **Agent Builder**.
2. Vaya a la pestaña **Toolkits** en la barra lateral izquierda.
3. Encuentre **Telegram** y haga clic en **Agregar al Agente**.
4. Pegue su token de bot en **Token de Bot de Telegram**.
5. 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:
1. Envíe un mensaje a @BotFather
2. Envíe `/mybots`
3. Seleccione su bot
4. 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 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.
Use el paso **Registrar Webhook** para indicar a Telegram que envíe mensajes a esa URL. Ejecútelo una vez — vea [Registrar Webhook](#register-webhook) más abajo.
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 `negrita` / `cursiva`. 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 |
Cree un flujo de trabajo con un activador de Nuevo Mensaje. Copie la URL `/tool-webhook/{workflow-id}` del panel del activador.
En un flujo de trabajo único o prueba manual separada, agregue un paso **Registrar Webhook** y complete las entradas anteriores.
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:
```bash theme={null}
curl -X POST "https://api.telegram.org/bot/setWebhook" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/tool-webhook/",
"allowed_updates": ["message"],
"secret_token": "my-secret-abc123"
}'
```
Una respuesta exitosa:
```json theme={null}
{ "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` |