# Telegram: start here (/en/docs/tg)

`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](#choose-how-to-start)
- [Try it after connecting](#try-it-after-connecting)
- [Find the guide for your task](#find-the-guide-for-your-task)

## Choose how to start [#choose-how-to-start]

### Connect through your agent [#connect-through-your-agent]

If you use Codex, Claude Code, Cursor, Gemini CLI or Hermes, open the
[agent installation guide](/llms.mdx/docs/installation/content.md#tg). 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](/llms.mdx/docs/agents/content.md). Apps that use an MCP server have a
[separate MCP guide](/llms.mdx/docs/agents/content.md#mcp-and-skills).

### Start in a terminal [#start-in-a-terminal]

Open [the installation guide](/llms.mdx/docs/installation/content.md#tg) 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.

```sh
tg personal setup
```

```sh
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](https://my.telegram.org/apps). 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](/llms.mdx/docs/tg/sessions/content.md).

> **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](/llms.mdx/docs/tg/sessions/content.md#the-app-from-mytelegramorg).

## Try it after connecting [#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](/llms.mdx/docs/tg/security/content.md).

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](/llms.mdx/docs/tg/search/content.md).

## Find the guide for your task [#find-the-guide-for-your-task]

| Task | Guide |
|---|---|
| Read, search and send messages | [Everyday commands](/llms.mdx/docs/tg/usage/content.md) |
| Log in, log out or add another account | [Login and profiles](/llms.mdx/docs/tg/sessions/content.md) |
| Search local history and export conversations | [Message archive](/llms.mdx/docs/tg/archive/content.md) |
| Write a precise search query, filters or dates | [Message search](/llms.mdx/docs/tg/search/content.md) |
| Follow questions and membership in a group | [Your groups](/llms.mdx/docs/tg/groups/content.md) |
| Find a ready request for your agent | [Usage recipes](/llms.mdx/docs/tg/recipes/content.md) |
| Check what Telegram bots currently support | [Bots: available capabilities](/llms.mdx/docs/tg/bot/content.md) |
| Fix an error | [Troubleshooting](/llms.mdx/docs/tg/troubleshooting/content.md) |
| Look up an exact command or option | [Command reference](/llms.mdx/docs/tg/commands/content.md) |
| Manage contacts, aliases and private notes | [People](/llms.mdx/docs/tg/people/content.md) |
| Compare activity and inspect ranking evidence | [Rankings](/llms.mdx/docs/tg/rankings/content.md) |
| Send, download and read files | [File commands](/llms.mdx/docs/tg/usage/content.md) |
| Transcribe voice messages locally | [Voice commands](/llms.mdx/docs/tg/usage/content.md) |
| Configure optional model APIs | [Model settings](/llms.mdx/docs/tg/configuration-reference/content.md) |
| Restrict reads, writes and confirmations | [Permissions](/llms.mdx/docs/tg/permissions/content.md) |
| Choose a personal or bot profile | [Profiles and bots](/llms.mdx/docs/tg/profiles/content.md) |
| Look up setting types and precedence | [Configuration reference](/llms.mdx/docs/tg/configuration-reference/content.md) |

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.
