# Tools Reference

MCP Telegram provides a comprehensive tool set organized by category. All tools are auto-discoverable — your AI client will see them with full parameter descriptions when connected.

## Auth

| Tool | Description |
|------|-------------|
| `telegram-status` | Check connection status and get account info |
| `telegram-login` | Generate QR code for authentication |
| `telegram-logout` | Revoke session on Telegram and delete the local session file |

## Messaging

| Tool | Description |
|------|-------------|
| `telegram-send-message` | Send a message to any chat (user, group, channel) |
| `telegram-edit-message` | Edit a previously sent message |
| `telegram-delete-message` | Delete one or more messages |
| `telegram-forward-message` | Forward messages between chats |
| `telegram-send-scheduled` | Schedule a message for later delivery |
| `telegram-send-typing` | Send a typing / upload action indicator |
| `telegram-translate-message` | Translate one or more messages to a target language (Premium; consumes translate quota) |
| `telegram-get-message-link` | Get a public t.me link to a message |

## Scheduled

| Tool | Description |
|------|-------------|
| `telegram-get-scheduled` | List scheduled messages in a chat |
| `telegram-delete-scheduled` | Delete one or more scheduled messages |

## Reading

| Tool | Description |
|------|-------------|
| `telegram-list-chats` | List your chats with filters (users, groups, channels) |
| `telegram-read-messages` | Read recent messages from a chat with pagination |
| `telegram-search-messages` | Search messages in a specific chat by keyword |
| `telegram-search-global` | Search messages across all chats at once |
| `telegram-search-chats` | Find chats by name or description |
| `telegram-get-unread` | Get all chats with unread messages and counts |
| `telegram-mark-as-read` | Mark a chat as read |
| `telegram-get-replies` | Read comments/replies under a channel post |
| `telegram-get-unread-mentions` | List unread messages that mention you in a chat (marks them as read on the server) |
| `telegram-get-unread-reactions` | List unread reactions on your messages in a chat (marks them as read on the server) |
| `telegram-get-saved-dialogs` | List per-peer folders inside Saved Messages |

## Drafts

| Tool | Description |
|------|-------------|
| `telegram-save-draft` | Save a text draft in a chat (empty clears the draft) |
| `telegram-get-drafts` | List all chats with saved drafts |
| `telegram-clear-drafts` | Clear a chat's draft, or wipe drafts in all chats (requires `confirmAllChats: true`) |

## Forum Topics

| Tool | Description |
|------|-------------|
| `telegram-list-topics` | List topics in a forum group |
| `telegram-read-topic-messages` | Read messages from a specific topic |
| `telegram-create-topic` | Create a new topic in a forum group |
| `telegram-edit-topic` | Rename, close, hide, or update an existing topic |
| `telegram-delete-topic` | Delete a topic and its history |

## Polls

| Tool | Description |
|------|-------------|
| `telegram-create-poll` | Create a poll or quiz in a chat |

## Poll Interaction (v1.31.0)

| Tool | Description |
|------|-------------|
| `telegram-vote-poll` | Vote in a poll by option index. Empty `optionIndexes: []` retracts your vote |
| `telegram-get-poll-results` | Get aggregated results: vote counts, percentages, quiz correct-answer flags |
| `telegram-get-poll-voters` | List users who voted for specific options (public polls only, paginated) |
| `telegram-close-poll` | Permanently close a poll — irreversible, no further votes allowed |

## Reactions

| Tool | Description |
|------|-------------|
| `telegram-send-reaction` | React to a message with an emoji |
| `telegram-get-reactions` | Get reactions on a message |
| `telegram-set-default-reaction` | Set your account's default quick-reaction emoji |
| `telegram-get-top-reactions` | List Telegram's top (popular) reaction emojis |
| `telegram-get-recent-reactions` | List emojis you recently used as reactions |

## Paid Reactions (v1.31.0)

| Tool | Description |
|------|-------------|
| `telegram-send-paid-reaction` | Send ★ Stars as a paid reaction on a channel post (`count` 1–2500, optional `private` flag) |
| `telegram-toggle-paid-reaction-privacy` | Toggle leaderboard visibility of your paid reaction on a specific post |
| `telegram-get-paid-reaction-privacy` | Get your current default paid reaction privacy setting |

## Audio Transcription (v1.31.0)

| Tool | Description |
|------|-------------|
| `telegram-transcribe-audio` | Start server-side transcription of a voice/video note (Telegram Premium). Returns `transcriptionId`; if `pending:true` poll with `telegram-get-transcription` |
| `telegram-get-transcription` | Poll for updated transcription status — idempotent, same `transcriptionId`, updated text once complete |
| `telegram-rate-transcription` | Rate transcription quality as good or poor to improve Telegram speech-to-text |

## Fact-check (v1.31.0)

| Tool | Description |
|------|-------------|
| `telegram-get-fact-check` | Fetch fact-check annotations on up to 100 channel messages; most messages have no annotation |
| `telegram-edit-fact-check` | Add or update a fact-check annotation (requires fact-checker privileges) |
| `telegram-delete-fact-check` | Remove a fact-check annotation (requires fact-checker privileges) |

## Stickers

| Tool | Description |
|------|-------------|
| `telegram-send-sticker` | Send a sticker to a chat |
| `telegram-get-installed-stickers` | List your installed sticker packs |
| `telegram-get-recent-stickers` | Show recently used stickers |
| `telegram-get-sticker-set` | Browse stickers in a specific pack |
| `telegram-search-sticker-sets` | Search Telegram's sticker catalog |

## Media

| Tool | Description |
|------|-------------|
| `telegram-send-file` | Send a file, photo, or document |
| `telegram-download-media` | Download media from a message |
| `telegram-get-profile-photo` | Get a user's or chat's profile photo |
| `telegram-get-web-preview` | Preview a URL's title/description/site before sending |

## Rich Media Sending (v1.29.0)

| Tool | Description |
|------|-------------|
| `telegram-send-voice` | Send a voice note (OGG/Opus recommended). Shows as a waveform UI. |
| `telegram-send-video-note` | Send a round video message (MP4, square recommended, ≤60s) |
| `telegram-send-location` | Send a geographic location; optional `livePeriod` (60–86400s) makes it live-updating |
| `telegram-send-venue` | Send a venue card (title, address, lat/long) |
| `telegram-send-contact` | Send a contact card (phone, first/last name, optional vCard) |
| `telegram-send-dice` | Send an animated dice/game emoji (🎲🎯🎰🏀⚽🎳) and return the rolled value |
| `telegram-send-album` | Send 2–10 grouped photos/videos as a single album message |

All `filePath` arguments must be absolute local filesystem paths. URLs, UNC shares, path-traversal (`..`), and POSIX pseudo-filesystems (`/proc`, `/sys`, `/dev`, `/run`) are rejected.

## Groups

| Tool | Description |
|------|-------------|
| `telegram-create-group` | Create a new group |
| `telegram-edit-group` | Edit group title, description, or photo |
| `telegram-invite-to-group` | Invite users to a group |
| `telegram-join-chat` | Join a group or channel via invite link |
| `telegram-leave-group` | Leave a group or channel |
| `telegram-kick-user` | Remove a user from a group |
| `telegram-ban-user` | Ban a user from a group |
| `telegram-unban-user` | Unban a user |
| `telegram-set-admin` | Promote a user to admin with custom permissions |
| `telegram-remove-admin` | Remove admin rights from a user |
| `telegram-get-my-role` | Check your role and permissions in a group |
| `telegram-set-chat-permissions` | Set default banned rights for all members (omitted flags keep their current state) |
| `telegram-set-slow-mode` | Set slow-mode interval in a supergroup |
| `telegram-get-admin-log` | Read the moderation/admin event log |

## Chat Info

| Tool | Description |
|------|-------------|
| `telegram-get-chat-info` | Get detailed chat info (title, members, photo, etc.) |
| `telegram-get-chat-members` | List members of a group or channel |
| `telegram-get-chat-folders` | List your chat folders |

## Invite Links

| Tool | Description |
|------|-------------|
| `telegram-create-invite-link` | Create an invite link with optional limits |
| `telegram-get-invite-links` | List existing invite links |
| `telegram-revoke-invite-link` | Revoke an invite link |

## Contacts

| Tool | Description |
|------|-------------|
| `telegram-get-contacts` | List your contacts |
| `telegram-add-contact` | Add a new contact |
| `telegram-get-contact-requests` | View pending contact requests |

## Moderation

| Tool | Description |
|------|-------------|
| `telegram-block-user` | Block a user |
| `telegram-unblock-user` | Unblock a user |
| `telegram-report-spam` | Report spam |

## Profiles

| Tool | Description |
|------|-------------|
| `telegram-get-profile` | Get a user's profile info |
| `telegram-update-profile` | Update your own profile (name, bio, username) |

## Account

| Tool | Description |
|------|-------------|
| `telegram-get-sessions` | List active sessions (devices) |
| `telegram-terminate-session` | Terminate a session |
| `telegram-set-privacy` | Configure privacy settings (phone, last seen, etc.) |
| `telegram-set-auto-delete` | Set auto-delete timer for a chat |

## Pinning

| Tool | Description |
|------|-------------|
| `telegram-pin-message` | Pin a message in a chat |
| `telegram-unpin-message` | Unpin a message or all messages |

## Chat Settings

| Tool | Description |
|------|-------------|
| `telegram-mute-chat` | Mute or unmute chat notifications |
| `telegram-archive-chat` | Move a chat to/from the Archive folder |
| `telegram-pin-chat` | Pin or unpin a dialog in the chat list |
| `telegram-mark-dialog-unread` | Mark a dialog as unread or clear the unread flag |

## Admin Toggles & Customization

| Tool | Description |
|------|-------------|
| `telegram-toggle-channel-signatures` | Toggle post signatures on a channel |
| `telegram-toggle-anti-spam` | Toggle native anti-spam in a supergroup (admin with `ban_users`) |
| `telegram-toggle-forum-mode` | Enable/disable forum mode (disabling removes all topics; requires `confirm: true`) |
| `telegram-toggle-prehistory-hidden` | Hide or show pre-history for new supergroup members |
| `telegram-set-chat-reactions` | Configure allowed reactions on a chat (`all` / `some` / `none`) |
| `telegram-approve-join-request` | Approve or reject a chat join request |

## Stats

| Tool | Description |
|------|-------------|
| `telegram-get-broadcast-stats` | Get channel stats (pass `includeGraphs: true` for raw series; Premium admin may be required) |
| `telegram-get-megagroup-stats` | Get supergroup stats (Telegram rate-limits to ~1 req/30 min per channel) |

## Inline Bots & Buttons

| Tool | Description |
|------|-------------|
| `telegram-inline-query` | Query an inline bot in a chat context (queryId TTL ≈ 1 min) |
| `telegram-inline-query-send` | Send an inline bot result by queryId + result id |
| `telegram-press-button` | Press a callback button on a message by row/col or raw data |
| `telegram-get-message-buttons` | List a message's reply-markup buttons with indices and types |

## Real-Time Updates (Polling)

Cursors are client-owned — the agent stores `{pts, qts, date}` between calls and passes them in.

| Tool | Description |
|------|-------------|
| `telegram-get-state` | Initialize a polling cursor (`pts`, `qts`, `date`, `seq`) |
| `telegram-get-updates` | Fetch global updates since a known cursor (falls back to history hint on `DifferenceTooLong`) |
| `telegram-get-channel-updates` | Fetch per-channel updates since a known channel cursor |

## Stories

| Tool | Description |
|------|-------------|
| `telegram-get-all-stories` | List stories across peers with pagination state |
| `telegram-get-peer-stories` | List stories posted by one peer |
| `telegram-get-stories-by-id` | Fetch specific story items by id |
| `telegram-get-story-views` | List views on your own stories (Premium for full stats) |

## Stories (write, v1.30.0)

| Tool | Description |
|------|-------------|
| `telegram-send-story` | Publish a photo or video story with privacy controls (everyone/contacts/close_friends/selected), period, pinning, no-forward flag |
| `telegram-edit-story` | Edit an existing story: replace media, update caption, or change privacy rules |
| `telegram-delete-stories` | Delete one or more stories (irreversible; requires `confirm: true`) |
| `telegram-react-to-story` | React to a story with an emoji; pass `""` to remove the reaction |
| `telegram-export-story-link` | Get a shareable `t.me/…` URL for a public story |
| `telegram-read-stories` | Mark stories as seen up to a given story ID |
| `telegram-toggle-story-pinned` | Pin or unpin stories in profile highlights |
| `telegram-toggle-story-pinned-to-top` | Pin stories to the top of the pinned row; pass `[]` to clear |
| `telegram-activate-stealth-mode` | Hide your story views retroactively and/or for 25 min (Telegram Premium required) |
| `telegram-get-stories-archive` | Fetch auto-archived (expired) stories, paginated |
| `telegram-report-story` | Report a story via the multi-step option flow |

## Discussion (v1.30.0)

| Tool | Description |
|------|-------------|
| `telegram-get-discussion-message` | For a channel post with comments, get discussion-group info (discussionGroupId, discussionMsgId, unreadCount) |
| `telegram-get-groups-for-discussion` | List groups eligible to link as discussion group to a channel you admin |

## Read Receipts (v1.30.0)

| Tool | Description |
|------|-------------|
| `telegram-get-message-read-participants` | List who has read a message in a small group (≤100 members, ≤7 days old) |
| `telegram-get-outbox-read-date` | Get when your recipient read your outgoing private message |

## Profile (write, v1.32.0)

| Tool | Description |
|------|-------------|
| `telegram-set-emoji-status` | Set custom animated emoji status next to your name. Pass `documentId` (from `telegram-list-emoji-statuses`) or `collectibleId`; omit both to clear. Optional `untilUnix` expiry. **Requires Telegram Premium.** |
| `telegram-list-emoji-statuses` | Browse emoji statuses available for your account. `kind`: `default`, `recent`, `channel_default`, `collectible`. Returns `documentId`, `until`, collectible `title`/`slug`. |
| `telegram-clear-recent-emoji-statuses` | Clear the "recent" emoji status picker list. |
| `telegram-set-profile-color` | Set name color (`forProfile=false`) or profile background color + pattern (`forProfile=true`, Premium). `color` 0–6 free, 7–20 Premium. Omit `color` to reset. |
| `telegram-set-birthday` | Set birthday on profile. `day` + `month` required; `year` optional (omit to hide age). `clear=true` removes. |
| `telegram-set-personal-channel` | Feature a channel on your profile. Pass `channelId` or `@username`. `clear=true` removes. |
| `telegram-set-profile-photo` | Upload static (JPEG/PNG) or animated (MP4, square, ≤10s) avatar. `fallback=true` sets it as the privacy-fallback photo. |
| `telegram-delete-profile-photo` | Delete profile photos by photo IDs (stringified longs). Internally fetches photo history to resolve `InputPhoto`; IDs not found are listed in `missing`. |

## Business (v1.32.0)

Requires **Telegram Business** subscription unless noted otherwise.

| Tool | Description |
|------|-------------|
| `telegram-get-business-chat-links` | List your Telegram Business chat links (read-only; no Business subscription required to read). |
| `telegram-create-business-chat-link` | Create a `t.me/m/...` deep-link with pre-filled message and optional admin `title`. Returns JSON with `link`, `slug`, `message`, `views`. |
| `telegram-edit-business-chat-link` | Update an existing link by `slug`. Same options as create. |
| `telegram-delete-business-chat-link` | Delete a link by `slug`. |
| `telegram-resolve-business-chat-link` | Resolve a `slug` to see who the link opens a chat with and the pre-filled message. No Business subscription needed. |
| `telegram-set-business-hours` | Set weekly work hours: `timezone` (IANA) + `schedule` array of `{day, openFrom, openTo}` in HH:MM. `clear=true` disables. |
| `telegram-set-business-location` | Set address ± geo coordinates. `clear=true` removes. |
| `telegram-set-business-greeting` | Auto-reply for new conversations. `shortcutId` (from `telegram-get-quick-replies`), `audience` enum, `noActivityDays`, optional include/exclude user lists. `clear=true` disables. |
| `telegram-set-business-away` | Auto-reply when offline. `schedule`: `always`, `outside_hours`, or `custom` (requires `customFrom`/`customTo` Unix timestamps). `offlineOnly` flag. Same audience model as greeting. `clear=true` disables. |
| `telegram-set-business-intro` | Intro card for new users: `title` (≤32 chars) + `description` (≤70 chars) + optional sticker (requires all three: `stickerId`, `stickerAccessHash`, `stickerFileReference`). `clear=true` removes. |

## Boosts

| Tool | Description |
|------|-------------|
| `telegram-get-my-boosts` | List boost slots assigned by your account |
| `telegram-get-boosts-status` | Boost status for a channel/supergroup |
| `telegram-get-boosts-list` | List boosters for a channel (admin) |

## Opt-In (env-gated)

These tools are only registered when the corresponding environment flag is set.

| Tool | Env flag |
|------|----------|
| `telegram-get-group-call` | `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1` |
| `telegram-get-group-call-participants` | `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1` |
| `telegram-get-stars-status` | `MCP_TELEGRAM_ENABLE_STARS=1` |
| `telegram-get-stars-transactions` | `MCP_TELEGRAM_ENABLE_STARS=1` |
| `telegram-get-quick-replies` | `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1` |
| `telegram-get-quick-reply-messages` | `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1` |

---

::: tip
You don't need to memorize these tools. Just describe what you want in natural language — your AI assistant will pick the right tool automatically.
:::
