Telegram

Status: Production-ready. Supports bot DM and group chat via grammY. Uses long-polling by default; also supports webhook.

1. Create a bot with ''@BotFather'' (''direct link''). Make sure the handle is ''@BotFather'', then copy the bot token.

2. Configure token:

- Environment variable: ''TELEGRAM_BOT_TOKEN=...''

- Or config: ''channels.telegram.botToken: "..."''.

- When both are set, config takes precedence (env only serves as default account fallback).

3. Start Gateway.

4. DM enables pairing by default; first contact receives a pairing code, messages are processed only after approval.

Minimum config:

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

- Canal de Telegram Bot API gestionado por el Gateway.

- Enrutamiento determinista: las respuestas solo van de vuelta a Telegram, el modelo no elige el canal.

- DM usa la sesión principal del agente por defecto; los chats de grupo se aíslan como ''agent:<agentId>:telegram:group:<chatId>''.

#

1. Abre Telegram, chatea con ''@BotFather'' (''enlace directo''), confirma que el handle es ''@BotFather''.

2. Ejecuta ''/newbot'', sigue las indicaciones (nombre + username terminando en ''bot'').

3. Copia el token y guárdalo de forma segura.

Configuraciones opcionales:

- ''/setjoingroups'' — permitir/prohibir que el bot se una a grupos

- ''/setprivacy'' — controlar si el bot puede ver todos los mensajes del grupo

Configuraciones opcionales:

- ''/setjoingroups'' — permitir/prohibir que el bot se una a grupos

- ''/setprivacy'' — controlar si el bot puede ver todos los mensajes del grupo

#

Ejemplo:

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

Variable de entorno: ''TELEGRAM_BOT_TOKEN=...'' (solo afecta la cuenta predeterminada). Cuando tanto env como config existen, config tiene precedencia.

Multi-cuenta: Usa ''channels.telegram.accounts'' para configurar el token de cada cuenta (opcional ''name''). Para estructura compartida, ver ''/gateway/configuration''.

3. Inicia el Gateway: el canal de Telegram inicia cuando el token es resoluble (prioridad config, fallback env).

4. DM usa emparejamiento por defecto: el primer contacto da un código de emparejamiento, los mensajes se procesan solo después de la aprobación.

5. Chat de grupo: agrega el bot al grupo; decide la política de privacidad/admin en BotFather (ver abajo); luego usa ''channels.telegram.groups'' para controlar el gating de mención y allowlist.

#

- ''/newbot'' crea el bot y retorna el token (mantenlo secreto).

- Si se filtra, revoca/resetea el token en @BotFather y actualiza tu config.

#

El bot de Telegram habilita Modo Privacidad por defecto, que limita el rango de mensajes de grupo que puede recibir. Si necesitas que el bot vea todos los mensajes en un grupo, hay dos formas:

- Usa ''/setprivacy'' para deshabilitar el modo privacidad, ''o''

- Establece el bot como admin del grupo (los bots admin pueden recibir todos los mensajes).

Nota: Después de cambiar el modo privacidad, necesitas remover el bot del grupo y volver a agregarlo para que los cambios surtan efecto.

#

Los permisos de admin se establecen en el UI del grupo. Los bots admin reciben todos los mensajes del grupo; solo haz esto cuando realmente necesites "visibilidad completa".

- Los mensajes entrantes se normalizan a un sobre de canal genérico (incluyendo contexto de respuesta y placeholders de media).

- El chat de grupo requiere mención para responder por defecto (@mención nativa o coincidencia con ''agents.list[].groupChat.mentionPatterns'' / ''messages.groupChat.mentionPatterns'').

- Con múltiples agentes, puedes anular por agente en ''agents.list[].groupChat.mentionPatterns''.

- Las respuestas siempre van de vuelta al chat de Telegram que las disparó.

- long-polling usa grammY runner y procesa secuencialmente por chat; la concurrencia general está limitada por ''agents.defaults.maxConcurrent''.

- Telegram Bot API no tiene confirmaciones de lectura, así que no hay ''sendReadReceipts''.

OpenClaw puede usar ''sendMessageDraft'' para transmitir actualizaciones parciales en DM de Telegram.

Requisitos:

- Habilitar Modo Hilos (modo tema de foro) para el bot en @BotFather.

- Solo hilos DM (Telegram incluye ''message_thread_id'' en mensajes entrantes).

- ''channels.telegram.streamMode'' no es ''"off"'' (predeterminado ''"partial"''; ''"block"'' hace actualizaciones de borrador por chunks).

El streaming de borrador solo soporta DM; Telegram no soporta este mecanismo en grupos/canales.

- El texto saliente de Telegram usa ''parse_mode: "HTML"'' (subconjunto de tags soportados por Telegram).

- La entrada tipo Markdown se renderiza como HTML seguro para Telegram (negrita/cursiva/tachado/código/enlaces); los elementos de nivel bloque se aplanan a texto con saltos de línea/viñetas.

- El HTML crudo del modelo se escapa para evitar errores de parse de Telegram.

- Si Telegram rechaza el payload HTML, OpenClaw reintenta el mismo mensaje con texto plano.

OpenClaw registra comandos nativos en el menú del bot de Telegram al inicio (como ''/status'', ''/reset'', ''/model'').

También puedes agregar comandos personalizados al menú vía config:

Notas:

- Los comandos personalizados son solo entradas de menú; OpenClaw no los implementará automáticamente a menos que los manejes en otro lugar.

- Los nombres de comandos se normalizan (remover ''/'' inicial, minúsculas), solo pueden contener ''a-z'', ''0-9'', ''_'' (longitud 1–32).

- Los comandos personalizados no pueden anular comandos nativos; los conflictos se ignoran y loggean.

- Si ''commands.native'' está deshabilitado, solo se registran comandos personalizados (o el menú se limpia si no hay comandos personalizados).

- ''setMyCommands failed'' en logs usualmente significa que HTTPS/DNS saliente a ''api.telegram.org'' está bloqueado.

- Al ver fallos de ''sendMessage'' o ''sendChatAction'', prioriza verificar enrutamiento IPv6 y DNS.

Más: ''/channels/troubleshooting''.

- El texto saliente se fragmenta por ''channels.telegram.textChunkLimit'' (predeterminado 4000).

- Fragmentación opcional por líneas en blanco primero: ''channels.telegram.chunkMode="newline"'' (límites de párrafo) luego por longitud.

- Límite de descarga/subida de media: ''channels.telegram.mediaMaxMb'' (predeterminado 5MB).

- Timeout de solicitud Telegram Bot API: ''channels.telegram.timeoutSeconds'' (predeterminado 500, grammY). Recomendamos establecer menor para evitar esperas largas.

- Contexto de historial de grupo: ''channels.telegram.historyLimit'' (o ''channels.telegram.accounts.*.historyLimit''), recurre a ''messages.groupChat.historyLimit''. Establece en ''0'' para deshabilitar (predeterminado 50).

- Límite de historial DM: ''channels.telegram.dmHistoryLimit'' (contado por turnos de usuario). Anular por usuario: ''channels.telegram.dms["''"].historyLimit''.

Por defecto, el bot solo responde en grupos cuando es mencionado (''@botname'' o coincidencia con ''agents.list[].groupChat.mentionPatterns''). Para ajustar comportamiento:

#

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // This group always responds
      },
    },
  },
}

''Importante:'' Una vez que ''channels.telegram.groups'' está establecido, se convierte en ''allowlist de grupos'': solo grupos listados (o ''"*"'') son aceptados.

Los temas de foro heredan la config del grupo padre (allowFrom, requireMention, skills, prompts) por defecto, a menos que escribas anulaciones a nivel de tema en ''channels.telegram.groups.''.topics.''''.

Permitir todos los grupos y siempre responder:

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

Mantener todos los grupos requiriendo mención (comportamiento predeterminado):

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true }, // Or omit groups entirely
      },
    },
  },
}

#

Enviar en grupo:

- ''/activation always'' — responder a todos los mensajes

- ''/activation mention'' — requerir mención (predeterminado)

Nota: Este comando solo cambia estado de sesión. Para persistir comportamiento después de reinicio, usa config.

#

Reenvía cualquier mensaje del grupo a ''@userinfobot'' o ''@getidsbot'' para ver el ID del chat (usualmente un número negativo como ''-1001234567890'').

Nota de privacidad: ''@userinfobot'' es un bot de terceros. Si no quieres usar terceros, agrega el bot al grupo, envía un mensaje, luego usa ''openclaw logs --follow'' para leer ''chat.id'', o usa ''getUpdates'' de Bot API.

Por defecto, Telegram permite actualizaciones de config disparadas por eventos de canal o ''/config set|unset'' ser escritas de vuelta al archivo de config.

Escenarios típicos:

- Grupo actualizado a supergrupo, Telegram emite ''migrate_to_chat_id'' (el ID del chat cambia); OpenClaw puede migrar automáticamente ''channels.telegram.groups''.

- Ejecutas ''/config set'' o ''/config unset'' en chat de Telegram (requiere ''commands.config: true'').

Deshabilitar:

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

Los temas de foro de Telegram llevan ''message_thread_id'' con cada mensaje. OpenClaw:

Telegram soporta teclado inline (botones de callback).

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

Config por cuenta:

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

Ámbitos:

- ''off'' — deshabilitado

- ''dm'' — solo DM (objetivos de grupo bloqueados)

- ''group'' — solo grupo (objetivos DM bloqueados)

- ''all'' — DM + grupo

- ''allowlist'' — DM + grupo, pero solo permite remitentes permitidos por ''allowFrom''/''groupAllowFrom'' (consistente con comandos de control)

Predeterminado: ''allowlist''. Sintaxis antigua: ''capabilities: ["inlineButtons"]'' equivale a ''inlineButtons: "all"''.

#

Usa la herramienta de mensaje para pasar parámetro ''buttons'':

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

Después de que el usuario hace clic en el botón, los datos de callback se envían de vuelta al agente como mensaje:

''callback_data: value''

#

Las capacidades de Telegram pueden configurarse en dos niveles (el ejemplo arriba usa forma de objeto; el array de strings antiguo todavía es soportado):

- ''channels.telegram.capabilities'': predeterminado global, aplicado a todas las cuentas de Telegram (a menos que se anule)

- ''channels.telegram.accounts.''.capabilities'': anulación por cuenta

#

ChannelsTelegramPage.step26.p1

ChannelsTelegramPage.step26.p2

ChannelsTelegramPage.step26.p3

ChannelsTelegramPage.step26.p4

ChannelsTelegramPage.step26.p5

ChannelsTelegramPage.step26.p6

#

Más seguro (sin dependencia de bot de terceros):

1. Inicia el gateway, envía un DM a tu bot.

2. Ejecuta ''openclaw logs --follow'', encuentra ''from.id''.

Bot API Oficial (más directo):

1. Envía DM al bot.

2. Usa el token para llamar ''getUpdates'' y leer ''message.from.id'':

''''`bash", "p8": "curl "https://api.telegram.org/bot''/getUpdates"", "p9": "''''`

curl "https://api.telegram.org/bot''/getUpdates"

''''`

Terceros (menos privacidad):

- DM ''@userinfobot'' o ''@getidsbot''.

#

El chat grupal tiene dos controles independientes:

''1) Qué grupos permitir'' (''channels.telegram.groups'' como allowlist de grupos):

- No escribas ''groups'': permitir todos los grupos

- Escribe ''groups'': solo permitir grupos listados o ''"*"''

- Ejemplo: "groups": { "-1001234567890": {'}, "*": {'} }' significa permitir todos los grupos (mientras escribes anulaciones para grupos específicos)

''2) Qué remitentes permitir'' (''channels.telegram.groupPolicy'' controla el filtrado de remitentes de grupo):

- ''"open"'': permitir todos los remitentes en el grupo

- ''"allowlist"'': solo permitir remitentes en ''channels.telegram.groupAllowFrom''

- ''"disabled"'': rechazar completamente mensajes de grupo

Predeterminado es ''groupPolicy: "allowlist"'' (ej., bloquear por defecto cuando ''groupAllowFrom'' no está configurado)

La mayoría de usuarios quieren: ''groupPolicy: "allowlist"'' + ''groupAllowFrom'' + listar grupos permitidos en ''channels.telegram.groups''.

- Predeterminado: long-polling (no se necesita URL pública).

- Webhook: establece ''channels.telegram.webhookUrl'' y ''channels.telegram.webhookSecret'' (opcional ''channels.telegram.webhookPath'').

- La escucha local vincula ''0.0.0.0:8787'' por defecto, path predeterminado ''POST /telegram-webhook''.

- Si tu URL pública es diferente, usa proxy inverso y apunta ''channels.telegram.webhookUrl'' al endpoint público.

Telegram soporta capacidad opcional de "responder al mensaje disparador" (basado en tags):

- ''[[reply_to_current]]'' — responder al mensaje disparador

- ''[[reply_to:'']]'' — responder al id de mensaje especificado

Controla vía ''channels.telegram.replyToMode'':

- ''first'' (predeterminado), ''all'', ''off''.

Telegram distingue notas de voz (burbuja redonda) de archivos de audio (con tarjeta de metadatos). Para compatibilidad con comportamiento antiguo, OpenClaw envía archivos de audio por defecto.

Para forzar envío de notas de voz en respuestas del agente, agrega en cualquier lugar de la respuesta:

- ''[[audio_as_voice]]'' — enviar audio como nota de voz

Este tag no aparecerá en el texto final entregado; otros canales lo ignoran.

Usa la herramienta de mensaje para enviar nota de voz: establece ''asVoice: true'' y proporciona URL de audio compatible con voz ''media'' (puedes omitir ''message''):

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