Telegram

Telegram CLI client for AI agents

Connect your Telegram account to an agent, or use it from a terminal.

tg is a command-line tool that lets your AI agent read Telegram, find messages and help you reply. It works with your personal account and its chats. You can also use it yourself with terminal commands. It runs on Windows, macOS and Linux.

You are in the Telegram documentation. Use the messenger switch at the top to open MAX.

On this page

Choose how to start

Connect through your agent

If you use Codex, Claude Code, Cursor, Gemini CLI or Hermes, open the agent installation guide. Copy the short request: your agent will install the tool, help you log in and check the connection. You scan the QR code and confirm the login.

Then follow the guide for your agent. Apps that use an MCP server have a separate MCP guide.

Start in a terminal

Open the installation guide and choose the terminal instructions. After installing, run guided setup: it helps with app registration and login, checks your account and five chats, and installs agent skills. It reuses an existing session; downloading history remains a separate choice.

tg personal setup
tg personal chats list --limit 5

personal is the profile name: choose any name at the first login and repeat it in every command.

First, the command asks for your phone number and a code sent in Telegram to obtain api_id and api_hash from my.telegram.org. Then it displays the QR code for account login. Open Telegram on your phone → Settings → Devices → Link Desktop Device and scan it. Wait for Logged in as … before listing chats. Complete login steps.

What is a Telegram application and why is it needed?

This is a registration record for the program connecting to Telegram, here the tg CLI. You fill in a form, without writing or downloading another application. Telegram issues api_id and api_hash to identify the program; QR or code confirmation then grants access to your account. The command can register or retrieve these credentials for you. Explanation and browser fallback.

Try it after connecting

  • Catch up on unread messages. Ask which chats are waiting for your reply.
  • Recall agreements. Ask what you promised this week and what you are waiting for from others.
  • Find a message. Ask for a conversation, date, link or file.
  • Get help replying. Give your agent context and ask it to draft or send a message.

Reading does not mark messages as read. Sending, deleting and other changes require separate commands. You can restrict the agent's access: see access and safety.

Word search asks both the local archive and the messenger by default (--backend both); use --backend archive for local-only results. The query language is strict Lucene and does not correct typos; --discover also tries close spellings in the local archive. Prepare saved history before archive-only search, counting or rankings, and check coverage before treating an empty result as proof that a message is absent. See search.

Find the guide for your task

TaskGuide
Read, search and send messagesEveryday commands
Log in, log out or add another accountLogin and profiles
Search local history and export conversationsMessage archive
Write a precise search query, filters or datesMessage search
Follow questions and membership in a groupYour groups
Find a ready request for your agentUsage recipes
Check what Telegram bots currently supportBots: available capabilities
Fix an errorTroubleshooting
Look up an exact command or optionCommand reference
Manage contacts, aliases and private notesPeople
Compare activity and inspect ranking evidenceRankings
Send, download and read filesFile commands
Transcribe voice messages locallyVoice commands
Configure optional model APIsModel settings
Restrict reads, writes and confirmationsPermissions
Choose a personal or bot profileProfiles and bots
Look up setting types and precedenceConfiguration reference

The left sidebar keeps Getting started and expandable Telegram/MAX guides available. The right sidebar lists sections of the current page. Use the command reference when you need an exact option; installation and everyday tasks are enough to get started.