> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Telegram

> Converse com o ChatCLI pelo Telegram: um bot por long-polling, sem URL pública, com lista de usuários permitidos, voice notes nos dois sentidos, imagens e o indicador nativo de digitação.

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**.

| | Telegram |
| - | - |
| Transporte | Long-polling da Bot API (`getUpdates`); nenhuma porta é aberta |
| Quem pode falar com o bot | Usuários em `CHATCLI_TELEGRAM_ALLOWED_USERS`; qualquer um quando vazio |
| Voice notes recebidas | Sim, transcritas antes de o agente rodar |
| Respostas em voz | Sim, como voice note nativa |
| Imagens recebidas | Sim, foto ou imagem enviada como arquivo |
| Imagens enviadas | Sim |
| Sinal de "trabalhando" | Indicador nativo "digitando…" |

## Configuração

<Steps>
  <Step title="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…`.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Configure o ChatCLI">
    ```bash theme={"system"}
    export CHATCLI_TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
    export CHATCLI_TELEGRAM_ALLOWED_USERS="111111111"   # o seu user ID; adicione outros separados por vírgula
    ```

    Coloque as mesmas linhas no seu `.env` para mantê-las entre sessões.
  </Step>

  <Step title="Inicie o gateway">
    ```text theme={"system"}
    /gateway start
    /gateway status     # telegram deve aparecer como pronto
    ```

    Mande uma mensagem para o bot. Ele mostra "digitando…" enquanto trabalha e responde no chat.
  </Step>
</Steps>

## Variáveis de ambiente

| Variável | Obrigatória | Padrão | O que faz |
| - | - | - | - |
| `CHATCLI_TELEGRAM_BOT_TOKEN` | sim | — | O token do bot dado pelo BotFather. O adaptador só liga com ela definida. |
| `CHATCLI_TELEGRAM_ALLOWED_USERS` | não | vazio | User IDs numéricos que podem falar com o bot, separados por vírgula, espaço ou ponto e vírgula. Vazio aceita **todo mundo** e registra um aviso no start. |
| `CHATCLI_TELEGRAM_HOME_CHANNEL` | não | — | Chat padrão das [mensagens proativas](/pt/gateway/proactive-messaging) enviadas com `@send telegram`. |

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

## Quem alcança o bot

<Warning>
  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.
</Warning>

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](/pt/gateway/chat-gateway#mensagens-de-voz-transcrição).
* **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](/pt/gateway/voice-replies).
* **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

<AccordionGroup>
  <Accordion title="O bot nunca responde">
    * `/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.
  </Accordion>

  <Accordion title="O bot ignora mensagens num grupo">
    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.
  </Accordion>

  <Accordion title="As voice notes não são entendidas">
    Veja [Mensagens de voz](/pt/gateway/chat-gateway#mensagens-de-voz-transcrição): `/gateway status` mostra o backend de transcrição em uso.
  </Accordion>
</AccordionGroup>

## Veja também

<CardGroup cols={2}>
  <Card title="Chat gateway" icon="comments" href="/pt/gateway/chat-gateway">
    Como as mensagens rodam, voz, imagens, continuidade e os outros canais.
  </Card>

  <Card title="Respostas em voz" icon="volume-high" href="/pt/gateway/voice-replies">
    Responder voz com voz, e como cada conversa liga ou desliga.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.