Skip to main content
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.

​
Set it up

1

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….
2

Find your user ID

The allow-list takes numeric user IDs, not usernames. Any “user info” bot in Telegram shows yours.
3

Configure ChatCLI

Put the same lines in your .env to keep them across sessions.
4

Start the gateway

Send the bot a message. It shows “typing…” while it works and answers in the chat.

​
Environment variables

Shared settings (voice, images, size limits, the Conversation Hub) are on the Chat gateway page.

​
Who can reach the bot

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

  • /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.
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.
See Voice messages: /gateway status shows the transcription backend in use.

​
See also

Chat gateway

How messages run, voice, images, continuity and the other channels.

Voice replies

Answer voice with voice, and how each conversation turns it on or off.