Configura tu bot de Telegram con el Gateway

Configurar un bot de Telegram suele implicar pelearse con tokens, permisos de privacidad y configuraciones de grupo que no siempre funcionan a la primera. Es tedioso pasar tiempo ajustando detalles técnicos cuando lo que realmente importa es que tu bot empiece a procesar mensajes de forma estable.

Aquí tienes la guía para conectar Telegram con el Gateway de manera directa.

Requisitos previos

• Una cuenta de Telegram activa.
• El CLI openclaw instalado en tu entorno.
• Acceso a @BotFather para generar credenciales.

Inicio rápido

Sigue estos pasos para tener tu bot funcionando en menos de 5 minutos. El sistema utiliza grammY y, por defecto, trabaja en modo long polling.

1. Crea el bot token en BotFather

Abre Telegram y busca a @BotFather (asegúrate de que el handle sea exactamente @BotFather).

Ejecuta el comando /newbot, sigue las instrucciones y guarda el token generado.

2. Configura el token y la política de DM

Añade la configuración en tu archivo JSON. Si prefieres usar variables de entorno, puedes usar TELEGRAM_BOT_TOKEN, pero ten en cuenta que esto solo aplica a la cuenta por defecto.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

3. Inicia el Gateway y aprueba el primer DM

Usa los siguientes comandos para activar el canal y vincular tu cuenta:

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Los códigos de pairing caducan tras 1 hora.

4. Añade el bot a un grupo

Añade el bot a tu grupo de Telegram. Después, ajusta channels.telegram.groups y groupPolicy para que coincidan con tu modelo de acceso.

Nota sobre los tokens: El orden de resolución de tokens prioriza la configuración del archivo JSON sobre las variables de entorno.

Solución de problemas

Si tu bot no se comporta como esperas, revisa estos puntos basados en los ajustes de Telegram:

El bot no recibe mensajes en los grupos Los bots de Telegram tienen activado el Privacy Mode por defecto. Esto limita los mensajes que pueden ver. Para solucionarlo tienes dos opciones:

• Desactiva el modo de privacidad con el comando /setprivacy en BotFather.
• Haz que el bot sea administrador del grupo.

Importante: Si cambias el modo de privacidad, debes eliminar y volver a añadir el bot al grupo para que Telegram aplique los cambios.

Permisos de administrador Si necesitas que el bot procese todos los mensajes sin restricciones, asígnale el estado de administrador en los ajustes del grupo de Telegram. Los bots administradores reciben todo el tráfico de mensajes del grupo.

Comandos útiles en BotFather

• /setjoingroups: Controla si tu bot puede ser añadido a grupos.
• /setprivacy: Gestiona la visibilidad de los mensajes en grupos.

Si necesitas ayuda personalizada para tu caso de uso, consulta al AI Setup Assistant.

Próximos pasos

• Pairing: Detalles sobre la política de DM por defecto.
• Channel troubleshooting: Diagnóstico y reparación de canales.
• Gateway configuration: Ejemplos completos de patrones de configuración.

---
title: Control de acceso y activación
description: Configura quién puede interactuar con tu bot y cómo se activan las respuestas en grupos y DMs.
---

Configurar un bot es sencillo, pero controlar quién tiene permiso para hablar con él puede ser un dolor de cabeza. No quieres que tu bot responda a usuarios no autorizados o que sature un grupo con mensajes innecesarios porque no configuraste bien las reglas de activación.

Gestionar el acceso correctamente evita interacciones no deseadas y asegura que el bot solo responda cuando tú lo decidas. En esta guía verás cómo configurar estas reglas de forma directa en tu Gateway.

## Requisitos previos

- Un bot de Telegram activo y su token.
- Acceso al archivo de configuración de tu instancia.
- La herramienta CLI `openclaw` instalada.
- Una cuenta de Telegram para realizar pruebas.

## Inicio rápido

Para restringir el acceso y configurar la activación básica en 5 minutos, sigue estos pasos:

1. **Define la política de DM**: Configura `channels.telegram.dmPolicy` en tu archivo de configuración. El valor por defecto es `pairing`.
2. **Identifica tu ID**: Usa `openclaw logs --follow` mientras envías un mensaje al bot para ver tu `from.id`.
3. **Configura la lista de permitidos**: Añade tu ID o username en `channels.telegram.allowFrom`.
4. **Establece el comportamiento en grupos**: Decide si el bot requiere mención explícita usando `requireMention`.

## Control de DMs y activación

La propiedad `channels.telegram.dmPolicy` controla quién puede enviar mensajes directos al bot. Tienes estas opciones:

- `pairing` (predeterminado)
- `allowlist`
- `open` (requiere que `allowFrom` incluya `*`)
- `disabled`

La opción `channels.telegram.allowFrom` acepta IDs numéricos y usernames. Los prefijos `telegram:` o `tg:` son aceptados y se normalizan automáticamente.

### Cómo encontrar tu ID de usuario de Telegram

Existen dos formas principales y seguras de obtener tu ID sin depender de herramientas externas poco privadas:

**Método recomendado (vía logs):**
1. Envía un mensaje directo a tu bot.
2. Ejecuta el comando `openclaw logs --follow` en tu terminal.
3. Busca el campo `from.id` en la salida del log.

**Método oficial de la API:**
Usa `curl` para consultar los updates de tu bot:
```bash
curl "https://api.telegram.org/bot\<bot_token\>/getUpdates"

También existen bots de terceros como @userinfobot o @getidsbot, aunque son menos privados.

Grupos y listas de permitidos

El control en grupos se gestiona mediante dos capas independientes:

1. Grupos permitidos (channels.telegram.groups):

   • Si no configuras groups, se permiten todos los grupos.
   • Si configuras groups, funciona como una allowlist (usa IDs explícitos o *).

2. Remitentes permitidos en grupos (channels.telegram.groupPolicy):

   • open
   • allowlist (predeterminado)
   • disabled

Para filtrar quién puede enviar mensajes dentro de un grupo, se usa groupAllowFrom. Si no lo defines, el sistema usará los valores de allowFrom.

Ejemplo para permitir que cualquier miembro interactúe en un grupo específico:

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          groupPolicy: "open",
          requireMention: false,
        },
      },
    },
  },
}

Comportamiento de las menciones

Por defecto, el bot solo responderá en grupos si es mencionado. El sistema reconoce la mención si:

• Usas la mención nativa @botusername.
• El mensaje coincide con los patrones definidos en agents.list[].groupChat.mentionPatterns o messages.groupChat.mentionPatterns.

Puedes cambiar este comportamiento de forma temporal en la sesión actual con estos comandos:

• /activation always
• /activation mention

Ten en cuenta que estos comandos solo actualizan el estado de la sesión. Para cambios permanentes, usa la configuración:

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false },
      },
    },
  },
}

Solución de problemas

Si el bot no responde o no reconoce a un usuario, verifica los identificadores de chat:

• No encuentras el Chat ID del grupo: Reenvía un mensaje del grupo a @userinfobot o busca el campo chat.id ejecutando openclaw logs --follow.
• El bot ignora mensajes en grupos: Revisa si requireMention está activo. Si lo está, el bot no responderá a menos que uses @botusername o los patrones configurados.
• Error de permisos: Verifica que el ID del usuario esté correctamente incluido en allowFrom o groupAllowFrom si la política es allowlist.
• Logs vacíos: Asegúrate de que el bot no esté en modo de privacidad de Telegram si esperas que lea todos los mensajes de un grupo sin mención.

Si necesitas ayuda personalizada para configurar tus políticas de acceso, consulta nuestro AI Setup Assistant.

Próximos pasos

• Telegram Channel Configuration
• Agent Group Chat Settings

Gestionar estados de chat y ruteo de mensajes en Telegram puede ser un dolor de cabeza si no entiendes cómo se procesan los datos por debajo. Es frustrante cuando los mensajes terminan en el hilo equivocado o cuando la concurrencia satura tu bot sin previo aviso.

Para evitar estos problemas, necesitas saber exactamente cómo interactúa el Gateway con la API de Telegram. Aquí te explico cómo funciona el runtime para que tus agentes respondan siempre de forma predecible.

## Requisitos previos

- Acceso al proceso del Gateway.
- Configuración definida en `agents.defaults.maxConcurrent`.

## Inicio rápido

Entender el ciclo de vida de un mensaje te tomará menos de 5 minutos. Sigue estos puntos clave para dominar el comportamiento del runtime:

1. **Propiedad del proceso**: Ten en cuenta que Telegram pertenece exclusivamente al proceso del Gateway.
2. **Ruteo determinista**: El flujo es predecible. Si un mensaje entra por Telegram, la respuesta vuelve a Telegram. El modelo no elige los canales de salida de forma aleatoria.
3. **Normalización de mensajes**: Todos los mensajes entrantes se convierten en un "envelope" de canal compartido. Esto incluye metadatos de respuesta y placeholders para archivos multimedia.
4. **Aislamiento de sesiones**: El sistema separa las sesiones de grupo mediante el ID del grupo. En el caso de los foros, se añade `:topic:<threadId>` para mantener cada tema aislado.

## Detalles del Runtime

Cuando trabajas con mensajes directos (DM), estos pueden incluir un `message_thread_id`. OpenClaw gestiona esto mediante session keys que reconocen los hilos (thread-aware) y mantiene el ID del hilo para todas las respuestas.

Para el manejo de datos, el sistema utiliza long polling mediante grammY runner. Esto permite una secuenciación por chat o por hilo. Si necesitas controlar cuántos procesos ocurren al mismo tiempo, debes ajustar el sink de concurrencia global en la configuración `agents.defaults.maxConcurrent`.

## Solución de problemas

Si encuentras comportamientos inesperados, revisa estos puntos basados en las limitaciones de la API:

- **Las confirmaciones de lectura no funcionan**: Si intentas usar `sendReadReceipts`, no verás ningún resultado. La Telegram Bot API no ofrece soporte para confirmaciones de lectura, por lo que esta opción no aplica aquí.
- **Sesiones mezcladas en foros**: Asegúrate de que los IDs de los hilos se estén pasando correctamente. Si falta el sufijo `:topic:<threadId>`, el aislamiento de la sesión podría fallar.

Para resolver dudas específicas sobre tu implementación, consulta al [AI Setup Assistant](/docs/).

## Próximos pasos

- [Configuración de Agentes](/docs/agents-config)
- [Gestión de Canales](/docs/channels)

¿Alguna vez has sentido que tu bot de Telegram es demasiado lento o que la interfaz es poco intuitiva? Gestionar manualmente el streaming de mensajes o los menús de comandos puede ser un dolor de cabeza constante. OpenClaw soluciona esto automatizando la integración con la API de Telegram para que tu bot se sienta nativo y fluido sin que tengas que escribir código repetitivo.

Aquí tienes todo lo que necesitas para exprimir al máximo las capacidades de Telegram.

## Requisitos previos

- Una cuenta de Telegram y un bot token.
- Configuración de `channels.telegram` en tu archivo de configuración.
- Plugin `device-pair` (opcional, si necesitas vinculación con iOS).
- Soporte para tópicos habilitado (`getMe().has_topics_enabled`) si usas grupos tipo foro.

## Inicio rápido

Para poner en marcha las funciones principales en menos de 5 minutos, asegúrate de tener estas opciones básicas:

1. **Streaming de borradores**: Activa `channels.telegram.streamMode: "partial"` para ver cómo el bot escribe en tiempo real.
2. **Comandos nativos**: Configura `commands.native: "auto"` para que el menú de comandos se registre solo al iniciar.
3. **Botones inline**: Define el scope en `allowlist` para controlar quién interactúa con los botones.

## Streaming de borradores en DMs

OpenClaw puede enviar respuestas parciales usando las burbujas de borrador de Telegram (`sendMessageDraft`). Esto solo funciona en chats privados (DMs).

**Requisitos:**
- `channels.telegram.streamMode` no debe estar en `"off"` (por defecto es `"partial"`).
- El bot debe tener los tópicos habilitados.

**Modos disponibles:**
- `off`: Sin streaming de borradores.
- `partial`: Actualizaciones frecuentes del borrador según el texto parcial generado.
- `block`: Actualizaciones por fragmentos usando `channels.telegram.draftChunk`.

Si prefieres recibir mensajes reales de Telegram de forma temprana en lugar de actualizaciones de borrador, usa `channels.telegram.blockStreaming: true`.

Para el streaming de razonamiento, el comando `/reasoning stream` envía el proceso de pensamiento al borrador mientras se genera, entregando solo la respuesta final al terminar.

## Formato y fallback de HTML

El texto de salida utiliza `parse_mode: "HTML"`. OpenClaw renderiza texto tipo Markdown a HTML seguro para Telegram. Si Telegram rechaza el HTML por errores de parseo, OpenClaw reintenta el envío automáticamente como texto plano.

Puedes desactivar las vistas previas de enlaces con `channels.telegram.linkPreview: false`.

## Comandos nativos y personalizados

El registro del menú de comandos se gestiona al arrancar mediante `setMyCommands`. Los nombres se normalizan automáticamente (se eliminan las `/` iniciales y se pasa a minúsculas).

Puedes añadir entradas personalizadas al menú:

```json
{
  channels: {
    telegram: {
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
    },
  },
}

Reglas de comandos:

• Patrón válido: a-z, 0-9, _, longitud de 1 a 32 caracteres.
• Los comandos personalizados no pueden sobrescribir a los nativos.
• Si desactivas los comandos nativos, los integrados se eliminan del menú.

Comandos de emparejamiento (plugin device-pair)

Si instalas este plugin, dispones de este flujo:

1. /pair genera el código de configuración.
2. Pegas el código en la app de iOS.
3. /pair approve confirma la solicitud pendiente.

Más detalles en: Pairing.

Botones inline

Configura el alcance del teclado inline para mayor seguridad:

{
  channels: {
    telegram: {
      capabilities: {
        inlineButtons: "allowlist",
      },
    },
  },
}

Los scopes disponibles son: off, dm, group, all y allowlist.

Cuando un usuario hace clic, el callback_data se envía al agente como texto: callback_data: <value>.

Ejemplo de acción de mensaje con botones:

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Choose an option:",
  buttons: [
    [
      { text: "Yes", callback_data: "yes" },
      { text: "No", callback_data: "no" },
    ],
    [{ text: "Cancel", callback_data: "cancel" }],
  ],
}

Acciones de mensaje y automatización

OpenClaw expone herramientas para que los agentes interactúen con la API:

• sendMessage, react, deleteMessage, editMessage.

Puedes controlar qué acciones están permitidas mediante estos flags:

• channels.telegram.actions.sendMessage
• channels.telegram.actions.editMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (desactivado por defecto)

Tópicos de foros y comportamiento de hilos

En supergrupos tipo foro, OpenClaw maneja los hilos de forma inteligente:

• Las claves de sesión incluyen el threadId.
• Las respuestas y los indicadores de escritura apuntan al tópico correcto.
• El tópico general (threadId=1) es un caso especial: los mensajes omiten el message_thread_id porque Telegram lo rechaza en ese ID, aunque las acciones de escritura sí lo incluyen.

Audio, video y stickers

Audio y Video

Telegram diferencia entre notas de voz y archivos de audio. Usa el tag [[audio_as_voice]] en la respuesta del agente para forzar el envío como nota de voz.

Para video notes (mensajes circulares), usa asVideoNote: true. Ten en cuenta que estos no admiten subtítulos (captions); el texto se enviará por separado.

Stickers

OpenClaw procesa stickers estáticos WEBP y los describe mediante visión artificial, guardando el resultado en ~/.openclaw/telegram/sticker-cache.json para ahorrar recursos. Los stickers animados (TGS) o de video (WEBM) se ignoran.

Para habilitar el envío de stickers:

{
  channels: {
    telegram: {
      actions: {
        sticker: true,
      },
    },
  },
}

Notificaciones de reacciones

Las reacciones llegan como actualizaciones independientes. Puedes configurar el nivel de detalle:

• channels.telegram.reactionNotifications: off | own | all.
• channels.telegram.reactionLevel: off | ack | minimal | extensive.

Nota: Telegram no envía el ID del hilo en las actualizaciones de reacciones. En foros, estas se redirigen al tópico general.

Webhook vs Long Polling

Por defecto, OpenClaw usa long polling. Si prefieres Webhook:

• Configura channels.telegram.webhookUrl.
• Define channels.telegram.webhookSecret (obligatorio).
• El listener local corre en 0.0.0.0:8787.

Límites y CLI

Puedes enviar mensajes desde la terminal usando el ID numérico o el username:

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"

El límite por defecto de fragmentos de texto es de 4000 caracteres (textChunkLimit).

Solución de problemas

• setMyCommands failed: Normalmente significa que el DNS o el tráfico HTTPS hacia api.telegram.org está bloqueado en tu red o servidor.
• Tópicos en foros: Si el bot no responde en un hilo específico, verifica que message_thread_id esté presente en el update entrante.
• Stickers: Si los stickers no aparecen en el contexto del agente, comprueba que sean formato WEBP estático; los formatos TGS y WEBM no son compatibles actualmente.

AI Setup Assistant

Próximos pasos

• Configuración de Pairing
• Gestión de Reacciones

---
title: "Solucionando problemas en tu integración de Telegram"
description: "Guía para diagnosticar y arreglar errores comunes de configuración, conectividad y permisos en tu Gateway de Telegram."
---

Seguro te ha pasado: terminas de configurar tu bot, todo parece estar en orden, pero cuando envías un mensaje, no recibes respuesta. Revisas el código, reinicias el proceso y el silencio continúa. Es frustrante cuando la comunicación entre tu Gateway y la API de Telegram se rompe sin una razón evidente.

No pierdas tiempo intentando adivinar qué falla. Aquí tienes los pasos directos para identificar por qué tu bot no se comporta como esperas y cómo solucionarlo rápidamente.

## Requisitos previos

- Node.js 22 o superior.
- Acceso a BotFather en Telegram.
- Openclaw CLI instalado y configurado.
- Credenciales de tu bot (botToken).

## Inicio rápido

Si algo no funciona, sigue esta ruta de 5 minutos para encontrar el problema:

1. **Monitorea en tiempo real**: Ejecuta `openclaw logs --follow` para ver por qué se están ignorando los mensajes.
2. **Verifica el estado**: Usa `openclaw channels status` para detectar errores de configuración en tus canales.
3. **Prueba forzada**: Envía el comando `/activation always` en el chat para verificar si la sesión está activa.
4. **Validación de red**: Confirma que tu servidor llega a `api.telegram.org` sin bloqueos de DNS o IPv6.

## Solución de problemas

### El bot no responde a mensajes de grupo sin mención

Si configuraste `requireMention=false` pero el bot sigue ignorando mensajes que no lo mencionan directamente:

- El modo de privacidad de Telegram debe permitir visibilidad total. Ve a BotFather, usa `/setprivacy` y selecciona **Disable**. Después, elimina y vuelve a añadir el bot al grupo.
- Ejecuta `openclaw channels status`. El CLI te avisará si tu configuración espera mensajes sin mención pero el canal no está listo.
- Para grupos específicos, usa `openclaw channels status --probe` con el ID numérico del grupo. Ten en cuenta que el comodín `"*"` no permite realizar este sondeo de membresía.
- Haz un test rápido de sesión con `/activation always`.

### El bot no ve ningún mensaje en los grupos

Si el bot parece estar "ciego" ante cualquier actividad grupal:

- Si la propiedad `channels.telegram.groups` existe en tu configuración, el grupo debe estar listado explícitamente o incluir el comodín `"*"` para permitirlos todos.
- Verifica que el bot sea miembro del grupo con los permisos necesarios.
- Revisa los logs con `openclaw logs --follow` para encontrar los motivos específicos del descarte (skip reasons).

### Los comandos funcionan parcialmente o no funcionan

Cuando los comandos se ejecutan a veces o fallan por completo:

- Autoriza tu identidad de remitente mediante el proceso de pairing o configurando `allowFrom`.
- Recuerda que la autorización de comandos se aplica incluso si la política del grupo está marcada como `open`.
- Si recibes un error tipo `setMyCommands failed`, suele indicar problemas de conectividad DNS o HTTPS hacia `api.telegram.org`.

### Inestabilidad de red o Polling

Si experimentas desconexiones o comportamiento errático:

- Node.js 22+ junto con fetch personalizado o proxies puede causar abortos inmediatos si hay un desajuste en los tipos de `AbortSignal`.
- Algunos hosts resuelven `api.telegram.org` primero por IPv6. Si tu salida IPv6 está rota, causarás fallos intermitentes en la API de Telegram.
- Valida tus respuestas de DNS con estos comandos:

```bash
dig +short api.telegram.org A
dig +short api.telegram.org AAAA

Si necesitas ayuda adicional, consulta la sección extendida de Channel troubleshooting.

Telegram config reference pointers

Usa estas referencias para ajustar tu Gateway. La referencia principal se encuentra en Configuration reference - Telegram.

Campos clave para revisar:

• Startup y Auth: enabled, botToken, tokenFile, accounts.*
• Control de acceso: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups, groups.*.topics.*
• Comandos y Menú: commands.native, customCommands
• Hilos y Respuestas: replyToMode
• Streaming: streamMode, draftChunk, blockStreaming
• Formato y Entrega: textChunkLimit, chunkMode, linkPreview, responsePrefix
• Media y Red: mediaMaxMb, timeoutSeconds, retry, network.autoSelectFamily, proxy
• Webhook: webhookUrl, webhookSecret, webhookPath
• Acciones y Capacidades: capabilities.inlineButtons, actions.sendMessage|editMessage|deleteMessage|reactions|sticker
• Reacciones: reactionNotifications, reactionLevel
• Escritura e Historial: configWrites, historyLimit, dmHistoryLimit, dms.*.historyLimit

¿Sigues con dudas sobre tu configuración? Prueba el AI Setup Assistant para obtener ayuda personalizada.

Próximos pasos

• Pairing
• Channel routing
• Troubleshooting