Skip to main content
O Telegram é o canal mais rápido de configurar: o gateway faz long-polling na Bot API, então não precisa de URL pública, porta aberta nem certificado TLS. Também é o mais completo: é o único canal com lista de usuários permitidos, respostas em voz e indicador nativo de digitação.

​
Configuração

1

Crie o bot

No Telegram, abra o @BotFather, mande /newbot e siga as instruções. O BotFather responde com o token do bot, algo como 123456:ABC-DEF….
2

Descubra o seu user ID

A lista de permitidos usa IDs numéricos, não nomes de usuário. Qualquer bot de “user info” no Telegram mostra o seu.
3

Configure o ChatCLI

Coloque as mesmas linhas no seu .env para mantê-las entre sessões.
4

Inicie o gateway

Mande uma mensagem para o bot. Ele mostra “digitando…” enquanto trabalha e responde no chat.

​
Variáveis de ambiente

As configurações compartilhadas (voz, imagens, limites de tamanho, Conversation Hub) estão na página do Chat gateway.

​
Quem alcança o bot

Cada mensagem roda o agente com suas tools e o shell, sem confirmações. Sempre defina CHATCLI_TELEGRAM_ALLOWED_USERS, a não ser que o bot seja público de propósito.
Uma mensagem de quem não está na lista é descartada sem resposta; o gateway registra o ID de quem mandou, o que ajuda a achar um ID que você esqueceu de incluir.

​
Mensagens

  • Texto e legendas: o texto da mensagem, ou a legenda de uma foto ou voice note quando não há texto.
  • Voice notes e arquivos de áudio são baixados (até CHATCLI_GATEWAY_MAX_AUDIO_BYTES, 20 MB por padrão) e transcritos antes de o agente rodar; veja Mensagens de voz.
  • Imagens: o maior tamanho de uma foto, ou um documento cujo tipo é imagem. Uma imagem por mensagem chega ao modelo.
  • As respostas são texto puro. Nenhum modo de formatação é enviado ao Telegram, então o Markdown de uma resposta aparece como foi digitado.
  • Respostas em voz chegam como voice note nativa quando o áudio é OGG (o padrão), ou como arquivo de áudio caso contrário, com o texto como legenda. Veja Respostas em voz.
  • Grupos: um grupo é uma conversa compartilhada por quem participa dele. Tópicos de fórum não são diferenciados; o bot responde no grupo.

​
Limites

  • Uma resposta é cortada em 3500 caracteres e termina com …; o resto não é enviado.
  • Uma resposta com voice note ou imagem usa o texto como legenda, que o Telegram limita a 1024 caracteres; nenhuma mensagem de texto separada é enviada.
  • Mensagens editadas, posts de canal e callbacks de botões são ignorados.

​
Solução de problemas

  • /gateway status deve listar telegram. Se não listar, CHATCLI_TELEGRAM_BOT_TOKEN não estava no ambiente em que o daemon subiu: defina e rode /gateway stop e depois /gateway start.
  • Procure em ~/.chatcli/gateway.log uma linha “not in allow-list” com o seu user ID.
  • Um bot com webhook configurado do lado do Telegram não pode também ser lido por long-polling. Remova o webhook (deleteWebhook da Bot API) se o bot já foi usado com outro serviço.
Por padrão, bots do Telegram em grupos só recebem comandos e mensagens que os mencionam (modo de privacidade). Desligue o modo de privacidade no BotFather (/setprivacy) se o bot deve ver todas as mensagens.
Veja Mensagens de voz: /gateway status mostra o backend de transcrição em uso.

​
Veja também

Chat gateway

Como as mensagens rodam, voz, imagens, continuidade e os outros canais.

Respostas em voz

Responder voz com voz, e como cada conversa liga ou desliga.