Mensagens ricas e aprovações do Telegram no OpenClaw

Texto é só o começo do que um bot do Telegram pode enviar: blocos formatados, um teclado abaixo de uma mensagem, um iniciador de Mini App, uma reação à mensagem de outra pessoa, um prompt de aprovação com dois botões. O OpenClaw expõe cada um deles por meio de um pequeno conjunto de chaves de configuração e ações de mensagem, a maioria desativada até você ativá-la. A seguir: o contrato de formatação, os escopos dos botões, as ações com seus controles e como uma aprovação de execução chega a um aprovador dentro do Telegram.

Formatação

• O texto enviado usa por padrão o HTML convencional do Telegram, legível nos clientes atuais, com negrito, itálico, links, código, spoilers e citações, e o código delimitado mantém seu conteúdo e espaçamento literais, incluindo exemplos de delimitadores dentro do bloco; os blocos exclusivos de mensagens ricas da Bot API 10.3, tabelas nativas, detalhes, mídia rica e fórmulas, não são usados a menos que você os ative.
• Com a flag de mensagens ricas ativada, o agente é informado de que as mensagens ricas estão disponíveis para esse bot ou conta, com o contrato de escrita compatível em Markdown e ilhas de HTML, o Markdown é renderizado pela representação intermediária de Markdown do OpenClaw como blocos ricos tipados, títulos, tabelas, detalhes, checklists, mídia rica, fórmulas, mapas e colagens, enquanto as legendas de mídia continuam usando legendas HTML limitadas a 1024 caracteres; o texto rico comum do corpo preserva os espaços e quebras de linha analisados, as entidades são decodificadas uma única vez, tags escapadas continuam como texto visível, HTML não suportado continua visível sem suprimir o Markdown dentro dele, texto rico longo é dividido automaticamente conforme os limites do Telegram, e tabelas acima do limite de 20 colunas recorrem a um bloco de código.
• A flag vem desativada por padrão por compatibilidade com os clientes, porque alguns clientes atuais de Desktop, Web, Android e de terceiros exibem mensagens ricas aceitas como não suportadas; mantenha-a desativada a menos que todos os clientes usados com o bot consigam renderizá-las, e o comando status mostra se a sessão atual está com as mensagens ricas ativadas ou desativadas.
• As prévias de links vêm ativadas por padrão, e a chave de prévia de links definida como false desativa a detecção automática de entidades no texto rico; manter o texto do modelo longe dos símbolos do Markdown rico do Telegram também é o motivo pelo qual uma faixa monetária como 400 a 600 mil dólares não é interpretada como fórmula.

Os botões de Mini App só funcionam em chats privados entre um usuário e o bot.

Botões inline

O recurso de botões inline tem cinco escopos, off, dm, group, all e allowlist, com allowlist como padrão, definido no canal e sobrescrito por conta; a forma legada em array corresponde a all, uma conta com um array de capacidades vazio herda as capacidades do canal, e um off explícito desativa os botões. A ferramenta de perguntar ao usuário usa esses controles nativos para uma única pergunta de escolha única, com uma linha por opção e uma opção Other que abre o campo de resposta do Telegram. Uma ação de mensagem carrega uma apresentação com um bloco de botões, cada botão com um rótulo, uma ação e um estilo opcional, como success ou danger; uma ação de callback devolve o seu valor, e uma ação de web app abre a URL de uma Mini App, o que só funciona em chats privados entre um usuário e o bot. Valores de callback não reivindicados por um handler interativo de plugin registrado são repassados ao agente como texto prefixado com callback data. Com a ingestão durável, a confirmação do callback é enviada logo depois que a atualização é armazenada, sem esperar handlers anteriores na fila desse chat, então o Telegram limpa cedo o indicador de carregamento, enquanto a ação do botão continua seguindo a autorização normal e o processamento ordenado.

Ações e aprovações

• As ações são send-message, com um destino, conteúdo e, opcionalmente, URL de mídia, ID de resposta e ID de thread, react, com um chat, uma mensagem e um emoji, emoji-list, com chat e limite opcionais, delete-message, edit-message, com conteúdo ou legenda e botões inline opcionais, em que uma edição só de botões atualiza o reply markup, e create-forum-topic, com um nome e, opcionalmente, cor do ícone ou emoji personalizado, além dos aliases send, react, delete, edit, sticker, sticker-search e topic-create; os controles de send-message, delete-message, reactions e sticker vêm desativados por padrão, reactions cobre tanto react quanto emoji-list, edit e as ações de tópico de fórum ficam ativadas sem um controle próprio, e os envios em tempo de execução usam o snapshot de configuração e segredos da inicialização ou do recarregamento, em vez de resolver de novo as referências a segredos a cada envio.
• A ação emoji-list inspeciona as reações permitidas no chat e na conta confiáveis atuais, agentes não podem inspecionar outro chat, enquanto operadores diretos podem passar outro ID de chat, o limite padrão é 100 e não pode passar disso, um chat sem restrições devolve as reações padrão com uma nota dizendo que todas são permitidas, uma reação rejeitada devolve uma pequena amostra das reações padrão e dos identificadores de emojis personalizados permitidos, a menos que a própria consulta tenha falhado, e você passa um emoji Unicode ou um identificador numérico de emoji personalizado diretamente para react.
• As aprovações de execução funcionam nas DMs dos aprovadores e podem, opcionalmente, publicar prompts no chat ou tópico de origem, os aprovadores precisam ser IDs de usuário numéricos, a chave enabled em auto as ativa quando pelo menos um aprovador pode ser resolvido, a lista de aprovadores recorre aos IDs numéricos de dono da lista de permissões de donos, o destino é dm por padrão, com channel e both como alternativas, filtros de agente e de sessão as restringem, as listas de permissões que decidem quem pode falar com o bot não tornam ninguém aprovador, embora o primeiro pareamento aprovado inicialize a lista de donos, a entrega no canal mostra o texto do comando, então channel ou both só cabem em grupos confiáveis, um prompt que cai em um tópico de fórum mantém esse tópico para a continuação, as aprovações expiram após 30 minutos por padrão, os botões inline de aprovação exigem que o recurso de botões permita a superfície de destino, e IDs de aprovação com prefixo plugin são resolvidos pelas aprovações de plugins, enquanto os demais tentam primeiro as aprovações de execução.

OpenClaw no Telegram é o artigo sobre o canal que essas superfícies ampliam, e o comportamento das mensagens do Telegram no OpenClaw, o modelo de entrega por baixo delas.

Botões entre canais

O bloco de botões, o valor de callback e o prompt de aprovação mantêm o mesmo formato em todos os canais que têm componentes nativos, e é por isso que um agente pode fazer uma pergunta de sim ou não sem saber onde ela será respondida. Componentes e aprovações do Discord no OpenClaw mostra o lado do Discord desse contrato, e as reações no OpenClaw, a semântica de reações que react e emoji-list implementam.

Na Diali

O Telegram é um dos canais que a Diali conecta pelo painel, e a configuração do motor gerada é substituída a cada versão, então as chaves de formatação e de botões descritas aqui mostram o que um bot hospedado pode fazer, e não configurações que você edita à mão. Telegram na Diali é o canal na Diali, e a segurança na Diali, a fronteira que se aplica a toda ação que um bot pode executar.

• HTML por padrão; blocos ricos só quando todos os clientes conseguem renderizá-los.
• Os botões seguem um escopo; Mini Apps abrem só em chats privados.
• Envios, exclusões, reações e stickers ficam desativados até serem liberados.