Telegram

• desactivar el modo de privacidad mediante /setprivacy, o
• convertir el bot en administrador del grupo.

• /setjoingroups para permitir/denegar agregados a grupos
• /setprivacy para el comportamiento de visibilidad en grupos

• chats directos: mensaje de vista previa + editMessageText
• grupos/temas: mensaje de vista previa + editMessageText

• channels.telegram.streaming es off | partial | block | progress (predeterminado: partial)
• progress conserva un borrador de estado editable para el progreso de herramientas, lo borra al finalizar y envía la respuesta final como un mensaje normal
• streaming.preview.toolProgress controla si las actualizaciones de herramientas/progreso reutilizan el mismo mensaje de vista previa editado (predeterminado: true cuando la transmisión de vista previa está activa)
• streaming.preview.commandText controla el detalle de comando/ejecución dentro de esas líneas de progreso de herramientas: raw (predeterminado, conserva el comportamiento publicado) o status (solo etiqueta de herramienta)
• se detectan los valores heredados channels.telegram.streamMode y los valores booleanos de streaming; ejecuta openclaw doctor --fix para migrarlos a channels.telegram.streaming.mode

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "commandText": "status"
        }
      }
    }
  }
}

{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

• vistas previas breves de DM/grupo/tema: OpenClaw conserva el mismo mensaje de vista previa y realiza la edición final en el mismo lugar
• las respuestas finales de texto largo que se dividen en varios mensajes de Telegram reutilizan la vista previa existente como el primer fragmento final cuando es posible, y luego envían solo los fragmentos restantes
• las respuestas finales en modo progreso borran el borrador de estado y usan entrega final normal en lugar de editar el borrador para convertirlo en la respuesta
• si la edición final falla antes de que se confirme el texto completado, OpenClaw usa la entrega final normal y limpia la vista previa obsoleta

• /reasoning stream envía el razonamiento a la vista previa en vivo mientras genera
• la vista previa de razonamiento se elimina después de la entrega final; usa /reasoning on cuando el razonamiento deba permanecer visible
• la respuesta final se envía sin texto de razonamiento

• El texto similar a Markdown se renderiza como HTML seguro para Telegram.
• Las etiquetas HTML compatibles con Telegram se conservan; el HTML no compatible se escapa.
• Si Telegram rechaza el HTML analizado, OpenClaw reintenta como texto sin formato.

• commands.native: "auto" habilita comandos nativos para Telegram

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

• los nombres se normalizan (se elimina la / inicial, minúsculas)
• patrón válido: a-z, 0-9, _, longitud 1..32
• los comandos personalizados no pueden sobrescribir comandos nativos
• los conflictos/duplicados se omiten y se registran

• los comandos personalizados son solo entradas de menú; no implementan comportamiento automáticamente
• los comandos de plugin/skill aún pueden funcionar al escribirse aunque no se muestren en el menú de Telegram

• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa que el menú de Telegram siguió desbordándose después del recorte; reduce los comandos de plugin/skill/personalizados o deshabilita channels.telegram.commands.native.
• deleteWebhook, deleteMyCommands o setMyCommands fallan con 404: Not Found mientras los comandos curl directos de la Bot API funcionan puede significar que channels.telegram.apiRoot se estableció en el endpoint completo /bot<TOKEN>. apiRoot debe ser solo la raíz de la Bot API, y openclaw doctor --fix elimina un /bot<TOKEN> final accidental.
• getMe returned 401 significa que Telegram rechazó el token de bot configurado. Actualiza botToken, tokenFile o TELEGRAM_BOT_TOKEN con el token actual de BotFather; OpenClaw se detiene antes del sondeo, por lo que esto no se informa como un error de limpieza de Webhook.
• setMyCommands failed con errores de red/fetch normalmente significa que el DNS/HTTPS saliente hacia api.telegram.org está bloqueado.

​

Comandos de emparejamiento de dispositivos (plugin device-pair)

1. /pair genera un código de configuración
2. pega el código en la app de iOS
3. /pair pending lista las solicitudes pendientes (incluidos rol/ámbitos)
4. aprueba la solicitud:
   • /pair approve <requestId> para aprobación explícita
   • /pair approve cuando solo hay una solicitud pendiente
   • /pair approve latest para la más reciente

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

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

• off
• dm
• group
• all
• allowlist (predeterminado)

{
  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" }],
  ],
}

• sendMessage (to, content, mediaUrl opcional, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (predeterminado: deshabilitado)

• [[reply_to_current]] responde al mensaje activador
• [[reply_to:<id>]] responde a un ID de mensaje de Telegram específico

• off (predeterminado)
• first
• all

• las claves de sesión de tema añaden :topic:<threadId>
• las respuestas y la indicación de escritura apuntan al hilo del tema
• ruta de configuración de tema: channels.telegram.groups.<chatId>.topics.<threadId>

• los envíos de mensajes omiten message_thread_id (Telegram rechaza sendMessage(...thread_id=1))
• las acciones de escritura aún incluyen message_thread_id

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General topic → main agent
            "3": { agentId: "zu" },        // Dev topic → zu agent
            "5": { agentId: "coder" }      // Code review → coder agent
          }
        }
      }
    }
  }
}

​

Mensajes de audio

• predeterminado: comportamiento de archivo de audio
• etiqueta [[audio_as_voice]] en la respuesta del agente para forzar el envío como nota de voz
• las transcripciones entrantes de notas de voz se enmarcan como texto generado por máquina y no confiable en el contexto del agente; la detección de menciones sigue usando la transcripción sin procesar, por lo que los mensajes de voz controlados por menciones siguen funcionando.

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/voice.ogg",
  asVoice: true,
}

​

Mensajes de video

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  media: "https://example.com/video.mp4",
  asVideoNote: true,
}

​

Pegatinas

• WEBP estático: se descarga y procesa (marcador de posición <media:sticker>)
• TGS animado: se omite
• WEBM de video: se omite

• Sticker.emoji
• Sticker.setName
• Sticker.fileId
• Sticker.fileUniqueId
• Sticker.cachedDescription

• ~/.openclaw/telegram/sticker-cache.json

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

{
  action: "sticker",
  channel: "telegram",
  to: "123456789",
  fileId: "CAACAgIAAxkBAAI...",
}

{
  action: "sticker-search",
  channel: "telegram",
  query: "cat waving",
  limit: 5,
}

• Telegram reaction added: 👍 by Alice (@alice) on msg 42

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

• own significa solo reacciones de usuarios a mensajes enviados por el bot (mejor esfuerzo mediante la caché de mensajes enviados).
• Los eventos de reacción siguen respetando los controles de acceso de Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); los remitentes no autorizados se descartan.
• Telegram no proporciona IDs de hilo en las actualizaciones de reacción.
  • los grupos que no son de foro se enrutan a la sesión de chat del grupo
  • los grupos de foro se enrutan a la sesión del tema general del grupo (:topic:1), no al tema de origen exacto

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• respaldo de emoji de identidad del agente (agents.list[].identity.emoji; si no existe, ”👀”)

• Telegram espera emoji unicode (por ejemplo, ”👀”).
• Usa "" para deshabilitar la reacción para un canal o cuenta.

• eventos de migración de grupo (migrate_to_chat_id) para actualizar channels.telegram.groups
• /config set y /config unset (requiere habilitación de comandos)

{
  channels: {
    telegram: {
      configWrites: false,
    },
  },
}

• El valor predeterminado de channels.telegram.textChunkLimit es 4000.
• channels.telegram.chunkMode="newline" prefiere límites de párrafo (líneas en blanco) antes de dividir por longitud.
• channels.telegram.mediaMaxMb (predeterminado 100) limita el tamaño de los medios entrantes y salientes de Telegram.
• channels.telegram.mediaGroupFlushMs (predeterminado 500) controla cuánto tiempo se almacenan en búfer los álbumes/grupos de medios de Telegram antes de que OpenClaw los despache como un único mensaje entrante. Auméntalo si las partes del álbum llegan tarde; redúcelo para disminuir la latencia de respuesta del álbum.
• channels.telegram.timeoutSeconds anula el tiempo de espera del cliente de la API de Telegram (si no se establece, se aplica el valor predeterminado de grammY). Los clientes bot limitan los valores configurados por debajo del guarda de solicitudes salientes de texto/escritura de 60 segundos para que grammY no aborte la entrega de respuestas visibles antes de que el guarda de transporte y el respaldo de OpenClaw puedan ejecutarse. El sondeo largo sigue usando un guarda de solicitud getUpdates de 45 segundos para que los sondeos inactivos no se abandonen indefinidamente.
• channels.telegram.pollingStallThresholdMs tiene como valor predeterminado 120000; ajústalo entre 30000 y 600000 solo para reinicios por estancamiento de sondeo falsos positivos.
• el historial de contexto de grupo usa channels.telegram.historyLimit o messages.groupChat.historyLimit (predeterminado 50); 0 lo deshabilita.
• el contexto complementario de respuesta/cita/reenvío se normaliza en una única ventana de contexto de conversación seleccionada cuando el Gateway ha observado los mensajes principales; la caché de mensajes observados se conserva junto al almacén de sesiones. Telegram solo incluye un reply_to_message superficial en las actualizaciones, por lo que las cadenas más antiguas que la caché quedan limitadas a la carga de actualización actual de Telegram.
• Las listas de permitidos de Telegram principalmente controlan quién puede activar el agente, no son un límite completo de redacción de contexto complementario.
• Controles de historial de DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• la configuración channels.telegram.retry se aplica a los auxiliares de envío de Telegram (CLI/herramientas/acciones) para errores recuperables de la API saliente. La entrega de respuesta final entrante también usa un reintento de envío seguro acotado para fallos de preconexión de Telegram, pero no reintenta sobres de red ambiguos posteriores al envío que podrían duplicar mensajes visibles.

openclaw message send --channel telegram --target 123456789 --message "hi"
openclaw message send --channel telegram --target @name --message "hi"
openclaw message send --channel telegram --target -1001234567890:topic:42 --message "hi topic"

openclaw message poll --channel telegram --target 123456789 \
  --poll-question "Ship it?" --poll-option "Yes" --poll-option "No"
openclaw message poll --channel telegram --target -1001234567890:topic:42 \
  --poll-question "Pick a time" --poll-option "10am" --poll-option "2pm" \
  --poll-duration-seconds 300 --poll-public

• --poll-duration-seconds (5-600)
• --poll-anonymous
• --poll-public
• --thread-id para temas de foro (o usa un destino :topic:)

• --presentation con bloques buttons para teclados en línea cuando channels.telegram.capabilities.inlineButtons lo permite
• --pin o --delivery '{"pin":true}' para solicitar entrega fijada cuando el bot pueda fijar en ese chat
• --force-document para enviar imágenes, GIF y videos salientes como documentos en lugar de cargas comprimidas de foto, medios animados o video

• channels.telegram.actions.sendMessage=false deshabilita los mensajes salientes de Telegram, incluidas las encuestas
• channels.telegram.actions.poll=false deshabilita la creación de encuestas de Telegram mientras deja habilitados los envíos normales

• channels.telegram.execApprovals.enabled (se habilita automáticamente cuando al menos un aprobador se puede resolver)
• channels.telegram.execApprovals.approvers (recurre a IDs numéricos de propietarios de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (predeterminado) | channel | both
• agentFilter, sessionFilter

• Si requireMention=false, el modo de privacidad de Telegram debe permitir visibilidad completa.
  • BotFather: /setprivacy -> Disable
  • luego elimina y vuelve a añadir el bot al grupo
• openclaw channels status advierte cuando la configuración espera mensajes de grupo sin mención.
• openclaw channels status --probe puede comprobar ID de grupo numéricos explícitos; el comodín "*" no se puede comprobar mediante sondeo de membresía.
• prueba rápida de sesión: /activation always.

• cuando existe channels.telegram.groups, el grupo debe estar listado (o incluir "*")
• verifica la membresía del bot en el grupo
• revisa los registros: openclaw logs --follow para conocer los motivos de omisión

• autoriza tu identidad de remitente (emparejamiento y/o allowFrom numérico)
• la autorización de comandos sigue aplicándose incluso cuando la política del grupo es open
• setMyCommands failed con BOT_COMMANDS_TOO_MUCH significa que el menú nativo tiene demasiadas entradas; reduce los comandos de plugins/Skills/personalizados o desactiva los menús nativos
• las llamadas de inicio deleteMyCommands / setMyCommands y las llamadas de escritura sendChatAction están acotadas y reintentan una vez mediante la reserva de transporte de Telegram cuando se agota el tiempo de espera de la solicitud. Los errores persistentes de red/fetch suelen indicar problemas de alcance DNS/HTTPS hacia api.telegram.org

• getMe returned 401 es un fallo de autenticación de Telegram para el token de bot configurado.
• Vuelve a copiar o regenerar el token del bot en BotFather y luego actualiza channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken o TELEGRAM_BOT_TOKEN para la cuenta predeterminada.
• deleteWebhook 401 Unauthorized durante el inicio también es un fallo de autenticación; tratarlo como “no existe ningún Webhook” solo aplazaría el mismo fallo de token incorrecto a llamadas de API posteriores.

• Node 22+ + fetch/proxy personalizado puede activar comportamiento de cancelación inmediata si los tipos de AbortSignal no coinciden.
• Algunos hosts resuelven api.telegram.org primero a IPv6; una salida IPv6 defectuosa puede causar fallos intermitentes de la API de Telegram.
• Si los registros incluyen TypeError: fetch failed o Network request for 'getUpdates' failed!, OpenClaw ahora reintenta estos casos como errores de red recuperables.
• Durante el inicio del sondeo, OpenClaw reutiliza la comprobación getMe de inicio correcta para grammY, de modo que el ejecutor no necesite un segundo getMe antes del primer getUpdates.
• Si deleteWebhook falla con un error de red transitorio durante el inicio del sondeo, OpenClaw continúa con sondeo largo en lugar de hacer otra llamada de plano de control previa al sondeo. Un Webhook aún activo aparece como un conflicto de getUpdates; entonces OpenClaw reconstruye el transporte de Telegram y reintenta la limpieza del Webhook.
• Si los sockets de Telegram se reciclan con una cadencia fija corta, comprueba si channels.telegram.timeoutSeconds es bajo; los clientes de bot limitan los valores configurados por debajo de las protecciones de solicitudes salientes y getUpdates, pero las versiones anteriores podían abortar cada sondeo o respuesta cuando esto se establecía por debajo de esas protecciones.
• Si los registros incluyen Polling stall detected, OpenClaw reinicia el sondeo y reconstruye el transporte de Telegram tras 120 segundos sin actividad de sondeo largo completada de forma predeterminada.
• openclaw channels status --probe y openclaw doctor advierten cuando una cuenta de sondeo en ejecución no ha completado getUpdates tras el margen de inicio, cuando una cuenta de Webhook en ejecución no ha completado setWebhook tras el margen de inicio, o cuando la última actividad correcta del transporte de sondeo está obsoleta.
• Aumenta channels.telegram.pollingStallThresholdMs solo cuando las llamadas getUpdates de larga duración están sanas, pero tu host aún informa reinicios falsos por sondeo detenido. Las detenciones persistentes suelen apuntar a problemas de proxy, DNS, IPv6 o salida TLS entre el host y api.telegram.org.
• Telegram también respeta las variables de entorno de proxy del proceso para el transporte de la API de bot, incluidas HTTP_PROXY, HTTPS_PROXY, ALL_PROXY y sus variantes en minúsculas. NO_PROXY / no_proxy aún pueden omitir api.telegram.org.
• Si el proxy gestionado de OpenClaw se configura mediante OPENCLAW_PROXY_URL para un entorno de servicio y no hay variables de entorno de proxy estándar presentes, Telegram también usa esa URL para el transporte de la API de bot.
• En hosts VPS con salida directa/TLS inestable, enruta las llamadas de API de Telegram mediante channels.telegram.proxy:

channels:
  telegram:
    proxy: socks5://<user>:<password>@proxy-host:1080

• Node 22+ usa autoSelectFamily=true de forma predeterminada (excepto WSL2). El orden de resultados DNS de Telegram respeta OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, luego channels.telegram.network.dnsResultOrder, luego el valor predeterminado del proceso como NODE_OPTIONS=--dns-result-order=ipv4first; si no aplica ninguno, Node 22+ recurre a ipv4first.
• Si tu host es WSL2 o funciona explícitamente mejor con comportamiento solo IPv4, fuerza la selección de familia:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Las respuestas del rango de referencia RFC 2544 (198.18.0.0/15) ya están permitidas para descargas de medios de Telegram de forma predeterminada. Si un proxy fake-IP de confianza o transparente reescribe api.telegram.org a alguna otra dirección privada/interna/de uso especial durante descargas de medios, puedes optar por la omisión solo para Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• La misma opción está disponible por cuenta en channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Si tu proxy resuelve hosts de medios de Telegram en 198.18.x.x, deja primero desactivada la marca peligrosa. Los medios de Telegram ya permiten el rango de referencia RFC 2544 de forma predeterminada.

• Anulaciones de entorno (temporales):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Valida las respuestas DNS:

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