Telegram

• desative o modo de privacidade via /setprivacy, ou
• torne o bot administrador do grupo.

• /setjoingroups para permitir/negar adições a grupos
• /setprivacy para comportamento de visibilidade em grupo

• chats diretos: mensagem de prévia + editMessageText
• grupos/tópicos: mensagem de prévia + editMessageText

• channels.telegram.streaming é off | partial | block | progress (padrão: partial)
• prévias curtas da resposta inicial são debounced e então materializadas após um atraso limitado se a execução ainda estiver ativa
• progress mantém um rascunho de status editável para progresso de ferramentas, mostra o rótulo de status estável quando atividade de resposta chega antes do progresso de ferramenta, limpa-o na conclusão e envia a resposta final como uma mensagem normal
• streaming.preview.toolProgress controla se atualizações de ferramenta/progresso reutilizam a mesma mensagem de prévia editada (padrão: true quando streaming de prévia está ativo)
• streaming.preview.commandText controla detalhes de comando/execução dentro dessas linhas de progresso de ferramenta: raw (padrão, preserva o comportamento lançado) ou status (somente rótulo da ferramenta)
• streaming.progress.commentary (padrão: false) opta por incluir texto de comentário/preâmbulo do assistente no rascunho temporário de progresso
• channels.telegram.streamMode legado, valores booleanos de streaming e chaves aposentadas de prévia de rascunho nativa são detectados; execute openclaw doctor --fix para migrá-los para a configuração de streaming atual

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

• prévias curtas de DM/grupo/tópico: o OpenClaw mantém a mesma mensagem de prévia e realiza a edição final no lugar
• finais de texto longos que são divididos em várias mensagens do Telegram reutilizam a prévia existente como o primeiro trecho final quando possível, depois enviam apenas os trechos restantes
• finais em modo de progresso limpam o rascunho de status e usam entrega final normal em vez de editar o rascunho para virar a resposta
• se a edição final falhar antes de o texto concluído ser confirmado, o OpenClaw usa entrega final normal e limpa a prévia obsoleta

• /reasoning stream usa o caminho de prévia de raciocínio de um canal compatível; no Telegram, ele transmite o raciocínio para a prévia ao vivo durante a geração
• a prévia de raciocínio é excluída após a entrega final; use /reasoning on quando o raciocínio deve permanecer visível
• a resposta final é enviada sem texto de raciocínio

{
  channels: {
    telegram: {
      richMessages: true,
    },
  },
}

• O agente é informado de que mensagens ricas do Telegram estão disponíveis para este bot/conta.
• Texto Markdown é renderizado pelo IR de Markdown do OpenClaw e enviado como HTML rico do Telegram.
• Payloads HTML ricos explícitos preservam tags compatíveis da Bot API 10.1, como cabeçalhos, tabelas, detalhes, mídia rica e fórmulas.
• Legendas de mídia ainda usam legendas HTML do Telegram porque mensagens ricas não substituem legendas.

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

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

• nomes são normalizados (remove / inicial, converte para minúsculas)
• padrão válido: a-z, 0-9, _, comprimento 1..32
• comandos personalizados não podem substituir comandos nativos
• conflitos/duplicatas são ignorados e registrados em log

• comandos personalizados são apenas entradas de menu; eles não implementam comportamento automaticamente
• comandos de Plugin/Skills ainda podem funcionar quando digitados, mesmo se não forem mostrados no menu do Telegram

• setMyCommands failed com BOT_COMMANDS_TOO_MUCH significa que o menu do Telegram ainda excedeu o limite após o corte; reduza comandos de Plugin/Skills/personalizados ou desabilite channels.telegram.commands.native.
• Falha em deleteWebhook, deleteMyCommands ou setMyCommands com 404: Not Found enquanto comandos curl diretos da Bot API funcionam pode significar que channels.telegram.apiRoot foi definido para o endpoint completo /bot<TOKEN>. apiRoot deve ser apenas a raiz da Bot API, e openclaw doctor --fix remove um /bot<TOKEN> final acidental.
• getMe returned 401 significa que o Telegram rejeitou o token de bot configurado. Atualize botToken, tokenFile ou TELEGRAM_BOT_TOKEN com o token atual do BotFather; o OpenClaw para antes do polling, então isso não é relatado como falha de limpeza de Webhook.
• setMyCommands failed com erros de rede/fetch geralmente significa que DNS/HTTPS de saída para api.telegram.org está bloqueado.

​

Comandos de pareamento de dispositivo (Plugin device-pair)

1. /pair gera código de configuração
2. cole o código no app iOS
3. /pair pending lista solicitações pendentes (incluindo função/escopos)
4. aprove a solicitação:
   • /pair approve <requestId> para aprovação explícita
   • /pair approve quando houver apenas uma solicitação pendente
   • /pair approve latest para a mais recente

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

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

• off
• dm
• group
• all
• allowlist (padrão)

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

{
  action: "send",
  channel: "telegram",
  to: "123456789",
  message: "Open app:",
  presentation: {
    blocks: [
      {
        type: "buttons",
        buttons: [{ label: "Launch", web_app: { url: "https://example.com/app" } }],
      },
    ],
  },
}

• sendMessage (to, content, mediaUrl opcional, replyToMessageId, messageThreadId)
• react (chatId, messageId, emoji)
• deleteMessage (chatId, messageId)
• editMessage (chatId, messageId, content ou caption, botões inline presentation opcionais; edições apenas de botões atualizam a marcação de resposta)
• createForumTopic (chatId, name, iconColor opcional, iconCustomEmojiId)

• channels.telegram.actions.sendMessage
• channels.telegram.actions.deleteMessage
• channels.telegram.actions.reactions
• channels.telegram.actions.sticker (padrão: desativado)

• [[reply_to_current]] responde à mensagem acionadora
• [[reply_to:<id>]] responde a um ID de mensagem específico do Telegram

• off (padrão)
• first
• all

• chaves de sessão de tópico acrescentam :topic:<threadId>
• respostas e digitação têm como alvo a thread do tópico
• caminho de configuração do tópico: channels.telegram.groups.<chatId>.topics.<threadId>

• envios de mensagem omitem message_thread_id (o Telegram rejeita sendMessage(...thread_id=1))
• ações de digitação ainda incluem 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
          }
        }
      }
    }
  }
}

​

Mensagens de áudio

• padrão: comportamento de arquivo de áudio
• tag [[audio_as_voice]] na resposta do agente para forçar envio como nota de voz
• transcrições de notas de voz recebidas são enquadradas como texto gerado por máquina, não confiável no contexto do agente; a detecção de menções ainda usa a transcrição bruta, então mensagens de voz controladas por menção continuam funcionando.

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

​

Mensagens de vídeo

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

​

Figurinhas

• WEBP estático: baixado e processado (placeholder <media:sticker>)
• TGS animado: ignorado
• WEBM de vídeo: ignorado

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

{
  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 (padrão: own)
• channels.telegram.reactionLevel: off | ack | minimal | extensive (padrão: minimal)

• own significa apenas reações do usuário a mensagens enviadas pelo bot (melhor esforço via cache de mensagens enviadas).
• Eventos de reação ainda respeitam os controles de acesso do Telegram (dmPolicy, allowFrom, groupPolicy, groupAllowFrom); remetentes não autorizados são descartados.
• O Telegram não fornece IDs de thread em atualizações de reação.
  • grupos que não são fóruns são roteados para a sessão de chat do grupo
  • grupos de fórum são roteados para a sessão de tópico geral do grupo (:topic:1), não para o tópico exato de origem

• channels.telegram.accounts.<accountId>.ackReaction
• channels.telegram.ackReaction
• messages.ackReaction
• fallback de emoji da identidade do agente (agents.list[].identity.emoji, caso contrário ”👀”)

• O Telegram espera emoji unicode (por exemplo, ”👀”).
• Use "" para desabilitar a reação para um canal ou conta.

• eventos de migração de grupo (migrate_to_chat_id) para atualizar channels.telegram.groups
• /config set e /config unset (exige habilitação de comando)

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

• O padrão de channels.telegram.textChunkLimit é 4000.
• channels.telegram.chunkMode="newline" prefere limites de parágrafo (linhas em branco) antes da divisão por tamanho.
• channels.telegram.mediaMaxMb (padrão 100) limita o tamanho de mídia de entrada e saída do Telegram.
• channels.telegram.mediaGroupFlushMs (padrão 500) controla por quanto tempo álbuns/grupos de mídia do Telegram ficam em buffer antes que o OpenClaw os despache como uma única mensagem de entrada. Aumente se partes do álbum chegarem tarde; reduza para diminuir a latência da resposta ao álbum.
• channels.telegram.timeoutSeconds substitui o timeout do cliente da API do Telegram (se não estiver definido, aplica-se o padrão do grammY). Clientes de bot limitam valores configurados abaixo da proteção de 60 segundos para solicitações de texto/digitação de saída, para que o grammY não aborte a entrega de respostas visíveis antes que a proteção de transporte e o fallback do OpenClaw possam executar. O long polling ainda usa uma proteção de solicitação getUpdates de 45 segundos para que polls ociosos não sejam abandonados indefinidamente.
• channels.telegram.pollingStallThresholdMs usa 120000 por padrão; ajuste entre 30000 e 600000 apenas para reinícios por polling travado falso-positivo.
• O histórico de contexto de grupos usa channels.telegram.historyLimit ou messages.groupChat.historyLimit (padrão 50); 0 desativa.
• O contexto suplementar de resposta/citação/encaminhamento é normalizado em uma única janela de contexto de conversa selecionada quando o Gateway observou as mensagens pai; o cache de mensagens observadas fica no estado de Plugin SQLite do OpenClaw, e openclaw doctor --fix importa sidecars legados. O Telegram inclui apenas um reply_to_message raso nas atualizações, então cadeias mais antigas que o cache ficam limitadas ao payload atual de atualização do Telegram.
• As allowlists do Telegram controlam principalmente quem pode acionar o agente, não um limite completo de redação de contexto suplementar.
• Controles de histórico de DM:
  • channels.telegram.dmHistoryLimit
  • channels.telegram.dms["<user_id>"].historyLimit
• A configuração channels.telegram.retry se aplica aos auxiliares de envio do Telegram (CLI/ferramentas/ações) para erros recuperáveis da API de saída. A entrega da resposta final de entrada também usa uma nova tentativa limitada de envio seguro para falhas de pré-conexão do Telegram, mas não tenta novamente envelopes de rede ambíguos após envio que poderiam duplicar mensagens visíveis.

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 tópicos de fórum (ou use um destino :topic:)

• --presentation com blocos buttons para teclados inline quando channels.telegram.capabilities.inlineButtons permite
• --pin ou --delivery '{"pin":true}' para solicitar entrega fixada quando o bot pode fixar nesse chat
• --force-document para enviar imagens, GIFs e vídeos de saída como documentos em vez de uploads de foto comprimida, mídia animada ou vídeo

• channels.telegram.actions.sendMessage=false desativa mensagens de saída do Telegram, incluindo enquetes
• channels.telegram.actions.poll=false desativa a criação de enquetes do Telegram mantendo envios regulares ativados

• channels.telegram.execApprovals.enabled (ativa automaticamente quando pelo menos um aprovador é resolvível)
• channels.telegram.execApprovals.approvers (recorre aos IDs numéricos de proprietários de commands.ownerAllowFrom)
• channels.telegram.execApprovals.target: dm (padrão) | channel | both
• agentFilter, sessionFilter

• Se requireMention=false, o modo de privacidade do Telegram deve permitir visibilidade completa.
  • BotFather: /setprivacy -> Disable
  • depois remova e adicione novamente o bot ao grupo
• openclaw channels status avisa quando a configuração espera mensagens de grupo sem menção.
• openclaw channels status --probe pode verificar IDs numéricos explícitos de grupos; o curinga "*" não pode ter associação verificada por probe.
• Teste rápido de sessão: /activation always.

• quando channels.telegram.groups existe, o grupo deve estar listado (ou incluir "*")
• verifique a associação do bot no grupo
• revise os logs: openclaw logs --follow para motivos de ignorar

• autorize sua identidade de remetente (pareamento e/ou allowFrom numérico)
• a autorização de comandos ainda se aplica mesmo quando a política do grupo é open
• setMyCommands failed com BOT_COMMANDS_TOO_MUCH significa que o menu nativo tem entradas demais; reduza comandos de Plugin/skill/personalizados ou desative menus nativos
• chamadas de inicialização deleteMyCommands / setMyCommands e chamadas de digitação sendChatAction são limitadas e tentam novamente uma vez pelo fallback de transporte do Telegram em timeout de solicitação. Erros persistentes de rede/fetch geralmente indicam problemas de DNS/alcance HTTPS para api.telegram.org

• getMe returned 401 é uma falha de autenticação do Telegram para o token de bot configurado.
• Copie novamente ou regenere o token do bot no BotFather e atualize channels.telegram.botToken, channels.telegram.tokenFile, channels.telegram.accounts.<id>.botToken ou TELEGRAM_BOT_TOKEN para a conta padrão.
• deleteWebhook 401 Unauthorized durante a inicialização também é uma falha de autenticação; tratá-la como “nenhum webhook existe” apenas adiaria a mesma falha de token inválido para chamadas posteriores da API.

• Node 22+ + fetch/proxy personalizado pode acionar comportamento de abort imediato se os tipos de AbortSignal não coincidirem.
• Alguns hosts resolvem api.telegram.org para IPv6 primeiro; saída IPv6 quebrada pode causar falhas intermitentes da API do Telegram.
• Se os logs incluírem TypeError: fetch failed ou Network request for 'getUpdates' failed!, o OpenClaw agora tenta novamente esses casos como erros de rede recuperáveis.
• Durante a inicialização de polling, o OpenClaw reutiliza a probe getMe de inicialização bem-sucedida para o grammY, para que o runner não precise de um segundo getMe antes do primeiro getUpdates.
• Se deleteWebhook falhar com um erro de rede transitório durante a inicialização de polling, o OpenClaw continua para long polling em vez de fazer outra chamada de plano de controle antes do poll. Um webhook ainda ativo aparece como um conflito de getUpdates; então o OpenClaw reconstrói o transporte do Telegram e tenta novamente a limpeza do webhook.
• Se sockets do Telegram forem reciclados em uma cadência fixa curta, verifique se há um channels.telegram.timeoutSeconds baixo; clientes de bot limitam valores configurados abaixo das proteções de solicitação de saída e getUpdates, mas versões mais antigas podiam abortar cada poll ou resposta quando isso era definido abaixo dessas proteções.
• Se os logs incluírem Polling stall detected, o OpenClaw reinicia o polling e reconstrói o transporte do Telegram após 120 segundos sem liveness de long-poll concluída por padrão.
• openclaw channels status --probe e openclaw doctor avisam quando uma conta de polling em execução não concluiu getUpdates após o período de tolerância de inicialização, quando uma conta de webhook em execução não concluiu setWebhook após o período de tolerância de inicialização, ou quando a última atividade bem-sucedida de transporte de polling está obsoleta.
• Aumente channels.telegram.pollingStallThresholdMs apenas quando chamadas getUpdates de longa duração estiverem saudáveis, mas seu host ainda relatar reinícios por polling travado falso-positivo. Travamentos persistentes geralmente apontam para problemas de saída de proxy, DNS, IPv6 ou TLS entre o host e api.telegram.org.
• O Telegram também respeita env de proxy de processo para transporte da Bot API, incluindo HTTP_PROXY, HTTPS_PROXY, ALL_PROXY e suas variantes em minúsculas. NO_PROXY / no_proxy ainda pode contornar api.telegram.org.
• Se o proxy gerenciado do OpenClaw estiver configurado por OPENCLAW_PROXY_URL para um ambiente de serviço e nenhum env de proxy padrão estiver presente, o Telegram também usa essa URL para transporte da Bot API.
• Em hosts VPS com saída direta/TLS instável, roteie chamadas da API do Telegram por channels.telegram.proxy:

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

• O Node 22+ usa autoSelectFamily=true por padrão (exceto no WSL2). A ordem dos resultados de DNS do Telegram respeita OPENCLAW_TELEGRAM_DNS_RESULT_ORDER, depois channels.telegram.network.dnsResultOrder, depois o padrão do processo, como NODE_OPTIONS=--dns-result-order=ipv4first; se nada disso se aplicar, o Node 22+ volta para ipv4first.
• Se o seu host for WSL2 ou funcionar explicitamente melhor com comportamento somente IPv4, force a seleção de família:

channels:
  telegram:
    network:
      autoSelectFamily: false

• Respostas de intervalo de benchmark RFC 2544 (198.18.0.0/15) já são permitidas para downloads de mídia do Telegram por padrão. Se um fake-IP confiável ou proxy transparente reescrever api.telegram.org para algum outro endereço privado/interno/de uso especial durante downloads de mídia, você pode optar pelo bypass exclusivo do Telegram:

channels:
  telegram:
    network:
      dangerouslyAllowPrivateNetwork: true

• A mesma opção está disponível por conta em channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork.
• Se o seu proxy resolver hosts de mídia do Telegram para 198.18.x.x, deixe a flag perigosa desativada primeiro. A mídia do Telegram já permite o intervalo de benchmark RFC 2544 por padrão.

• Substituições de ambiente (temporárias):
  • OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1
  • OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first
• Valide as respostas de DNS:

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