​

Telegram (Bot API)

​

Configuração rápida (iniciante)

1. Crie um bot com @BotFather (link direto). Confirme que o handle é exatamente @BotFather, depois copie o token.
2. Defina o token:
   • Env: TELEGRAM_BOT_TOKEN=...
   • Ou config: channels.telegram.botToken: "...".
   • Se ambos estiverem definidos, a config tem precedência (o fallback de env é apenas para a conta padrão).
3. Inicie o gateway.
4. O acesso por DM é pareamento por padrão; aprove o código de pareamento no primeiro contato.

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

​

O que é

• Um canal da API de Bots do Telegram pertencente ao Gateway.
• Roteamento determinístico: as respostas voltam para o Telegram; o modelo nunca escolhe canais.
• DMs compartilham a sessão principal do agente; grupos permanecem isolados (agent:<agentId>:telegram:group:<chatId>).

​

Configuração (caminho rápido)

​

1. Criar um token de bot (BotFather)

1. Abra o Telegram e converse com @BotFather (link direto). Confirme que o handle é exatamente @BotFather.
2. Execute /newbot, depois siga as instruções (nome + nome de usuário terminando em bot).
3. Copie o token e armazene-o com segurança.

• /setjoingroups — permitir/negar adicionar o bot a grupos.
• /setprivacy — controlar se o bot vê todas as mensagens do grupo.

​

2. Configurar o token (env ou config)

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

3. Inicie o gateway. O Telegram inicia quando um token é resolvido (config primeiro, fallback de env).
4. O acesso por DM é pareado por padrão. Aprove o código quando o bot for contatado pela primeira vez.
5. Para grupos: adicione o bot, decida o comportamento de privacidade/admin (abaixo) e então defina channels.telegram.groups para controlar gating por menção + listas de permissões.

​

Token + privacidade + permissões (lado do Telegram)

​

Criação do token (BotFather)

• /newbot cria o bot e retorna o token (mantenha-o em segredo).
• Se um token vazar, revogue/regenere via @BotFather e atualize sua configuração.

​

Visibilidade de mensagens em grupos (Modo de Privacidade)

• Desativar o modo de privacidade com /setprivacy ou
• Adicionar o bot como admin do grupo (bots admin recebem todas as mensagens).

​

Permissões de grupo (direitos de admin)

​

Como funciona (comportamento)

• Mensagens de entrada são normalizadas no envelope de canal compartilhado com contexto de resposta e placeholders de mídia.
• Respostas em grupos exigem menção por padrão (menção nativa @ ou agents.list[].groupChat.mentionPatterns / messages.groupChat.mentionPatterns).
• Substituição multiagente: defina padrões por agente em agents.list[].groupChat.mentionPatterns.
• As respostas sempre retornam para o mesmo chat do Telegram.
• Long-polling usa o runner do grammY com sequenciamento por chat; a concorrência geral é limitada por agents.defaults.maxConcurrent.
• A API de Bots do Telegram não suporta recibos de leitura; não há opção sendReadReceipts.

​

Streaming de rascunho

• Modo Threaded habilitado para o bot no @BotFather (modo de tópico de fórum).
• Apenas threads de chat privado (o Telegram inclui message_thread_id nas mensagens de entrada).
• channels.telegram.streamMode não definido como "off" (padrão: "partial", "block" habilita atualizações de rascunho em blocos).

​

Formatação (HTML do Telegram)

• Texto de saída do Telegram usa parse_mode: "HTML" (subconjunto de tags suportadas pelo Telegram).
• Entrada em estilo Markdown é renderizada em HTML seguro para o Telegram (negrito/itálico/riscado/código/links); elementos de bloco são achatados em texto com novas linhas/marcadores.
• HTML bruto vindo de modelos é escapado para evitar erros de parsing do Telegram.
• Se o Telegram rejeitar o payload HTML, o OpenClaw tenta novamente a mesma mensagem como texto simples.

​

Comandos (nativos + personalizados)

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

​

Solução de problemas de configuração (comandos)

• setMyCommands failed nos logs geralmente significa que HTTPS/DNS de saída está bloqueado para api.telegram.org.
• Se você vir falhas sendMessage ou sendChatAction, verifique o roteamento IPv6 e o DNS.

• Comandos personalizados são apenas entradas de menu; o OpenClaw não os implementa a menos que você os trate em outro lugar.
• Some commands can be handled by plugins/skills without being registered in Telegram’s command menu. These still work when typed (they just won’t show up in /commands / the menu).
• Os nomes dos comandos são normalizados (prefixo / removido, em minúsculas) e devem corresponder a a-z, 0-9, _ (1–32 caracteres).
• Comandos personalizados não podem substituir comandos nativos. Conflitos são ignorados e registrados em log.
• Se commands.native estiver desabilitado, apenas comandos personalizados são registrados (ou limpos se não houver).

​

Device pairing commands (device-pair plugin)

1. /pair generates a setup code (sent as a separate message for easy copy/paste).
2. Paste the setup code in the iOS app to connect.
3. /pair approve approves the latest pending device request.

​

Limites

• Texto de saída é dividido em channels.telegram.textChunkLimit (padrão 4000).
• Divisão opcional por nova linha: defina channels.telegram.chunkMode="newline" para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
• Downloads/uploads de mídia são limitados por channels.telegram.mediaMaxMb (padrão 5).
• Requisições da API de Bots do Telegram expiram após channels.telegram.timeoutSeconds (padrão 500 via grammY). Defina menor para evitar travamentos longos.
• Contexto do histórico do grupo usa channels.telegram.historyLimit (ou channels.telegram.accounts.*.historyLimit), com fallback para messages.groupChat.historyLimit. Defina 0 para desabilitar (padrão 50).
• O histórico de DM pode ser limitado com channels.telegram.dmHistoryLimit (turnos do usuário). Substituições por usuário: channels.telegram.dms["<user_id>"].historyLimit.

​

Modos de ativação em grupos

​

Via config (recomendado)

{
  channels: {
    telegram: {
      groups: {
        "-1001234567890": { requireMention: false }, // always respond in this group
      },
    },
  },
}

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: false }, // all groups, always respond
      },
    },
  },
}

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

​

Via comando (nível de sessão)

• /activation always - responder a todas as mensagens
• /activation mention - exigir menções (padrão)

​

Obtendo o ID do chat do grupo

​

Escritas de configuração

• Um grupo é atualizado para supergrupo e o Telegram emite migrate_to_chat_id (o ID do chat muda). O OpenClaw pode migrar channels.telegram.groups automaticamente.
• Você executa /config set ou /config unset em um chat do Telegram (requer commands.config: true).

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

​

Tópicos (supergrupos de fórum)

• Anexa :topic:<threadId> à chave de sessão do grupo do Telegram para que cada tópico fique isolado.
• Envia indicadores de digitação e respostas com message_thread_id para que as respostas permaneçam no tópico.
• O tópico geral (thread id 1) é especial: envios de mensagens omitem message_thread_id (o Telegram rejeita), mas indicadores de digitação ainda o incluem.
• Expõe MessageThreadId + IsForum no contexto de template para roteamento/templating.
• Configuração específica por tópico está disponível em channels.telegram.groups.<chatId>.topics.<threadId> (skills, listas de permissões, resposta automática, prompts do sistema, desabilitar).
• Configurações de tópico herdam as do grupo (requireMention, listas de permissões, skills, prompts, habilitado) a menos que sejam substituídas por tópico.

​

Botões Inline

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

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

• off — botões inline desabilitados
• dm — apenas DMs (alvos de grupo bloqueados)
• group — apenas grupos (alvos de DM bloqueados)
• all — DMs + grupos
• allowlist — DMs + grupos, mas apenas remetentes permitidos por allowFrom/groupAllowFrom (mesmas regras que comandos de controle)

​

Envio de botões

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

​

Opções de configuração

• channels.telegram.capabilities: Configuração de capacidade padrão global aplicada a todas as contas do Telegram, a menos que seja substituída.
• channels.telegram.accounts.<account>.capabilities: Capacidades por conta que substituem os padrões globais para aquela conta específica.

​

Controle de acesso (DMs + grupos)

​

Acesso por DM

• Padrão: channels.telegram.dmPolicy = "pairing". Remetentes desconhecidos recebem um código de pareamento; mensagens são ignoradas até a aprovação (códigos expiram após 1 hora).
• Aprovar via:
  • openclaw pairing list telegram
  • openclaw pairing approve telegram <CODE>
• O pareamento é a troca de token padrão usada para DMs do Telegram. Detalhes: Pareamento
• channels.telegram.allowFrom aceita IDs numéricos de usuário (recomendado) ou entradas @username. Não é o nome de usuário do bot; use o ID do remetente humano. O assistente aceita @username e resolve para o ID numérico quando possível.

​

Encontrando seu ID de usuário do Telegram

1. Inicie o gateway e envie DM ao seu bot.
2. Execute openclaw logs --follow e procure from.id.

1. Envie DM ao seu bot.
2. Busque atualizações com o token do bot e leia message.from.id:
   curl "https://api.telegram.org/bot<bot_token>/getUpdates"
   

• Envie DM para @userinfobot ou @getidsbot e use o ID de usuário retornado.

​

Acesso a grupos

• Sem config groups = todos os grupos permitidos
• Com config groups = apenas os grupos listados ou "*" são permitidos
• Exemplo: "groups": { "-1001234567890": {}, "*": {} } permite todos os grupos

• "open" = todos os remetentes em grupos permitidos podem enviar mensagens
• "allowlist" = apenas remetentes em channels.telegram.groupAllowFrom podem enviar mensagens
• "disabled" = nenhuma mensagem de grupo é aceita O padrão é groupPolicy: "allowlist" (bloqueado a menos que você adicione groupAllowFrom).

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

​

Long-polling vs webhook

• Padrão: long-polling (nenhuma URL pública necessária).
• Modo webhook: defina channels.telegram.webhookUrl e channels.telegram.webhookSecret (opcionalmente channels.telegram.webhookPath).
  • O listener local se liga a 0.0.0.0:8787 e serve POST /telegram-webhook por padrão.
  • Se sua URL pública for diferente, use um proxy reverso e aponte channels.telegram.webhookUrl para o endpoint público.

​

Encadeamento de respostas

• [[reply_to_current]] — responder à mensagem disparadora.
• [[reply_to:<id>]] — responder a um ID de mensagem específico.

• first (padrão), all, off.

​

Mensagens de áudio (voz vs arquivo)

• [[audio_as_voice]] — enviar áudio como nota de voz em vez de arquivo.

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

​

Video messages (video vs video note)

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

​

Figurinhas (Stickers)

​

Recebendo adesivos

• Figurinhas estáticas (WEBP): Baixadas e processadas via visão. A figurinha aparece como um placeholder <media:sticker> no conteúdo da mensagem.
• Figurinhas animadas (TGS): Ignoradas (formato Lottie não suportado para processamento).
• Figurinhas de vídeo (WEBM): Ignoradas (formato de vídeo não suportado para processamento).

• Sticker — objeto com:
  • emoji — emoji associado à figurinha
  • setName — nome do conjunto de figurinhas
  • fileId — ID de arquivo do Telegram (enviar a mesma figurinha de volta)
  • fileUniqueId — ID estável para consulta no cache
  • cachedDescription — descrição de visão em cache quando disponível

​

Cache de adesivo

1. Primeiro encontro: A imagem da figurinha é enviada à IA para análise de visão. A IA gera uma descrição (por exemplo, “Um gato de desenho animado acenando entusiasticamente”).
2. Armazenamento em cache: A descrição é salva junto com o ID do arquivo da figurinha, emoji e nome do conjunto.
3. Encontros subsequentes: Quando a mesma figurinha aparece novamente, a descrição em cache é usada diretamente. A imagem não é enviada à IA.

{
  "fileId": "CAACAgIAAxkBAAI...",
  "fileUniqueId": "AgADBAADb6cxG2Y",
  "emoji": "👋",
  "setName": "CoolCats",
  "description": "A cartoon cat waving enthusiastically",
  "cachedAt": "2026-01-15T10:30:00.000Z"
}

• Reduz custos de API ao evitar chamadas de visão repetidas para a mesma figurinha
• Tempos de resposta mais rápidos para figurinhas em cache (sem atraso de processamento de visão)
• Permite funcionalidade de busca de figurinhas com base em descrições em cache

​

Enviando stickers

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

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

• fileId (obrigatório) — o ID de arquivo do Telegram da figurinha. Obtenha isso a partir de Sticker.fileId ao receber uma figurinha, ou de um resultado de sticker-search.
• replyTo (opcional) — ID da mensagem à qual responder.
• threadId (opcional) — ID do tópico de mensagem para tópicos de fórum.

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

{
  ok: true,
  count: 2,
  stickers: [
    {
      fileId: "CAACAgIAAxkBAAI...",
      emoji: "👋",
      description: "A cartoon cat waving enthusiastically",
      setName: "CoolCats",
    },
  ],
}

{
  action: "sticker",
  channel: "telegram",
  to: "-1001234567890",
  fileId: "CAACAgIAAxkBAAI...",
  replyTo: 42,
  threadId: 123,
}

​

Streaming (rascunhos)

• Chats privados com tópicos habilitados (modo de tópico de fórum para o bot).
• Mensagens de entrada devem incluir message_thread_id (thread de tópico privado).
• O streaming é ignorado para grupos/supergrupos/canais.

• channels.telegram.streamMode: "off" | "partial" | "block" (padrão: partial)
  • partial: atualizar a bolha de rascunho com o texto de streaming mais recente.
  • block: atualizar a bolha de rascunho em blocos maiores (em partes).
  • off: desabilitar o streaming de rascunho.
• Opcional (apenas para streamMode: "block"):
  • channels.telegram.draftChunk: { minChars?, maxChars?, breakPreference? }
    • padrões: minChars: 200, maxChars: 800, breakPreference: "paragraph" (limitados a channels.telegram.textChunkLimit).

• /reasoning stream transmite o raciocínio para a bolha de rascunho enquanto a resposta é gerada, depois envia a resposta final sem o raciocínio.
• Se channels.telegram.streamMode for off, o stream de raciocínio é desabilitado. Mais contexto: Streaming + divisão em partes.

​

Política de tentativas

​

Ferramenta do agente (mensagens + reações)

• Ferramenta: telegram com ação sendMessage (to, content, opcional mediaUrl, replyToMessageId, messageThreadId).
• Ferramenta: telegram com ação react (chatId, messageId, emoji).
• Ferramenta: telegram com ação deleteMessage (chatId, messageId).
• Semântica de remoção de reações: veja /tools/reactions.
• Gateamento de ferramentas: channels.telegram.actions.reactions, channels.telegram.actions.sendMessage, channels.telegram.actions.deleteMessage (padrão: habilitado) e channels.telegram.actions.sticker (padrão: desabilitado).

​

Notificações de reações

1. Recebe a atualização message_reaction da API do Telegram
2. Converte para um evento de sistema com o formato: "Telegram reaction added: {emoji} by {user} on msg {id}"
3. Enfileira o evento de sistema usando a mesma chave de sessão das mensagens regulares
4. Quando a próxima mensagem chega nessa conversa, os eventos de sistema são drenados e prefixados ao contexto do agente

• channels.telegram.reactionNotifications: Controla quais reações disparam notificações
  • "off" — ignorar todas as reações
  • "own" — notificar quando usuários reagem a mensagens do bot (best-effort; em memória) (padrão)
  • "all" — notificar todas as reações
• channels.telegram.reactionLevel: Controla a capacidade de reação do agente
  • "off" — o agente não pode reagir a mensagens
  • "ack" — o bot envia reações de confirmação (👀 enquanto processa) (padrão)
  • "minimal" — o agente pode reagir com parcimônia (diretriz: 1 a cada 5–10 trocas)
  • "extensive" — o agente pode reagir liberalmente quando apropriado

{
  channels: {
    telegram: {
      reactionNotifications: "all", // See all reactions
      reactionLevel: "minimal", // Agent can react sparingly
    },
  },
}

• Bots do Telegram devem solicitar explicitamente message_reaction em allowed_updates (configurado automaticamente pelo OpenClaw)
• No modo webhook, reações são incluídas no webhook allowed_updates
• No modo polling, reações são incluídas nas getUpdates allowed_updates

​

Destinos de entrega (CLI/cron)

• Use um chat id (123456789) ou um nome de usuário (@name) como destino.
• Exemplo: openclaw message send --channel telegram --target 123456789 --message "hi".

​

Solução de problemas

• Se você definiu channels.telegram.groups.*.requireMention=false, o modo de privacidade da API de Bots do Telegram deve estar desabilitado.
  • BotFather: /setprivacy → Disable (depois remova e re-adicione o bot ao grupo)
• openclaw channels status mostra um aviso quando a config espera mensagens de grupo sem menção.
• openclaw channels status --probe pode verificar adicionalmente a associação para IDs numéricos explícitos de grupos (não consegue auditar regras curinga "*").
• Teste rápido: /activation always (apenas sessão; use config para persistência)

• Se channels.telegram.groups estiver definido, o grupo deve estar listado ou usar "*"
• Verifique Configurações de Privacidade no @BotFather → “Group Privacy” deve estar OFF
• Verifique se o bot é realmente membro (não apenas admin sem acesso de leitura)
• Verifique os logs do gateway: openclaw logs --follow (procure por “skipping group message”)

• O comando /activation atualiza o estado da sessão, mas não persiste na config
• Para comportamento persistente, adicione o grupo a channels.telegram.groups com requireMention: false

• Certifique-se de que seu ID de usuário do Telegram esteja autorizado (via pareamento ou channels.telegram.allowFrom)
• Comandos exigem autorização mesmo em grupos com groupPolicy: "open"

• O Node 22+ é mais rigoroso com instâncias AbortSignal; sinais externos podem abortar chamadas fetch imediatamente.
• Atualize para uma build do OpenClaw que normalize sinais de abort, ou execute o gateway no Node 20 até poder atualizar.

• Alguns hosts resolvem api.telegram.org para IPv6 primeiro. Se seu servidor não tiver saída IPv6 funcional, o grammY pode travar em requisições apenas IPv6.
• Corrija habilitando saída IPv6 ou forçando resolução IPv4 para api.telegram.org (por exemplo, adicione uma entrada /etc/hosts usando o registro A IPv4, ou prefira IPv4 na pilha DNS do SO), depois reinicie o gateway.
• Verificação rápida: dig +short api.telegram.org A e dig +short api.telegram.org AAAA para confirmar o que o DNS retorna.

​

Referência de configuração (Telegram)

• channels.telegram.enabled: habilitar/desabilitar a inicialização do canal.
• channels.telegram.botToken: token do bot (BotFather).
• channels.telegram.tokenFile: ler token de um caminho de arquivo.
• channels.telegram.dmPolicy: pairing | allowlist | open | disabled (padrão: pareamento).
• channels.telegram.allowFrom: lista de permissões de DM (ids/usernames). open requer "*".
• channels.telegram.groupPolicy: open | allowlist | disabled (padrão: lista de permissões).
• channels.telegram.groupAllowFrom: lista de permissões de remetentes de grupo (ids/usernames).
• channels.telegram.groups: padrões por grupo + lista de permissões (use "*" para padrões globais).
  • channels.telegram.groups.<id>.groupPolicy: substituição por grupo para groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.requireMention: padrão de gating por menção.
  • channels.telegram.groups.<id>.skills: filtro de skills (omitir = todas as skills, vazio = nenhuma).
  • channels.telegram.groups.<id>.allowFrom: substituição da lista de permissões de remetentes por grupo.
  • channels.telegram.groups.<id>.systemPrompt: prompt de sistema extra para o grupo.
  • channels.telegram.groups.<id>.enabled: desabilitar o grupo quando false.
  • channels.telegram.groups.<id>.topics.<threadId>.*: substituições por tópico (mesmos campos do grupo).
  • channels.telegram.groups.<id>.topics.<threadId>.groupPolicy: substituição por tópico para groupPolicy (open | allowlist | disabled).
  • channels.telegram.groups.<id>.topics.<threadId>.requireMention: substituição de gating por menção por tópico.
• channels.telegram.capabilities.inlineButtons: off | dm | group | all | allowlist (padrão: lista de permissões).
• channels.telegram.accounts.<account>.capabilities.inlineButtons: substituição por conta.
• channels.telegram.replyToMode: off | first | all (padrão: first).
• channels.telegram.textChunkLimit: tamanho de divisão de saída (caracteres).
• channels.telegram.chunkMode: length (padrão) ou newline para dividir em linhas em branco (limites de parágrafo) antes da divisão por comprimento.
• channels.telegram.linkPreview: alternar prévias de links para mensagens de saída (padrão: true).
• channels.telegram.streamMode: off | partial | block (streaming de rascunho).
• channels.telegram.mediaMaxMb: limite de mídia de entrada/saída (MB).
• channels.telegram.retry: política de tentativas para chamadas de saída da API do Telegram (tentativas, minDelayMs, maxDelayMs, jitter).
• channels.telegram.network.autoSelectFamily: substituir autoSelectFamily do Node (true=habilitar, false=desabilitar). Padrão desabilitado no Node 22 para evitar timeouts do Happy Eyeballs.
• channels.telegram.proxy: URL de proxy para chamadas da API de Bots (SOCKS/HTTP).
• channels.telegram.webhookUrl: habilitar modo webhook (requer channels.telegram.webhookSecret).
• channels.telegram.webhookSecret: segredo do webhook (obrigatório quando webhookUrl está definido).
• channels.telegram.webhookPath: caminho local do webhook (padrão /telegram-webhook).
• channels.telegram.actions.reactions: gatear reações da ferramenta do Telegram.
• channels.telegram.actions.sendMessage: gatear envios de mensagens da ferramenta do Telegram.
• channels.telegram.actions.deleteMessage: gatear exclusões de mensagens da ferramenta do Telegram.
• channels.telegram.actions.sticker: gatear ações de figurinhas do Telegram — enviar e buscar (padrão: false).
• channels.telegram.reactionNotifications: off | own | all — controlar quais reações disparam eventos de sistema (padrão: own quando não definido).
• channels.telegram.reactionLevel: off | ack | minimal | extensive — controlar a capacidade de reação do agente (padrão: minimal quando não definido).

• agents.list[].groupChat.mentionPatterns (padrões de gating por menção).
• messages.groupChat.mentionPatterns (fallback global).
• commands.native (padrão para "auto" → ligado para Telegram/Discord, desligado para Slack), commands.text, commands.useAccessGroups (comportamento de comandos). Substitua com channels.telegram.commands.native.
• messages.responsePrefix, messages.ackReaction, messages.ackReactionScope, messages.removeAckAfterReply.