Telegram (Bot API)

Los bots de Telegram usan por defecto el **Modo de privacidad**, que limita qué mensajes de grupo reciben.

Si el bot debe ver todos los mensajes del grupo, puedes:

- desactivar el modo de privacidad vía `/setprivacy`, o
- hacer al bot administrador del grupo.

Al cambiar el modo de privacidad, elimina y vuelve a añadir el bot en cada grupo para que Telegram aplique el cambio.

El estado de administrador se controla en la configuración del grupo de Telegram.

Los bots administradores reciben todos los mensajes del grupo, lo cual es útil para comportamiento siempre activo en grupos.

- `/setjoingroups` para permitir/denegar añadir a grupos
- `/setprivacy` para el comportamiento de visibilidad en grupos

OpenClaw puede transmitir respuestas parciales en tiempo real:

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

Requisito:

- `channels.telegram.streaming` es `off | partial | block | progress` (por defecto: `partial`)
- `progress` se mapea a `partial` en Telegram (compat con nombres entre canales)
- `channels.telegram.streamMode` legacy y valores boolean `streaming` se auto-mapean

Para respuestas solo de texto:

- MD: OpenClaw mantiene el mismo mensaje de vista previa y realiza una edición final en su lugar (sin segundo mensaje)
- grupo/tema: OpenClaw mantiene el mismo mensaje de vista previa y realiza una edición final en su lugar (sin segundo mensaje)

Para respuestas complejas (p. ej., payloads de medios), OpenClaw recurre a la entrega final normal y luego limpia el mensaje de vista previa.

La transmisión de vista previa es separada de la transmisión por bloques. Cuando la transmisión por bloques está habilitada explícitamente para Telegram, OpenClaw omite la transmisión de vista previa para evitar doble transmisión.

Si el transporte nativo de borrador no está disponible/es rechazado, OpenClaw recurre automáticamente a `sendMessage` + `editMessageText`.

Stream de razonamiento exclusivo de Telegram:

- `/reasoning stream` envía el razonamiento a la vista previa en vivo mientras genera
- la respuesta final se envía sin texto de razonamiento

El texto saliente usa `parse_mode: "HTML"` de Telegram.

- El texto tipo Markdown se renderiza a HTML seguro para Telegram.
- El HTML sin procesar del modelo se escapa para reducir fallos de parseo de Telegram.
- Si Telegram rechaza el HTML parseado, OpenClaw reintenta como texto plano.

Las vistas previas de enlaces están activadas por defecto y pueden desactivarse con `channels.telegram.linkPreview: false`.

El registro del menú de comandos de Telegram se maneja al iniciar con `setMyCommands`.

Valores predeterminados de comandos nativos:

- `commands.native: "auto"` activa los comandos nativos para Telegram

Añade entradas de menú de comandos personalizados:

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

Reglas:

- los nombres se normalizan (eliminar `/` 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 registran

Configura el alcance del teclado inline:

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

Alcances:

- `off`
- `dm`
- `group`
- `all`
- `allowlist` (predeterminado)

Legacy `capabilities: ["inlineButtons"]` se mapea a `inlineButtons: "all"`.

Ejemplo de acción de mensaje:

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

Los clics de callback se pasan al agente como texto:
`callback_data: <value>`

Las acciones de herramienta de Telegram incluyen:

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

Las acciones de mensajes del canal exponen aliases ergonómicos (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).

Controles de puertas:

- `channels.telegram.actions.sendMessage`
- `channels.telegram.actions.deleteMessage`
- `channels.telegram.actions.reactions`
- `channels.telegram.actions.sticker` (por defecto: desactivado)

Telegram admite etiquetas de hilos de respuesta explícitas en la salida generada:

- `[[reply_to_current]]` responde al mensaje que lo activó
- `[[reply_to:<id>]]` responde a un ID de mensaje específico de Telegram

`channels.telegram.replyToMode` controla el manejo:

- `off` (predeterminado)
- `first`
- `all`

Nota: `off` desactiva el hilo de respuesta implícito. Las etiquetas explícitas `[[reply_to_*]]` se respetan igualmente.

Supergrupos de foro:

- las claves de sesión de tema añaden `:topic:<threadId>`
- las respuestas y escritura se dirigen al hilo del tema
- ruta de configuración de tema:
  `channels.telegram.groups.<chatId>.topics.<threadId>`

Caso especial del tema general (`threadId=1`):

- los envíos de mensajes omiten `message_thread_id` (Telegram rechaza `sendMessage(...thread_id=1)`)
- las acciones de escritura sí incluyen `message_thread_id`

Herencia de tema: las entradas de tema heredan la configuración del grupo a menos que se sobrescriban (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
`agentId` es solo de tema y no hereda de los valores predeterminados del grupo.

**Enrutamiento de agente por tema**: cada tema puede enrutarse a un agente diferente estableciendo `agentId` en la configuración del tema. Esto le da a cada tema su propio espacio de trabajo, memoria y sesión aislados.

### Mensajes de audio

Telegram distingue notas de voz de archivos de audio.

- por defecto: comportamiento de archivo de audio
- etiqueta `[[audio_as_voice]]` en la respuesta del agente para forzar envío como nota de voz

### Mensajes de video

Telegram distingue archivos de video de notas de video.

Las notas de video no admiten subtítulos; el texto proporcionado se envía por separado.

### Stickers

Manejo de stickers entrantes:

- WEBP estático: descargado y procesado (placeholder `<media:sticker>`)
- TGS animado: omitido
- WEBM de video: omitido

Activa acciones de sticker:

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

Las reacciones de Telegram llegan como actualizaciones `message_reaction` (separadas de los payloads de mensajes).

Configuración:

- `channels.telegram.reactionNotifications`: `off | own | all` (por defecto: `own`)
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (por defecto: `minimal`)

Por defecto: long polling.

Modo webhook:

- establece `channels.telegram.webhookUrl`
- establece `channels.telegram.webhookSecret` (obligatorio cuando se establece la URL de webhook)
- opcional `channels.telegram.webhookPath` (por defecto `/telegram-webhook`)
- opcional `channels.telegram.webhookHost` (por defecto `127.0.0.1`)
- opcional `channels.telegram.webhookPort` (por defecto `8787`)

- `channels.telegram.textChunkLimit` por defecto es 4000.
- `channels.telegram.chunkMode="newline"` prefiere límites de párrafo (líneas en blanco) antes de dividir por longitud.
- `channels.telegram.mediaMaxMb` (por defecto 100) limita el tamaño de medios entrantes y salientes de Telegram.
- el historial de contexto de grupo usa `channels.telegram.historyLimit` o `messages.groupChat.historyLimit` (por defecto 50); `0` desactiva.

El destino de envío CLI puede ser ID numérico de chat o username:

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

Telegram admite aprobaciones de ejecución en mensajes directos del aprobador y puede opcionalmente publicar solicitudes de aprobación en el chat o tema de origen.

Ruta de configuración:

- `channels.telegram.execApprovals.enabled`
- `channels.telegram.execApprovals.approvers`
- `channels.telegram.execApprovals.target` (`dm` | `channel` | `both`, por defecto: `dm`)

Los aprobadores deben ser IDs numéricos de usuario de Telegram.

Documentación relacionada: [Aprobaciones de ejecución](/docs/tools/exec-approvals)

- Si `requireMention=false`, el modo de privacidad de Telegram debe permitir visibilidad completa.
  - BotFather: `/setprivacy` -> Disable
  - luego elimina + vuelve a añadir el bot al grupo
- `openclaw channels status` advierte cuando la configuración espera mensajes de grupo sin mención.
- verificación rápida de sesión: `/activation always`.

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

- autoriza tu identidad de remitente (emparejamiento y/o `allowFrom` numérico)
- la autorización de comandos sigue aplicando incluso cuando la política de grupo es `open`

- Node 22+ + fetch/proxy personalizado puede activar comportamiento de abort inmediato si los tipos de AbortSignal no coinciden.
- Algunos hosts resuelven `api.telegram.org` a IPv6 primero; el egreso IPv6 roto puede causar fallos intermitentes en la API de Telegram.
- En hosts VPS con egreso/TLS directo inestable, enruta las llamadas a la API de Telegram a través de `channels.telegram.proxy`:

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