Check Telegram connection status

Login to Telegram via QR code. Returns QR image. IMPORTANT: pass the entire result to user without modifications.

Log out from Telegram completely. Revokes the session on Telegram servers (removes it from Settings → Devices), deletes the local session file, and disconnects. After this you must run telegram-login to re-authenticate.

Send a message to a Telegram chat

Read recent messages from a Telegram chat with sender names, dates, media info, and reactions

Search messages in a specific Telegram chat by text

Search messages globally across all public Telegram chats and channels

Edit a previously sent message in Telegram

Delete messages in a Telegram chat

Forward messages between Telegram chats

Get chats with unread messages. Forums show per-topic unread breakdown

List scheduled messages in a Telegram chat

Delete scheduled messages in a Telegram chat

Get replies/comments under a Telegram channel post or discussion message

Get a t.me link to a specific message in a Telegram channel or supergroup

Get unread @mentions addressed to you in a Telegram chat. Marks all mentions as read on the server when all unread mentions fit within the requested limit.

Get messages with unread reactions on your posts in a Telegram chat. Marks all reactions as read on the server when all unread reactions fit within the requested limit.

Translate one or more Telegram messages to a target language (requires Telegram Premium). Consumes account translation quota.

Send a typing/upload indicator to a Telegram chat (or cancel it)

Mark a Telegram chat as read

Query an inline bot (like @gif, @bing) in a chat context and return the compact result list. Returns queryId, cacheTime, and results[{id,type,title?,description?,url?}]. The queryId is typically valid for ~60s and can be passed to telegram-inline-query-send to deliver a chosen result. Bot must be a real bot account

Send an inline bot result to a chat by queryId + resultId (as returned by telegram-inline-query). The queryId is valid for ~60s after the original query, so call this soon after telegram-inline-query. Returns the sent messageId (0 if not extractable from the update).

List the inline/reply keyboard buttons on a Telegram message with their (row, col) indices, type (e.g. KeyboardButtonCallback, KeyboardButtonUrl), label and type-specific fields (callback data as base64, url, switchQuery, userId, copyText, etc). Helper for telegram-press-button — call this first to discover indices and filter by type before pressing. Returns markupType='none' and empty buttons when the message has no keyboard

Press an inline keyboard callback button on a message. Identify the button by (row, column) from its replyMarkup, or pass raw callback_data as base64. URL, switch-inline, game and 2FA-password buttons are rejected with a clear error. Returns the bot's callback answer: {alert?, hasUrl?, nativeUi?, message?, url?, cacheTime}

Initialize the polling cursor by fetching the current Telegram updates state {pts, qts, date, seq, unreadCount}. Call once before telegram-get-updates; then persist {pts, qts, date} in your agent state and feed them into telegram-get-updates. The MCP server does NOT store the cursor — you do.

Fetch new messages, deleted messages, and other updates since a previously-known {pts, qts, date} cursor (from telegram-get-state or a prior call). Returns compact newMessages[], deletedMessageIds[], otherUpdates[] (className only), and the new cursor state. isFinal=false means more updates are queued — call again with the returned state. If Telegram reports the gap is too long, a fallback hint is returned suggesting to resync via telegram-read-messages per chat. Cursor is stateless — the agent must persist {pts, qts, date} between calls.

Fetch new messages and updates for a single channel/supergroup since a known per-channel pts cursor. Separate from the global cursor used by telegram-get-updates. Returns compact newMessages[], otherUpdates[], and new {pts, isFinal, timeout?}. If the channel gap is too long, Telegram returns a dialog snapshot — this tool forwards it and hints to resync via telegram-read-messages. Cursor is stateless — the agent stores pts.

For a channel post with comments enabled, returns the linked discussion-group info: discussionGroupId, discussionMsgId, unreadCount, readInboxMaxId, readOutboxMaxId, topMessage. Use discussionGroupId + discussionMsgId with telegram-send-message (replyTo=discussionMsgId) to post a comment.

List groups that can be linked as a discussion group to a channel you admin. Helper for channel admins setting up comment threads.

List who has read a message in a small group (≤100 members, ≤7 days old). Returns readers with userId, readAt timestamp. Does NOT work for channels or groups over 100 members (CHAT_TOO_BIG).

Vote in a poll by option index (single or multi-choice). Empty array retracts vote.

Get aggregated poll results: vote counts, percentages, quiz answer status

List users who voted for specific poll options (public polls only, paginated)

Close a poll permanently. This is a one-way operation — closed polls cannot be reopened.

Get when your recipient read your outgoing message in a private chat. Returns null/Not read yet if unread. Errors if the other side disabled read receipts (YOUR_PRIVACY_RESTRICTED / USER_PRIVACY_RESTRICTED).

List Telegram chats with unread counts, type indicators, and contact status

Search for Telegram chats, users, or channels by name or username. Returns description and member count

Get detailed info about a Telegram chat including name, type, members, description, and forum status

Get members of a Telegram group or channel

Get the current user's role in a chat (creator, admin, or member)

Create a new Telegram group or supergroup

Join a Telegram group or channel by username or invite link

Leave a Telegram group or channel

Invite users to a Telegram group or channel

Kick a user from a Telegram group (removes without permanent ban)

Ban a user from a supergroup or channel (permanent until unbanned)

Unban a previously banned user from a supergroup or channel

Edit a group's title, description, or photo

Promote a user to admin in a supergroup or channel with full permissions

Archive or unarchive a Telegram dialog (moves to/from the Archive folder)

Pin or unpin a Telegram dialog in the dialog list

Mark a Telegram dialog as unread (or clear the unread mark)

Get the admin action log (recent event history) of a supergroup or channel. Includes bans, edits, pins, and role changes

Remove admin rights from a user in a supergroup or channel

Set the default permissions for all non-admin members of a group, supergroup, or channel. Omitted flags keep their current state; true = allowed, false = denied

Set slow mode for a supergroup (minimum interval between messages per user). Allowed values: 0, 10, 30, 60, 300, 900, 3600 seconds (0 disables slow mode)

Enable or disable author signatures on broadcast channel posts. Channel admin required; not supported for supergroups

Enable or disable aggressive anti-spam filtering in a supergroup. Supergroup only (not broadcast channels); requires admin with ban_users permission

Enable or disable forum/topics mode in a supergroup. Supergroup only; requires creator or admin. WARNING: disabling removes ALL existing topics — pass confirm=true to proceed with disable

Toggle pre-history visibility for new members in a supergroup. When hidden=true, new joiners cannot see messages posted before they joined. Supergroup only; requires admin

Approve or deny a pending join request for a supergroup or channel (basic groups are not supported). Admin with invite_users permission required

Create a new forum topic in a forum-enabled supergroup

Edit a forum topic — rename, change icon emoji, open/close, or show/hide

Get broadcast channel statistics: followers, views/shares/reactions per post & story, notification percent, recent post interactions. Broadcast channels only (use telegram-get-megagroup-stats for supergroups). Admin rights required; some channels may require Telegram Premium to expose stats

Get supergroup statistics: members, messages, viewers, posters (current vs previous period), top posters/admins/inviters. Supergroups only (use telegram-get-broadcast-stats for broadcast channels). Admin rights required. Telegram rate-limits this endpoint to roughly 1 request per 30 minutes per channel — expect FLOOD_WAIT on rapid repeat calls

Delete a forum topic and all its message history

Send a file (photo, document, video, etc.) to a Telegram chat

Download media from a Telegram message to a local file

Download profile photo of a Telegram user, group, or channel. Returns inline image or saves to file

Fetch Telegram's web-page preview metadata (type, title, description, site name) for a URL

Send a voice note (audio recording) to a Telegram chat. Shows as a voice message with waveform UI.

Send a video note (round-shaped short video) to a Telegram chat. Shows as a circular video in the UI.

Send a contact card (phone number + name) to a Telegram chat.

Send an animated dice/game emoji to a Telegram chat. Returns the server-rolled value — useful for games, coin-flips, random picks. Values: 🎲🎯🎳 = 1-6, 🏀⚽ = 1-5, 🎰 = slot combo 1-64.

Send a geographic location to a Telegram chat. Static pin by default; set livePeriod to share a live-updating location for N seconds.

Send a venue card (point-of-interest with title and address) to a Telegram chat.

Send an album (group) of 2-10 photos as a single grouped message. Media type is auto-detected by file extension — videos are supported by the underlying TL call but are not covered by v1.29.0 mock tests, so uniform-photo albums are the safer choice until a live checkpoint. Uploads are serial per item: expect ≈4-10s for 10 mid-size photos, 15-40s for 10 large videos. Prefer ≤5 items or photos when low latency matters.

Get your Telegram contacts list with phone numbers

Get detailed profile info of a Telegram user including bio, birthday, premium status, business info and more

Get incoming messages from non-contacts (contact requests). Shows who messaged you without being in your contacts, with message preview

Add a user to your Telegram contacts. Use this to accept contact requests from non-contacts

Block a Telegram user. Blocked users cannot send you messages

Unblock a previously blocked Telegram user

Report a chat as spam to Telegram

Send emoji reaction(s) to a message. Supports multiple reactions and adding to existing ones. Omit emoji to remove all reactions

Get detailed reaction info for a message: which reactions, counts, and who reacted (when visible)

Set the default emoji reaction used in quick-reaction menus across Telegram

Get the list of most popular emoji reactions available on Telegram

Set which reactions are available in a chat. type='all' allows all standard emoji (set allowCustom=true to also permit custom emoji for Premium users), type='some' restricts to a specific emoji list, type='none' disables reactions entirely. Requires admin

Get the list of emoji reactions the current account used recently

Send a paid reaction (★ Stars) on a channel post. Stars are spent from your balance. Optional private flag controls leaderboard visibility.

Change leaderboard visibility of your paid reaction on a specific channel post (Layer 198 API).

Get your current default paid reaction privacy setting.

Request server-side transcription of a voice note or video note (Telegram Premium feature). Returns immediately with transcriptionId — if pending:true, call telegram-get-transcription to poll for completion.

Poll for updated transcription result. Calls the same endpoint as telegram-transcribe-audio — Telegram guarantees idempotency (returns same transcriptionId with updated text once processing completes).

Rate transcription quality (good/poor) to improve Telegram speech-to-text.

Get fact-check annotations on channel messages. Fact-checks are added by independent fact-checkers in supported countries. Most messages will show no fact-check.

Add or update a fact-check annotation. Requires fact-checker privileges (limited to independent verifiers in supported countries).

Remove a fact-check annotation. Requires fact-checker privileges.

Pin a message in a Telegram chat