> ## 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

> Talk to ChatCLI from Telegram: a bot over long-polling, no public URL needed, with an allow-list of users, voice notes in both directions, images and the native typing indicator.

Telegram is the quickest channel to set up: the gateway **long-polls** the Bot API, so it needs no public URL, no open port and no TLS certificate. It is also the most complete one: it is the only channel with a sender **allow-list**, **voice replies** and a **native typing indicator**.

| | Telegram |
| - | - |
| Transport | Bot API long-polling (`getUpdates`); no port is opened |
| Who can talk to the bot | Users in `CHATCLI_TELEGRAM_ALLOWED_USERS`; anyone when it is empty |
| Voice notes in | Yes, transcribed before the agent runs |
| Voice replies | Yes, as a native voice note |
| Images in | Yes, a photo or an image sent as a file |
| Images out | Yes |
| "Working on it" signal | Native "typing…" indicator |

## Set it up

<Steps>
  <Step title="Create the bot">
    In Telegram, open **@BotFather**, send `/newbot` and follow the prompts. BotFather answers with the bot token, a string like `123456:ABC-DEF…`.
  </Step>

  <Step title="Find your user ID">
    The allow-list takes **numeric** user IDs, not usernames. Any "user info" bot in Telegram shows yours.
  </Step>

  <Step title="Configure ChatCLI">
    ```bash theme={"system"}
    export CHATCLI_TELEGRAM_BOT_TOKEN="123456:ABC-DEF..."
    export CHATCLI_TELEGRAM_ALLOWED_USERS="111111111"   # your user ID; add more separated by commas
    ```

    Put the same lines in your `.env` to keep them across sessions.
  </Step>

  <Step title="Start the gateway">
    ```text theme={"system"}
    /gateway start
    /gateway status     # telegram should be listed as ready
    ```

    Send the bot a message. It shows "typing…" while it works and answers in the chat.
  </Step>
</Steps>

## Environment variables

| Variable | Required | Default | What it does |
| - | - | - | - |
| `CHATCLI_TELEGRAM_BOT_TOKEN` | yes | — | The bot token from BotFather. The adapter starts only when it is set. |
| `CHATCLI_TELEGRAM_ALLOWED_USERS` | no | empty | Numeric user IDs allowed to talk to the bot, separated by commas, spaces or semicolons. Empty accepts **everyone** and logs a warning at start. |
| `CHATCLI_TELEGRAM_HOME_CHANNEL` | no | — | Default chat for [proactive messages](/gateway/proactive-messaging) sent with `@send telegram`. |

Shared settings (voice, images, size limits, the Conversation Hub) are on the [Chat gateway](/gateway/chat-gateway) page.

## Who can reach the bot

<Warning>
  Every message runs the agent with its tools and shell, without confirmations. **Always set `CHATCLI_TELEGRAM_ALLOWED_USERS`** unless the bot is meant to be public.
</Warning>

A message from a user who is not on the list is dropped without a reply; the gateway logs the sender's ID, which is a convenient way to find an ID you forgot to add.

## Messages

* **Text and captions**: the message text, or the caption of a photo or voice note when there is no text.
* **Voice notes and audio files** are downloaded (up to `CHATCLI_GATEWAY_MAX_AUDIO_BYTES`, 20 MB by default) and transcribed before the agent runs; see [Voice messages](/gateway/chat-gateway#voice-messages-transcription).
* **Images**: the largest size of a photo, or a document whose type is an image. One image per message reaches the model.
* **Replies are plain text.** Telegram is sent no formatting mode, so Markdown in a reply shows as typed.
* **Voice replies** arrive as a native voice note when the reply audio is OGG (the default), or as an audio file otherwise, with the text as its caption. See [Voice replies](/gateway/voice-replies).
* **Groups**: a group is one conversation shared by its members. Forum topics are not distinguished; the bot answers in the group.

## Limits

* A reply is cut at **3500 characters** and ends with `…`; the rest is not sent.
* A reply that carries a voice note or an image uses its text as the caption, which Telegram limits to **1024 characters**; no separate text message follows.
* Edited messages, channel posts and button callbacks are ignored.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The bot never answers">
    * `/gateway status` should list `telegram`. If it does not, `CHATCLI_TELEGRAM_BOT_TOKEN` is not set in the environment the daemon started with: set it and run `/gateway stop` then `/gateway start`.
    * Check `~/.chatcli/gateway.log` for a "not in allow-list" line with your user ID.
    * A bot that has a webhook set on the Telegram side cannot also be long-polled. Remove the webhook (Bot API `deleteWebhook`) if the bot was used with another service before.
  </Accordion>

  <Accordion title="The bot ignores messages in a group">
    By default Telegram bots in groups only receive commands and messages that mention them (privacy mode). Turn privacy mode off with BotFather (`/setprivacy`) if the bot should see every message.
  </Accordion>

  <Accordion title="Voice notes are not understood">
    See [Voice messages](/gateway/chat-gateway#voice-messages-transcription): `/gateway status` shows the transcription backend in use.
  </Accordion>
</AccordionGroup>

## See also

<CardGroup cols={2}>
  <Card title="Chat gateway" icon="comments" href="/gateway/chat-gateway">
    How messages run, voice, images, continuity and the other channels.
  </Card>

  <Card title="Voice replies" icon="volume-high" href="/gateway/voice-replies">
    Answer voice with voice, and how each conversation turns it on or off.
  </Card>
</CardGroup>


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