Chatroost — unofficial Telegram MCP server

Create a poll in a Telegram chat (multiple choice or quiz mode)

Create a new forum topic in a forum-enabled supergroup

Delete a Telegram Business chat link by its slug. Requires Telegram Business subscription.

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

Delete a Telegram chat folder by its ID. Chats inside the folder are not deleted — they remain in All Chats. System folders (0 = All Chats, 1 = Archive) cannot be deleted.

Delete messages in a Telegram chat

Delete one or more profile photos by their photo IDs. Photo IDs are the ones telegram-get-profile-photo returns. Returns which IDs were deleted and which were not found.

Delete scheduled messages in a Telegram chat

Delete one or more of your own stories. This action is irreversible and requires confirm:true.

Delete a forum topic and all its message history

Download media from a Telegram message to a local file

Edit an existing Telegram Business chat link by its slug (the trailing segment after t.me/m/). Returns JSON with updated fields. Requires Telegram Business subscription.

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

Edit an existing Telegram chat folder by its ID (from telegram-get-chat-folders). Only pass fields you want to change — omitted fields keep their current values.

Edit a group's title, description, or photo

Edit a previously sent message in Telegram

Edit an existing story: replace media, update caption ('' clears it), or change privacy rules.

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

Get a shareable t.me/… URL for a public story.

Forward messages between Telegram chats

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

Fetch active stories from contacts/channels the user follows. Pagination via 'next' + 'state' — pass the returned state back on the next call with next:true to load more. Use hidden:true to read stories from muted/archived peers. Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) without raw media blobs.

List all available Telegram Star Gifts that can be sent to other users. Returns gift ID, cost in Stars, conversion value, availability (for limited gifts), and upgrade cost. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List the boosts applied to a channel/supergroup (premium.GetBoostsList). Returns paginated boost entries with id, userId (or undefined for anonymous gift boosts), date, expires, flags (gift, giveaway, unclaimed), optional giveawayMsgId, usedGiftSlug, multiplier, and stars. Requires channel admin permissions. Supports pagination via nextOffset and an optional gifts filter to show only gift boosts. Read-only.

Fetch the boost status of a channel/supergroup (premium.GetBoostsStatus). Returns current boost level, total boosts, progress to next level (currentLevelBoosts/nextLevelBoosts), giftBoosts, premiumAudience ratio, public boostUrl, and whether the current user is boosting (myBoost + myBoostSlots). Also includes any prepaidGiveaways attached to the chat. Read-only.

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

List Telegram Business chat links configured for the account. Each entry includes the t.me/... link, the prefilled message, optional title (admin-facing label), views count, and entityCount. Requires Telegram Business — returns empty list when none configured.

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 instead, and this tool forwards it. The server does not store the cursor; each call takes the pts returned by the previous one.

Get list of your Telegram chat folders (filters) with their names and chat counts

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

Get members of a Telegram group or channel

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

Get your Telegram contacts list with phone numbers

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.

Get all saved message drafts across chats

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.

Get your account-level global privacy settings: whether new non-contacts are auto-archived/muted, whether archived chats are kept unmuted, whether read receipts are hidden, and whether non-contacts must have Premium to message you.

Fetch metadata + an optional initial slice of participants for the active group call (voice/video chat) attached to a chat (phone.GetGroupCall). Returns call info (id, accessHash, participantsCount, title, scheduleDate, recordStartDate, streamDcId, flags) plus a participant slice (peer, date, muted/left/self flags, source, volume, video/presentation indicators) and participantsNextOffset. Pass limit:0 (default) for metadata only. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1. Read-only.

List participants of the active group call (voice/video chat) attached to a chat with pagination (phone.GetGroupParticipants). Looks up the chat's current InputGroupCall automatically, then returns {count, participants[], nextOffset?, version}. Each participant includes peer, date, source, volume, muted/self/left/videoJoined flags, raise-hand rating, about text, and hasVideo/hasPresentation indicators. Pass offset from a prior call's nextOffset to paginate; pass ids (user/channel peers) or sources to filter to specific participants. Opt-in: register only when MCP_TELEGRAM_ENABLE_GROUP_CALLS=1.…

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

List all sticker sets installed by the user. Returns pack titles and short names.

Get list of invite links for a group or channel. By default returns links created by the current account; pass adminId to query another admin's links

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

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

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

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

List the user's premium boost slots (premium.GetMyBoosts). Each entry includes slot index, the peer it currently boosts (if any), the date the boost was applied, expiration timestamp, and cooldownUntilDate (when a slot can be reassigned). Premium users have multiple slots; non-Premium users typically have a single slot. Read-only.

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

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

Get your current default paid reaction privacy setting.

Fetch currently active stories posted by a specific peer (user/channel). Returns compact story metadata (id, date, expireDate, caption, mediaType, counters) with media type className only — no raw media blobs. The media itself is not included; telegram-download-media returns it by story id.

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

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

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

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

Fetch the list of quick-reply shortcuts configured for the user account (messages.GetQuickReplies). Each entry has {shortcutId, shortcut, topMessage, count} ; telegram-get-quick-reply-messages takes the shortcutId and shows the stored messages. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string and the server may respond with {notModified:true} if nothing changed. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.

Fetch messages stored under a quick-reply shortcut (messages.GetQuickReplyMessages). `shortcutId` comes from telegram-get-quick-replies. Optional `ids` narrows to specific message ids within the shortcut. Optional `hash` implements Telegram's hash-based diff: pass the last-known aggregate hash as a decimal string — the server may respond with {notModified:true, count} if nothing changed. Returns compact {count, messages[{id, date, text, isService, fromId?, replyToMsgId?}]}. Opt-in: register only when MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1. Read-only.

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

Get the list of emoji reactions the current account used recently

Get recently used stickers. Returns each sticker with its list index and associated emoji

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

Get Saved Messages dialogs (Telegram's per-sender grouping of messages forwarded to your Saved Messages)

List the songs pinned to a user's profile (users.GetSavedMusic) — the tracks behind the music row on a Telegram profile. Returns count plus tracks with title, performer, duration, fileName, mimeType and size; element 0 is the track shown on the profile. Defaults to your own profile. Supports pagination via offset/limit and returns nextOffset when more remain. Read-only.

List Star Gifts received by a user or chat. Pass 'me' for your own gifts. Supports pagination via offset/nextOffset and filtering flags. Returns gift ID, kind (regular/unique), stars cost, from-peer, date, and upgrade eligibility. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List scheduled messages in a Telegram chat

Get list of all active Telegram sessions (logged-in devices) with device info, IP, and last active time

Fetch the current Telegram Stars balance and recent activity for a peer (payments.GetStarsStatus). Pass 'me' / '@me' (or the user's own id) to inspect your own wallet, or a bot/channel peer you own/administrate. Returns {balance:{amount,nanos}, subscriptions?[], subscriptionsNextOffset?, subscriptionsMissingBalance?, history?[], nextOffset?}. Each transaction has id, stars, date, peer (kind: appStore|playMarket|premiumBot|fragment|ads|api|peer|unsupported), and flags (refund/pending/failed/gift/reaction). Use telegram-get-stars-transactions for full paginated history. Opt-in: register only whe…

List active Telegram Stars subscriptions for a peer (payments.GetStarsSubscriptions). Pass 'me' for your own account or a bot/channel you own. Returns subscription ID, peer, renewal date, period, price in Stars, and canceled status. Paginate with offset. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

List available Telegram Stars top-up tiers (from payments.GetStarsTopupOptions). Returns each option with star count, currency, price amount (in smallest currency units), and whether it is an extended/premium tier. Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1. Read-only.

Fetch a paginated Telegram Stars transaction history for a peer (payments.GetStarsTransactions). Pass 'me'/'@me' (or your own user id) for your wallet, or a bot/channel peer you own/administrate. Filters: inbound (credits only), outbound (debits only), ascending (chronological; default descending), subscriptionId (scope to a single subscription). Paginate with offset (cursor string from a prior response's nextOffset) and limit (default 50). Returns {balance, history[], nextOffset?, subscriptions?[], ...} — same shape as telegram-get-stars-status but focused on transactions. Opt-in: register on…

Initialize the polling cursor by fetching the current Telegram updates state {pts, qts, date, seq, unreadCount}. The returned {pts, qts, date} is the starting cursor for telegram-get-updates. The server does not store the cursor between calls.

Get all stickers from a sticker set by its short name. Returns each sticker with index and emoji. The index identifies the sticker in telegram-send-sticker.

Fetch auto-archived (expired) stories from a peer's archive. Paginate via offsetId (pass last story id from previous page).

Fetch specific stories from a peer by their numeric IDs. Useful for retrieving archived/pinned stories outside the active feed. Returns compact story metadata and optional pinnedToTop list. Pass up to ~100 ids per request.

List viewers of one of YOUR stories (stories.GetStoryViewsList). Returns per-viewer entries (user id, view date, their reaction emoji if any), plus totals (viewsCount, forwardsCount, reactionsCount) and nextOffset for pagination. Pass your own user id (numeric) or @username as the peer — this only works for stories you posted. Some accounts (non-Premium, old stories) may not get a full viewer list — a Premium hint is surfaced on typical errors.

Get Telegram's suggested chat folders based on your chat list (e.g. 'Unread', 'Personal', 'Work'). Returns folder templates only; nothing is created.

Get the list of most popular emoji reactions available on Telegram

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

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

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.

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, the result says so and the history has to be re-read per chat. The server does not store the cursor; each call takes the {pts, qts, date} returned by the previous one.

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

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 expires about 60s after the original query. Returns the sent messageId (0 if not extractable from the update).

Invite users to a Telegram group or channel

Join a Telegram group or channel by username or invite link

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

Leave a Telegram group or channel

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

List default or recently-used emoji statuses available for your account. Useful for finding a documentId to pass to telegram-set-emoji-status.

List forum topics in a Telegram group with Topics enabled. Shows topic names, unread counts, and 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.

Mark a Telegram chat as read

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

Mute or unmute notifications for a Telegram chat. Set muted=true to mute (optionally with duration in seconds), muted=false to unmute

Pin or unpin a Telegram dialog in the dialog list

Pin a message in a Telegram chat

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}

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

React to a story with an emoji, or remove the current reaction by passing ''.

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

Mark stories as seen up to a given story ID (maxId, inclusive).

Read messages from a specific forum topic in a Telegram group

Remove admin rights from a user in a supergroup or channel

Reorder Telegram chat folders by specifying a new order of folder IDs. All existing custom folder IDs must be included.

Report a chat as spam to Telegram

Report a story via the multi-step option flow. First call with option:'' starts the flow; subsequent calls pass the base64 option bytes from the previous response.

Resolve a Telegram Business chat link by slug to see whose chat it opens and the pre-filled message. Returns JSON with peerId, peerType, message, and entityCount.

Revoke an invite link for a group or channel

Save or clear a message draft for a chat. Pass empty text to clear the draft. Optional replyTo sets the message being replied to

Show or hide a received Star Gift on your profile. Pass msgId for a gift received as a personal message (DM), or chatId + savedId for a gift in a chat/channel. Set unsave=true to hide the gift (remove from profile display). Opt-in: register only when MCP_TELEGRAM_ENABLE_STARS=1.

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

Search messages globally across all public Telegram chats and channels

Search messages in a specific Telegram chat by text

Search for sticker sets by name or keyword. Returns the short names of matching sticker packs.

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.

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 file (photo, document, video, etc.) to a Telegram chat

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 message to a Telegram chat

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

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

Send a scheduled message to a Telegram chat. The message will be delivered at the specified time by Telegram servers

Send a sticker from a sticker set to a chat. The sticker is identified by the set's short name and its index in that set, as listed by telegram-get-sticker-set.

Publish a new story (photo or video) to your profile or a channel you manage. Privacy: everyone/contacts/close_friends/selected (allowUserIds required for 'selected'). MediaAreas not supported in this version.

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

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

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

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

Promote a user to admin in a supergroup or channel. Grants: change info, post, edit and delete messages, ban users, invite users, pin messages, manage voice chats. Does not grant the right to add other admins.

Set auto-delete timer for messages in a chat. Common values: 86400 (1 day), 604800 (1 week), 2592000 (1 month). Use 0 to disable

Set your birthday in your Telegram profile. Year is optional (omit to hide age). Pass clear=true to remove birthday. Requires day and month unless clearing.

Set Telegram Business away message — auto-reply when you are offline or outside work hours. Uses a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.

Set Telegram Business greeting message — auto-reply sent to new conversations using a quick reply shortcut as template. Requires Telegram Business subscription. Pass clear=true to disable.

Set Telegram Business work hours — days and time ranges when your business is open. Requires Telegram Business subscription. Pass clear=true to disable the work hours display entirely.

Set Telegram Business intro card — title and description shown to new users opening your chat, with an optional sticker. Requires Telegram Business subscription. Pass clear=true to remove.

Set Telegram Business physical location (address + optional geo coordinates). Requires Telegram Business subscription. Pass clear=true to remove.

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

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

Set your profile emoji status (custom animated emoji shown next to your name). Requires Telegram Premium. Pass documentId or collectibleId to set — omit both to clear the status. Available IDs are listed by telegram-list-emoji-statuses.

Update account-level global privacy settings. Only pass the fields you want to change — omitted fields keep their current values. hideReadMarks and newNoncontactPeersRequirePremium require Telegram Premium.

Set the channel displayed on your profile as 'Personal Channel'. Pass clear=true to remove. Pass channelId or @username of a channel you own or are subscribed to.

Configure privacy settings for your Telegram account. Controls who can see your phone number, last seen, profile photo, etc.

Set your profile name color or profile background color. Requires Telegram Premium for colors above index 6 and for profile background patterns. Omit color to reset to default.

Upload and set a new profile photo from a local file. Supports JPEG/PNG for static avatar or MP4 for animated avatar (square, up to 10s). Optionally set as fallback photo shown to users who cannot see your main photo.

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)

Check Telegram connection status

Terminate a specific Telegram session by its hash, or explicitly terminate all other sessions by setting terminateAllOther=true

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

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

Enable or disable folder tags (colored labels that appear on messages in chat lists when the message belongs to a tagged folder). Requires Telegram Premium.

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

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

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

Pin or unpin stories in your profile highlights (Telegram allows up to 3 pinned stories).

Pin stories to the very top of your pinned row. Pass an empty array [] to clear all top-pinned stories.

Request server-side transcription of a voice note or video note (Telegram Premium feature). Returns immediately with a transcriptionId; pending:true means the text is not ready yet, and telegram-get-transcription returns it once it is.

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

Unban a previously banned user from a supergroup or channel

Unblock a previously blocked Telegram user

Unpin a message in a Telegram chat

Update your Telegram profile — first name, last name, bio, or username

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