@overpod/mcp-telegram 1.28.1 → 1.33.0

package/CHANGELOG.md

@@ -5,6 +5,175 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.33.0] — 2026-04-24
+
+### Added
+
+**Folder management (6 new tools):**
+- **telegram-create-folder** — Create a new chat folder. Accepts `title` (max 12 chars), optional `emoticon`, type flags (`contacts`, `nonContacts`, `groups`, `broadcasts`, `bots`), filter flags (`excludeMuted`, `excludeRead`, `excludeArchived`), and peer lists (`includePeers`, `excludePeers`, `pinnedPeers` max 5). Auto-assigns the next available folder ID ≥ 2. Returns the new ID
+- **telegram-edit-folder** — Edit an existing folder by `id`. Only pass fields to change — omitted fields preserve current values (fetches current state first via `messages.GetDialogFilters`)
+- **telegram-delete-folder** — Delete a chat folder by ID. Chats remain in All Chats. System folders (0 = All Chats, 1 = Archive) cannot be deleted. Uses `messages.UpdateDialogFilter` without a filter argument
+- **telegram-reorder-folders** — Set the display order of folders by passing an ordered array of folder IDs. Uses `messages.UpdateDialogFiltersOrder`
+- **telegram-get-suggested-folders** — Fetch Telegram's server-side folder suggestions based on your chat list (e.g. "Unread", "Work", "Personal"). Skips `DialogFilterDefault` entries that lack a title
+- **telegram-toggle-folder-tags** — Enable or disable folder tag labels on messages in chat lists. Requires Telegram Premium. Uses `messages.ToggleDialogFilterTags`
+
+**Global privacy (2 new tools):**
+- **telegram-get-global-privacy-settings** — Read all five global privacy flags: `archiveAndMuteNewNoncontactPeers`, `keepArchivedUnmuted`, `keepArchivedFolders`, `hideReadMarks`, `newNoncontactPeersRequirePremium`. Returns JSON
+- **telegram-set-global-privacy-settings** — Update any subset of global privacy flags. Fetches current settings first and merges only the fields you pass. `hideReadMarks` and `newNoncontactPeersRequirePremium` require Telegram Premium
+
+## [1.32.0] — 2026-04-24
+
+### Added
+
+**Profile write (8 new tools):**
+- **telegram-set-emoji-status** — Set custom animated emoji status next to your name (Telegram Premium). Pass `documentId` or `collectibleId`; omit both to clear. Supports optional expiry via `untilUnix`
+- **telegram-list-emoji-statuses** — List available emoji statuses: `default`, `recent`, `channel_default`, or `collectible` (Premium). Returns `documentId`, `until`, collectible `title`/`slug`
+- **telegram-clear-recent-emoji-statuses** — Remove all entries from the "recent" emoji status picker section
+- **telegram-set-profile-color** — Set your name or profile background color. `forProfile=false` = chat list name color; `forProfile=true` = profile page background (Premium). Accepts color index 0-6 (free) or 7-20 (Premium) plus optional background pattern emoji
+- **telegram-set-birthday** — Add/update birthday on profile (`day` + `month` required, `year` optional to hide age). Pass `clear=true` to remove
+- **telegram-set-personal-channel** — Feature a channel on your profile as "Personal Channel". Pass `channelId` or `clear=true` to remove
+- **telegram-set-profile-photo** — Upload static (JPEG/PNG) or animated (MP4, square, ≤10s) avatar. Optional `fallback=true` sets it as the privacy fallback shown when your main photo is hidden
+- **telegram-delete-profile-photo** — Delete one or more profile photos by photo ID (stringified long). Fetches your photo history internally to build the required `InputPhoto`; reports which IDs were not found
+
+**Business write (9 tools, including migrated read-only tool):**
+- **telegram-get-business-chat-links** — Moved from `account.ts` to new `business.ts` module. Behavior unchanged (read-only list of Business chat links)
+- **telegram-create-business-chat-link** — Create a `t.me/m/...` deep-link pre-filled with a message. Supports `parseMode` (md/html), optional admin `title`. Returns JSON with `link`, `slug`, `message`, `views`
+- **telegram-edit-business-chat-link** — Update an existing Business chat link by slug. Same options as create
+- **telegram-delete-business-chat-link** — Delete a Business chat link by slug
+- **telegram-resolve-business-chat-link** — Resolve a slug to see who it opens a chat with and the pre-filled message. Returns `peerId`, `peerType`, `message`, `entityCount`
+- **telegram-set-business-hours** — Configure weekly work hours (Telegram Business required). Input: `timezone` (IANA string) + `schedule` array of `{day, openFrom, openTo}` in HH:MM. Internally converts to minute-of-week (0–10079). `clear=true` disables
+- **telegram-set-business-location** — Set street address ± geo coordinates for Business profile. `clear=true` removes
+- **telegram-set-business-greeting** — Auto-reply for new conversations using a Quick Reply shortcut as template. `audience` enum (all_new / contacts_only / non_contacts / existing_only), `noActivityDays`, optional include/excludeUsers. `clear=true` disables
+- **telegram-set-business-away** — Auto-reply when offline or outside hours. `schedule` enum (always / outside_hours / custom). `custom` requires `customFrom`/`customTo` Unix timestamps. `offlineOnly` flag. Same audience model as greeting. `clear=true` disables
+- **telegram-set-business-intro** — Intro card shown to new users: `title` (≤32) + `description` (≤70) + optional sticker (requires `stickerId` + `stickerAccessHash` + `stickerFileReference` all together). `clear=true` removes
+
+### Notes
+- All Premium-gated tools (`telegram-set-emoji-status`, `telegram-set-profile-color` with index ≥ 7 or `backgroundEmojiId`) throw `PREMIUM_ACCOUNT_REQUIRED` from Telegram on non-Premium accounts — the error is propagated as-is
+- All Business-gated tools throw `BUSINESS_PEER_INVALID` or similar when the account lacks Telegram Business subscription
+- `telegram-get-business-chat-links` moved to `src/tools/business.ts` — tool name and behavior unchanged
+- `telegram-set-profile-photo`: uploads via GramJS `uploadFile` (4 workers). Video must be square MP4, ≤10s; server enforces its own size limits
+- `telegram-delete-profile-photo`: calls `photos.GetUserPhotos` first (up to 100) to resolve `accessHash` + `fileReference` from the photo ID; IDs not in your history are returned in `missing` array
+
+## [1.31.0] — 2026-04-24
+
+### Added
+- **telegram-vote-poll** — Vote in a poll by option index (single/multi-choice). Empty array retracts vote.
+- **telegram-get-poll-results** — Get aggregated poll results: vote counts, percentages, quiz answer status
+- **telegram-get-poll-voters** — List users who voted for specific poll options (public polls only, paginated)
+- **telegram-close-poll** — Permanently close a poll (irreversible; prevents further voting)
+- **telegram-transcribe-audio** — Start server-side transcription of a voice/video note (Telegram Premium)
+- **telegram-get-transcription** — Poll for updated transcription status (idempotent re-call)
+- **telegram-rate-transcription** — Rate transcription quality (good/poor) to improve speech-to-text
+- **telegram-get-fact-check** — Get fact-check annotations on channel messages (batch up to 100)
+- **telegram-edit-fact-check** — Add/update fact-check annotation (requires fact-checker privileges)
+- **telegram-delete-fact-check** — Remove fact-check annotation (requires fact-checker privileges)
+- **telegram-send-paid-reaction** — Send paid reaction (★ Stars) on a channel post with optional privacy
+- **telegram-toggle-paid-reaction-privacy** — Change leaderboard visibility of your paid reaction
+- **telegram-get-paid-reaction-privacy** — Get your current default paid reaction privacy setting
+
+### Notes
+- `telegram-close-poll`: One-way operation — closed polls cannot be reopened
+- `telegram-transcribe-audio`: Premium feature. Non-Premium accounts have limited free trials; `trialRemainsNum` shows count
+- `telegram-get-transcription`: Idempotent — returns same transcriptionId with updated text once processing completes
+- `telegram-edit-fact-check` / `telegram-delete-fact-check`: Require fact-checker privileges; regular users get permission errors
+- `telegram-send-paid-reaction`: Stars are debited from your Telegram balance; `count` range 1-2500
+- `telegram-toggle-paid-reaction-privacy`: Per-message toggle (Layer 198 API)
+
+### New helpers (exported from `telegram-client`)
+- `summarizePoll(poll, results?)` — summarize a GramJS Poll+PollResults into a compact typed object
+- `extractPollMediaFromUpdates(updates)` — extract poll + results from any Updates envelope
+- `extractPeerId(peer)` — convert TypePeer to string ID
+
+### Testing
+- 29 new mock-only tests (cumulative: 447 total)
+
+## [1.30.0] — 2026-04-24
+
+### Added
+- **telegram-send-story** — Publish a photo or video story to your profile or a channel with privacy controls (everyone/contacts/close_friends/selected), period (6-48h), pinning, and no-forward flag. Accepts absolute file path, auto-detects photo/video from extension (jpg/jpeg/png/webp/heic/heif → photo; everything else → video). Caption supports md/html parse mode.
+- **telegram-edit-story** — Edit an existing story: replace media, update caption (empty string clears it), or change privacy rules. At least one field (filePath, caption, or privacy) must be provided.
+- **telegram-delete-stories** — Delete one or more stories (irreversible; requires `confirm: true`; up to 100 IDs per call). Returns the actually-deleted IDs from Telegram (partial success possible).
+- **telegram-react-to-story** — React to a story with an emoji, or remove the reaction by passing empty string `""`.
+- **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 (maxId, inclusive). Returns count of newly-seen stories.
+- **telegram-toggle-story-pinned** — Pin/unpin stories in profile highlights (Telegram allows up to 3 pinned stories). Returns affected story IDs.
+- **telegram-toggle-story-pinned-to-top** — Pin stories to the very top of the pinned row; pass `[]` to clear all top-pinned stories.
+- **telegram-activate-stealth-mode** — Hide your story views retroactively (`past: true`) and/or for the next 25 minutes (`future: true`). At least one of past/future must be true. Requires Telegram Premium — non-Premium accounts receive PREMIUM_ACCOUNT_REQUIRED.
+- **telegram-get-stories-archive** — Fetch auto-archived (expired) stories from a peer's archive, paginated via `offsetId` + `limit` (1–100, default 50).
+- **telegram-report-story** — Report a story via Telegram's multi-step option flow. First call with `option: ""` starts the flow; subsequent calls pass the base64 option bytes from the previous response's `options[n].option` field.
+- **telegram-get-discussion-message** — 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.
+- **telegram-get-groups-for-discussion** — List groups eligible to link as discussion group to a channel you admin (channels.GetGroupsForDiscussion). No parameters required.
+- **telegram-get-message-read-participants** — List who has read a message in a small group (≤100 members, ≤7 days old). Returns `readers` array with `userId` and `readAt` (ISO timestamp). Returns CHAT_TOO_BIG error for large groups or channels.
+- **telegram-get-outbox-read-date** — Get when your recipient read your outgoing private message. Returns `"Read at <ISO date>"` or `"Not read yet"` (maps NOT_READ_YET error to null). Propagates YOUR_PRIVACY_RESTRICTED / USER_PRIVACY_RESTRICTED as errors.
+
+### New helpers in `telegram-helpers.ts`
+- `StoryPrivacy` type and `buildStoryPrivacyRules()` — builds GramJS `TypeInputPrivacyRule[]` from privacy enum + allow/disallow user ID lists
+- `detectMediaType()` — infers photo/video from file extension (safe default: video)
+- `extractStoryIdFromUpdates()` — extracts story ID from SendStory Updates envelope (prefers UpdateStoryID, falls back to UpdateStory)
+- `summarizeDiscussionMessage()`, `DiscussionMessageSummary` type
+- `summarizeGroupsForDiscussion()`, `GroupsForDiscussionSummary` type
+- `summarizeReadParticipants()`, `ReadParticipantsSummary` type
+- `summarizeReportResult()`, `ReportResultSummary` type (discriminated union: reported / chooseOption / addComment)
+
+### Notes
+- `telegram-activate-stealth-mode` requires Telegram Premium — non-Premium accounts receive PREMIUM_ACCOUNT_REQUIRED
+- `telegram-get-message-read-participants` only works for groups ≤100 members and messages ≤7 days old
+- `telegram-delete-stories` requires `confirm: true` (irreversible)
+- `telegram-send-story`: MediaAreas (venue/reaction/URL tags on the story frame) are not supported in this version
+- `telegram-report-story`: Multi-step flow — first call with `option: ""` starts the flow; subsequent calls pass the base64 option bytes from the previous response
+
+### Testing
+- 45 new mock-only tests in `src/__tests__/stories-v2.test.ts` (cumulative: 418 total)
+
+## [1.29.0] - 2026-04-23
+
+### Added
+- **Phase 5 Block A — Rich media sending (7 new tools)** — functional parity with Telegram UI for content types that could not be sent before.
+  - `telegram-send-voice` — send a voice note (OGG/Opus preferred) with optional caption, parseMode, reply/topic. Shows as a waveform UI in the chat.
+  - `telegram-send-video-note` — send a round-shaped video message (MP4, square recommended; duration ≤60s enforced client-side, length ≤640px).
+  - `telegram-send-location` — send a geographic location; single tool handles both static pins and live-updating locations (`livePeriod` 60–86400 seconds; optional `heading` 1–360°, `proximityRadius` meters).
+  - `telegram-send-venue` — send a venue card (title, address, lat/long + optional provider-specific metadata).
+  - `telegram-send-contact` — send a contact card (phone number in E.164-like format `^\+?\d{6,15}$`, first name, optional last name and vCard).
+  - `telegram-send-dice` — send an animated dice/game emoji (🎲 🎯 🎰 🏀 ⚽ 🎳) and receive the server-rolled value in the response.
+  - `telegram-send-album` — send 2–10 grouped photos/videos as a single album message with per-item or album-level caption.
+- **Block B — enhancements to existing `telegram-send-message`:**
+  - `quoteText` — attach a verbatim quote from the replied-to message (requires `replyTo`). Uses raw `messages.SendMessage` + `InputReplyToMessage.quoteText` under the hood.
+  - `effect` — Premium message effect ID (numeric string) attached to the outgoing message.
+- **Defence-in-depth for file-path inputs (`isSafeAbsolutePath`)** — all new `filePath` parameters reject:
+  - URL schemes (`http:`, `https:`, `file:`, `ftp:`, `data:`, `javascript:`, `ws:`, `wss:`) — no SSRF via GramJS URL-fetching.
+  - UNC / SMB shares (`\\server\share`, `//server/share`) — no NTLM-relay from Windows hosts.
+  - Path traversal (`..` segments inside an absolute path) — no escape out of the intended directory.
+  - POSIX pseudo-filesystems (`/proc`, `/sys`, `/dev`, `/run`) — prevents AI prompt-injection from reading `/proc/self/environ` and leaking env vars / session paths to Telegram.
+  - Embedded NUL byte and bare `/` — rejected explicitly.
+- **UTF-16 surrogate sanitation on input** — all free-text parameters (message `text`, captions, venue title/address/provider/venueId/venueType, contact name/vCard, quoteText) now strip unpaired surrogates before reaching GramJS's TL encoder. Complements the existing v1.11.1 output-side fix.
+- **Shared helpers in `telegram-helpers.ts`:**
+  - `buildReplyTo(replyTo?, topicId?)` — construct `InputReplyToMessage` (supports topic root where `replyToMsgId === topicId`).
+  - `generateRandomBigInt()` — cryptographically-random 64-bit `long` for TL `randomId`.
+  - `extractMessageId(result)` — unified parser across `Api.Updates`, `UpdatesCombined`, `Api.Message`, `UpdateShortSentMessage`, `UpdateNewMessage`, `UpdateNewChannelMessage`.
+  - `extractDiceResult(result)` — dice-specific extractor returning `{id, value?}` from `MessageMediaDice`.
+
+### Changed
+- `telegram-send-contact`: `phone` field now validated against `^\+?\d{6,15}$` (E.164-like) to reject malformed/hallucinated numbers.
+- `telegram-send-venue`: `provider` relaxed from a 2-value enum to a free string (≤32 chars) to match TL `venueProvider: string`.
+- `TelegramService.sendMessage()`: gained an optional 6th `extra: { quoteText?, effect? }` parameter. When set, falls back to raw `messages.SendMessage` (high-level `client.sendMessage` does not support these fields). Backward-compatible — existing callers see no change.
+
+### Security
+- `quoteText` without `replyTo` now raises a clear error instead of silently dropping the quote.
+- GramJS private `_parseMessageText` usage in the quoteText/effect raw path is feature-detected; future GramJS bumps surface a clear "version incompatible" error instead of crashing.
+- `effect` ID regex tightened to `^\d{1,19}$` (Int64-safe range).
+
+### Testing
+- 371 unit tests (was 322 in v1.28.1, +49). All tests mock-only (no live Telegram connection).
+- New coverage: all 8 new/changed service methods, helper edge cases (channel path, combined updates, direct Api.Message, UpdateShortSentMessage), SSRF guard (POSIX/Windows accept + URL/UNC/traversal/pseudo-fs reject), raw-path `sendMessage` with `quoteText` / `effect`.
+
+### Notes & known limitations
+- **`telegram-send-video-note` caption omitted** — Telegram UI does not render captions under round video notes; including it here would silently drop.
+- **`telegram-send-contact.userId` field dropped** — GramJS 2.26.22 `InputMediaContact` TL schema (Layer 198) has no `userId` slot. The card is standalone; recipients see the number and name, not a link to a Telegram user. Will return once GramJS advances.
+- **TTL / self-destruct media** — deferred. Requires raw `InputMediaUploadedPhoto({ttlSeconds})` path which bypasses the high-level `sendFile`; will ship in a follow-up.
+- **`telegram-send-voice.duration` removed vs. initial design** — GramJS auto-detects duration from the audio file; letting the AI override it caused the Telegram UI to display wrong playback times.
+- **Album mixed photo+video** — GramJS accepts mixed arrays via extension-based detection, but this is not covered by tests; recommend uniform media type per album until a live-test checkpoint confirms.
+- **Album flood control** — a 10-item album fans out 10 `messages.UploadMedia` calls inside one rate-limit slot; under heavy contention the later items may still hit `FLOOD_WAIT`. Rate limiter retries apply.
+
 ## [1.26.0] - 2026-04-20
 
 ### Added

package/README.md

@@ -24,14 +24,16 @@ An MCP (Model Context Protocol) server that connects AI assistants like Claude t
 - **Full-featured** -- messaging, reactions, polls, scheduled messages, stickers, media, contacts, and more
 - **Forum Topics** -- list topics, read per-topic messages, send to specific topics, per-topic unread counts
 - **Stickers** -- search sticker sets, browse installed/recent stickers, send stickers to any chat
-- **Account management** -- update profile, manage privacy settings, sessions, auto-delete timers
+- **Account & profile management** -- update profile, set emoji status, birthday, personal channel, profile photo, manage privacy settings, sessions, auto-delete timers
 - **Global search** -- search messages across all chats at once
 - **Real-time polling** -- fetch updates via stateless cursors; agent owns `{pts, qts, date}` state
 - **Inline bots & buttons** -- query inline bots, send results, press callback buttons
-- **Stories** -- read stories from peers, get story view stats
+- **Stories** -- read stories from peers, get story view stats; publish/edit/delete stories, react, pin, stealth mode, archive, report (v1.30.0)
+- **Discussion** -- get discussion-group info for channel posts with comments, list groups eligible for discussion (v1.30.0)
+- **Read Receipts** -- who read a message in a small group, when your private message was read (v1.30.0)
 - **Admin controls** -- toggle channel signatures, anti-spam, forum mode, prehistory; approve join requests
 - **Stats** -- channel and supergroup analytics (GetBroadcastStats / GetMegagroupStats)
-- **Boosts & Business** -- boost status, boosters list, Telegram Business chat links
+- **Boosts & Business** -- boost status, boosters list, Telegram Business chat links CRUD, work hours, location, greeting/away/intro messages
 - **QR code login** -- authenticate by scanning a QR code in the Telegram app
 - **Session persistence** -- login once, stay connected across restarts
 - **Human-readable output** -- sender names are resolved, not just numeric IDs
@@ -317,21 +319,27 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | Category | Tools |
 |----------|-------|
 | **Auth** | `telegram-status`, `telegram-login`, `telegram-logout` |
-| **Messaging** | `telegram-send-message`, `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |
+| **Messaging** | `telegram-send-message` (incl. `quoteText` for verbatim reply quotes and Premium message `effect`), `telegram-edit-message`, `telegram-delete-message`, `telegram-forward-message`, `telegram-send-scheduled`, `telegram-send-typing`, `telegram-translate-message`, `telegram-get-message-link` |
 | **Scheduled** | `telegram-get-scheduled`, `telegram-delete-scheduled` |
 | **Reading** | `telegram-list-chats`, `telegram-read-messages`, `telegram-search-messages`, `telegram-search-global`, `telegram-search-chats`, `telegram-get-unread`, `telegram-mark-as-read`, `telegram-get-replies`, `telegram-get-unread-mentions`, `telegram-get-unread-reactions`, `telegram-get-saved-dialogs` |
 | **Drafts** | `telegram-save-draft`, `telegram-get-drafts`, `telegram-clear-drafts` |
 | **Forum Topics** | `telegram-list-topics`, `telegram-read-topic-messages`, `telegram-create-topic`, `telegram-edit-topic`, `telegram-delete-topic` |
 | **Polls** | `telegram-create-poll` |
+| **Poll Interaction (v1.31.0)** | `telegram-vote-poll`, `telegram-get-poll-results`, `telegram-get-poll-voters`, `telegram-close-poll` |
 | **Reactions** | `telegram-send-reaction`, `telegram-get-reactions`, `telegram-set-default-reaction`, `telegram-get-top-reactions`, `telegram-get-recent-reactions` |
+| **Paid Reactions (v1.31.0)** | `telegram-send-paid-reaction` (★ Stars), `telegram-toggle-paid-reaction-privacy`, `telegram-get-paid-reaction-privacy` |
+| **Audio Transcription (v1.31.0)** | `telegram-transcribe-audio` (Premium), `telegram-get-transcription`, `telegram-rate-transcription` |
+| **Fact-check (v1.31.0)** | `telegram-get-fact-check`, `telegram-edit-fact-check`, `telegram-delete-fact-check` |
 | **Stickers** | `telegram-send-sticker`, `telegram-get-installed-stickers`, `telegram-get-recent-stickers`, `telegram-get-sticker-set`, `telegram-search-sticker-sets` |
 | **Media** | `telegram-send-file`, `telegram-download-media`, `telegram-get-profile-photo`, `telegram-get-web-preview` |
+| **Rich Media Sending** | `telegram-send-voice`, `telegram-send-video-note` (round video), `telegram-send-location` (static or live), `telegram-send-venue`, `telegram-send-contact`, `telegram-send-dice` (🎲🎯🎰🏀⚽🎳), `telegram-send-album` (2–10 grouped photos/videos) |
 | **Groups** | `telegram-create-group`, `telegram-edit-group`, `telegram-invite-to-group`, `telegram-join-chat`, `telegram-leave-group`, `telegram-kick-user`, `telegram-ban-user`, `telegram-unban-user`, `telegram-set-admin`, `telegram-remove-admin`, `telegram-get-my-role`, `telegram-set-chat-permissions`, `telegram-set-slow-mode`, `telegram-get-admin-log` |
 | **Chat Info** | `telegram-get-chat-info`, `telegram-get-chat-members`, `telegram-get-chat-folders` |
 | **Invite Links** | `telegram-create-invite-link`, `telegram-get-invite-links`, `telegram-revoke-invite-link` |
 | **Contacts** | `telegram-get-contacts`, `telegram-add-contact`, `telegram-get-contact-requests` |
 | **Moderation** | `telegram-block-user`, `telegram-unblock-user`, `telegram-report-spam` |
-| **Profiles** | `telegram-get-profile`, `telegram-update-profile` |
+| **Profiles (read)** | `telegram-get-profile`, `telegram-update-profile` |
+| **Profile (write, v1.32.0)** | `telegram-set-emoji-status` (Premium), `telegram-list-emoji-statuses`, `telegram-clear-recent-emoji-statuses`, `telegram-set-profile-color` (Premium), `telegram-set-birthday`, `telegram-set-personal-channel`, `telegram-set-profile-photo`, `telegram-delete-profile-photo` |
 | **Account** | `telegram-get-sessions`, `telegram-terminate-session`, `telegram-set-privacy`, `telegram-set-auto-delete` |
 | **Pinning** | `telegram-pin-message`, `telegram-unpin-message` |
 | **Chat Settings** | `telegram-mute-chat`, `telegram-archive-chat`, `telegram-pin-chat`, `telegram-mark-dialog-unread` |
@@ -339,8 +347,12 @@ All tools are auto-discoverable via MCP — your AI client will see the full lis
 | **Stats** | `telegram-get-broadcast-stats`, `telegram-get-megagroup-stats` |
 | **Inline Bots & Buttons** | `telegram-inline-query`, `telegram-inline-query-send`, `telegram-press-button`, `telegram-get-message-buttons` |
 | **Real-Time Polling** | `telegram-get-state`, `telegram-get-updates`, `telegram-get-channel-updates` |
-| **Stories** | `telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views` |
-| **Boosts & Business** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list`, `telegram-get-business-chat-links` |
+| **Stories (read)** | `telegram-get-all-stories`, `telegram-get-peer-stories`, `telegram-get-stories-by-id`, `telegram-get-story-views` |
+| **Stories (write, v1.30.0)** | `telegram-send-story`, `telegram-edit-story`, `telegram-delete-stories`, `telegram-react-to-story`, `telegram-export-story-link`, `telegram-read-stories`, `telegram-toggle-story-pinned`, `telegram-toggle-story-pinned-to-top`, `telegram-activate-stealth-mode` (Premium), `telegram-get-stories-archive`, `telegram-report-story` |
+| **Discussion (v1.30.0)** | `telegram-get-discussion-message`, `telegram-get-groups-for-discussion` |
+| **Read Receipts (v1.30.0)** | `telegram-get-message-read-participants`, `telegram-get-outbox-read-date` |
+| **Boosts** | `telegram-get-my-boosts`, `telegram-get-boosts-status`, `telegram-get-boosts-list` |
+| **Business (v1.32.0)** | `telegram-get-business-chat-links`, `telegram-create-business-chat-link`, `telegram-edit-business-chat-link`, `telegram-delete-business-chat-link`, `telegram-resolve-business-chat-link`, `telegram-set-business-hours`, `telegram-set-business-location`, `telegram-set-business-greeting`, `telegram-set-business-away`, `telegram-set-business-intro` |
 | **Opt-in (env-gated)** | `telegram-get-group-call`, `telegram-get-group-call-participants` (requires `MCP_TELEGRAM_ENABLE_GROUP_CALLS=1`), `telegram-get-stars-status`, `telegram-get-stars-transactions` (requires `MCP_TELEGRAM_ENABLE_STARS=1`), `telegram-get-quick-replies`, `telegram-get-quick-reply-messages` (requires `MCP_TELEGRAM_ENABLE_QUICK_REPLIES=1`) |
 
 > **Tip**: Ask your AI assistant *"What Telegram tools are available?"* to get the full list with parameters and descriptions.
@@ -385,7 +397,8 @@ src/
     reactions.ts      -- Reactions, set-chat-reactions
     extras.ts         -- Pin, schedule, polls, topics
     stickers.ts       -- Sticker sets, send, search, browse
-    account.ts        -- Sessions, privacy, auto-delete, profile, chat mute/folders, invite links, business chat links
+    account.ts        -- Sessions, privacy, auto-delete, profile, emoji status, birthday, chat mute/folders, invite links
+    business.ts       -- Telegram Business: chat links CRUD, work hours, location, greeting/away/intro
     boosts.ts         -- Boost status, my boosts, boosters list
     stories.ts        -- Stories: list all, peer, by-id, view stats
     group-calls.ts    -- Group call info and participants (opt-in: MCP_TELEGRAM_ENABLE_GROUP_CALLS)

package/dist/telegram-client.d.ts

@@ -1,8 +1,8 @@
 import { TelegramClient } from "telegram";
 import { Api } from "telegram/tl/index.js";
-import type { AllStoriesSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, GroupCallParticipantsSummary, GroupCallSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostsSummary, PeerStoriesSummary, QuickRepliesSummary, QuickReplyMessagesSummary, StarsStatusSummary, StoriesByIdSummary, StoryViewsListSummary, UpdatesDifferenceSummary } from "./telegram-helpers.js";
-export type { AllStoriesSummary, BoostSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinkSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, CompactPeer, CompactStatsGraph, GroupCallInfoSummary, GroupCallParticipantSummary, GroupCallParticipantsSummary, GroupCallSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostSummary, MyBoostsSummary, PeerStoriesSummary, PrepaidGiveawaySummary, QuickRepliesSummary, QuickReplyMessageSummary, QuickReplyMessagesSummary, QuickReplySummary, StarsAmountSummary, StarsStatusSummary, StarsSubscriptionPricingSummary, StarsSubscriptionSummary, StarsTransactionPeerSummary, StarsTransactionSummary, StatsValue, StoriesByIdSummary, StoryItemSummary, StoryViewSummary, StoryViewsListSummary, UpdatesDifferenceSummary, UpdatesMessageSummary, } from "./telegram-helpers.js";
-export { describeAdminLogAction, describeAdminLogDetails, describeKeyboardButton, mergeBannedRights, peerToCompact, reactionToEmoji, summarizeAllStories, summarizeBoost, summarizeBoostsList, summarizeBoostsStatus, summarizeBroadcastStats, summarizeBusinessChatLink, summarizeBusinessChatLinks, summarizeChannelDifference, summarizeGroupCall, summarizeGroupCallInfo, summarizeGroupCallParticipant, summarizeGroupCallParticipants, summarizeMegagroupStats, summarizeMyBoost, summarizeMyBoosts, summarizePeerStories, summarizePrepaidGiveaway, summarizeQuickReplies, summarizeQuickReply, summarizeQuickReplyMessage, summarizeQuickReplyMessages, summarizeStarsAmount, summarizeStarsStatus, summarizeStarsSubscription, summarizeStarsTransaction, summarizeStarsTransactionPeer, summarizeStoriesById, summarizeStoryItem, summarizeStoryView, summarizeStoryViewsList, summarizeUpdatesDifference, } from "./telegram-helpers.js";
+import type { AllStoriesSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, DiscussionMessageSummary, EmojiStatusSummary, GroupCallParticipantsSummary, GroupCallSummary, GroupsForDiscussionSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostsSummary, PeerStoriesSummary, PollSummary, QuickRepliesSummary, QuickReplyMessagesSummary, ReadParticipantsSummary, ReportResultSummary, ResolvedBusinessChatLinkSummary, StarsStatusSummary, StoriesByIdSummary, StoryPrivacy, StoryViewsListSummary, UpdatesDifferenceSummary } from "./telegram-helpers.js";
+export type { AllStoriesSummary, BoostSummary, BoostsListSummary, BoostsStatusSummary, BroadcastStatsSummary, BusinessChatLinkSummary, BusinessChatLinksSummary, ChannelDifferenceSummary, ChatPermissions, CompactPeer, CompactStatsGraph, DiscussionMessageSummary, EmojiStatusSummary, GroupCallInfoSummary, GroupCallParticipantSummary, GroupCallParticipantsSummary, GroupCallSummary, GroupsForDiscussionSummary, MegagroupStatsSummary, MessageButtonDescriptor, MyBoostSummary, MyBoostsSummary, PeerStoriesSummary, PeerSummary, PollSummary, PrepaidGiveawaySummary, QuickRepliesSummary, QuickReplyMessageSummary, QuickReplyMessagesSummary, QuickReplySummary, ReadParticipantsSummary, ReportResultSummary, ResolvedBusinessChatLinkSummary, StarsAmountSummary, StarsStatusSummary, StarsSubscriptionPricingSummary, StarsSubscriptionSummary, StarsTransactionPeerSummary, StarsTransactionSummary, StatsValue, StoriesByIdSummary, StoryItemSummary, StoryPrivacy, StoryViewSummary, StoryViewsListSummary, UpdatesDifferenceSummary, UpdatesMessageSummary, } from "./telegram-helpers.js";
+export { buildStoryPrivacyRules, describeAdminLogAction, describeAdminLogDetails, describeKeyboardButton, detectMediaType, extractPeerId, extractPollMediaFromUpdates, extractStoryIdFromUpdates, mergeBannedRights, peerToCompact, reactionToEmoji, summarizeAllStories, summarizeBoost, summarizeBoostsList, summarizeBoostsStatus, summarizeBroadcastStats, summarizeBusinessChatLink, summarizeBusinessChatLinks, summarizeChannelDifference, summarizeDiscussionMessage, summarizeEmojiStatus, summarizeGroupCall, summarizeGroupCallInfo, summarizeGroupCallParticipant, summarizeGroupCallParticipants, summarizeGroupsForDiscussion, summarizeMegagroupStats, summarizeMyBoost, summarizeMyBoosts, summarizePeer, summarizePeerStories, summarizePoll, summarizePrepaidGiveaway, summarizeQuickReplies, summarizeQuickReply, summarizeQuickReplyMessage, summarizeQuickReplyMessages, summarizeReadParticipants, summarizeReportResult, summarizeStarsAmount, summarizeStarsStatus, summarizeStarsSubscription, summarizeStarsTransaction, summarizeStarsTransactionPeer, summarizeStoriesById, summarizeStoryItem, summarizeStoryView, summarizeStoryViewsList, summarizeUpdatesDifference, } from "./telegram-helpers.js";
 export type ChatEntity = Api.User | Api.Chat | Api.Channel | Api.TypeUser | Api.TypeChat;
 export declare class TelegramService {
     private client;
@@ -51,8 +51,72 @@ export declare class TelegramService {
         username?: string;
         firstName?: string;
     }>;
-    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number): Promise<Api.Message | Api.UpdateShortSentMessage | undefined>;
+    sendMessage(chatId: string, text: string, replyTo?: number, parseMode?: "md" | "html", topicId?: number, extra?: {
+        quoteText?: string;
+        effect?: string;
+    }): Promise<Api.Message | Api.UpdateShortSentMessage | undefined>;
     sendFile(chatId: string, filePath: string, caption?: string): Promise<void>;
+    sendVoice(chatId: string, filePath: string, opts?: {
+        caption?: string;
+        replyTo?: number;
+        topicId?: number;
+        parseMode?: "md" | "html";
+    }): Promise<{
+        id: number;
+    }>;
+    sendVideoNote(chatId: string, filePath: string, opts?: {
+        duration?: number;
+        length?: number;
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        id: number;
+    }>;
+    sendContact(chatId: string, phone: string, firstName: string, opts?: {
+        lastName?: string;
+        vcard?: string;
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        id: number;
+    }>;
+    sendDice(chatId: string, emoji: string, opts?: {
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        id: number;
+        value?: number;
+    }>;
+    sendLocation(chatId: string, latitude: number, longitude: number, opts?: {
+        accuracyRadius?: number;
+        livePeriod?: number;
+        heading?: number;
+        proximityRadius?: number;
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        id: number;
+    }>;
+    sendVenue(chatId: string, latitude: number, longitude: number, title: string, address: string, opts?: {
+        provider?: string;
+        venueId?: string;
+        venueType?: string;
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        id: number;
+    }>;
+    sendAlbum(chatId: string, items: Array<{
+        filePath: string;
+        caption?: string;
+    }>, opts?: {
+        caption?: string;
+        parseMode?: "md" | "html";
+        replyTo?: number;
+        topicId?: number;
+    }): Promise<{
+        ids: number[];
+    }>;
     downloadMedia(chatId: string, messageId: number, downloadPath: string): Promise<string>;
     downloadMediaAsBuffer(chatId: string, messageId: number): Promise<{
         buffer: Buffer;
@@ -341,6 +405,58 @@ export declare class TelegramService {
         quiz?: boolean;
         correctAnswer?: number;
     }): Promise<number>;
+    sendPollVote(chatId: string, messageId: number, optionIndexes: number[]): Promise<{
+        totalVoters: number;
+        chosenLabels: string[];
+        isRetracted: boolean;
+    }>;
+    getPollResults(chatId: string, messageId: number): Promise<PollSummary>;
+    getPollVoters(chatId: string, messageId: number, opts?: {
+        optionIndex?: number;
+        limit?: number;
+        offset?: string;
+    }): Promise<{
+        total: number;
+        nextOffset?: string;
+        voters: Array<{
+            peerId: string;
+            name?: string;
+            username?: string;
+            options: string[];
+            date: number;
+        }>;
+    }>;
+    closePoll(chatId: string, messageId: number): Promise<{
+        totalVoters: number;
+    }>;
+    transcribeAudio(chatId: string, messageId: number): Promise<{
+        transcriptionId: string;
+        text: string;
+        pending: boolean;
+        trialRemainsNum?: number;
+        trialRemainsUntilDate?: number;
+    }>;
+    rateTranscription(chatId: string, messageId: number, transcriptionId: string, good: boolean): Promise<void>;
+    getFactCheck(chatId: string, messageIds: number[]): Promise<Array<{
+        messageId: number;
+        needCheck: boolean;
+        country?: string;
+        text?: string;
+        hash: string;
+    }>>;
+    editFactCheck(chatId: string, messageId: number, text: string, _opts?: {
+        parseMode?: "md" | "html";
+    }): Promise<void>;
+    deleteFactCheck(chatId: string, messageId: number): Promise<void>;
+    sendPaidReaction(chatId: string, messageId: number, count: number, opts?: {
+        private?: boolean;
+    }): Promise<{
+        count: number;
+    }>;
+    togglePaidReactionPrivacy(chatId: string, messageId: number, privateFlag: boolean): Promise<void>;
+    getPaidReactionPrivacy(): Promise<{
+        private: boolean;
+    }>;
     getForumTopics(chatId: string, limit?: number): Promise<Array<{
         id: number;
         title: string;
@@ -530,6 +646,57 @@ export declare class TelegramService {
         includeCount: number;
     }>>;
     setAutoDelete(chatId: string, period: number): Promise<void>;
+    createFolder(opts: {
+        title: string;
+        emoticon?: string;
+        contacts?: boolean;
+        nonContacts?: boolean;
+        groups?: boolean;
+        broadcasts?: boolean;
+        bots?: boolean;
+        excludeMuted?: boolean;
+        excludeRead?: boolean;
+        excludeArchived?: boolean;
+        includePeers?: string[];
+        excludePeers?: string[];
+        pinnedPeers?: string[];
+    }): Promise<number>;
+    editFolder(id: number, opts: {
+        title?: string;
+        emoticon?: string;
+        contacts?: boolean;
+        nonContacts?: boolean;
+        groups?: boolean;
+        broadcasts?: boolean;
+        bots?: boolean;
+        excludeMuted?: boolean;
+        excludeRead?: boolean;
+        excludeArchived?: boolean;
+        includePeers?: string[];
+        excludePeers?: string[];
+        pinnedPeers?: string[];
+    }): Promise<void>;
+    deleteFolder(id: number): Promise<void>;
+    reorderFolders(ids: number[]): Promise<void>;
+    getSuggestedFolders(): Promise<Array<{
+        title: string;
+        emoticon?: string;
+    }>>;
+    toggleDialogFilterTags(enabled: boolean): Promise<void>;
+    getGlobalPrivacySettings(): Promise<{
+        archiveAndMuteNewNoncontactPeers: boolean;
+        keepArchivedUnmuted: boolean;
+        keepArchivedFolders: boolean;
+        hideReadMarks: boolean;
+        newNoncontactPeersRequirePremium: boolean;
+    }>;
+    setGlobalPrivacySettings(opts: {
+        archiveAndMuteNewNoncontactPeers?: boolean;
+        keepArchivedUnmuted?: boolean;
+        keepArchivedFolders?: boolean;
+        hideReadMarks?: boolean;
+        newNoncontactPeersRequirePremium?: boolean;
+    }): Promise<void>;
     getActiveSessions(): Promise<Array<{
         hash: string;
         device: string;
@@ -621,6 +788,101 @@ export declare class TelegramService {
         limit?: number;
     }): Promise<BoostsListSummary>;
     getBusinessChatLinks(): Promise<BusinessChatLinksSummary>;
+    setEmojiStatus(opts: {
+        documentId?: string;
+        collectibleId?: string;
+        untilUnix?: number;
+    }): Promise<void>;
+    listEmojiStatuses(kind: "default" | "recent" | "channel_default" | "collectible", limit: number): Promise<EmojiStatusSummary[]>;
+    clearRecentEmojiStatuses(): Promise<void>;
+    setProfileColor(opts: {
+        forProfile: boolean;
+        color?: number;
+        backgroundEmojiId?: string;
+    }): Promise<void>;
+    setBirthday(opts: {
+        day?: number;
+        month?: number;
+        year?: number;
+        clear?: boolean;
+    }): Promise<void>;
+    setPersonalChannel(opts: {
+        channelId?: string;
+        clear?: boolean;
+    }): Promise<string | null>;
+    setProfilePhoto(opts: {
+        filePath: string;
+        isVideo: boolean;
+        videoStartTs?: number;
+        fallback: boolean;
+    }): Promise<{
+        id: string;
+    }>;
+    deleteProfilePhotos(photoIds: string[]): Promise<{
+        deleted: string[];
+        missing: string[];
+    }>;
+    private buildBusinessRecipients;
+    private resolveInputUsers;
+    private parseEntities;
+    setBusinessWorkHours(opts: {
+        timezone?: string;
+        openNow?: boolean;
+        schedule?: Array<{
+            day: string;
+            openFrom: string;
+            openTo: string;
+        }>;
+        clear?: boolean;
+    }): Promise<void>;
+    setBusinessLocation(opts: {
+        address?: string;
+        latitude?: number;
+        longitude?: number;
+        clear?: boolean;
+    }): Promise<void>;
+    setBusinessGreeting(opts: {
+        shortcutId?: number;
+        audience: "all_new" | "contacts_only" | "non_contacts" | "existing_only";
+        includeUsers?: string[];
+        excludeUsers?: string[];
+        noActivityDays: number;
+        clear?: boolean;
+    }): Promise<void>;
+    setBusinessAway(opts: {
+        shortcutId?: number;
+        schedule: "always" | "outside_hours" | "custom";
+        customFrom?: number;
+        customTo?: number;
+        offlineOnly: boolean;
+        audience: "all_new" | "contacts_only" | "non_contacts" | "existing_only";
+        includeUsers?: string[];
+        excludeUsers?: string[];
+        clear?: boolean;
+    }): Promise<void>;
+    setBusinessIntro(opts: {
+        title?: string;
+        description?: string;
+        stickerId?: string;
+        stickerAccessHash?: string;
+        stickerFileReference?: string;
+        clear?: boolean;
+    }): Promise<void>;
+    createBusinessChatLink(opts: {
+        message: string;
+        title?: string;
+        parseMode?: "md" | "html";
+    }): Promise<BusinessChatLinksSummary["links"][0] & {
+        slug: string;
+    }>;
+    editBusinessChatLink(opts: {
+        slug: string;
+        message: string;
+        title?: string;
+        parseMode?: "md" | "html";
+    }): Promise<BusinessChatLinksSummary["links"][0]>;
+    deleteBusinessChatLink(slug: string): Promise<void>;
+    resolveBusinessChatLink(slug: string): Promise<ResolvedBusinessChatLinkSummary>;
     getGroupCall(chatId: string, options?: {
         limit?: number;
     }): Promise<GroupCallSummary>;
@@ -644,5 +906,55 @@ export declare class TelegramService {
         ids?: number[];
         hash?: string;
     }): Promise<QuickReplyMessagesSummary>;
+    sendStory(chatId: string, filePath: string, opts: {
+        type?: "photo" | "video";
+        caption?: string;
+        parseMode?: "md" | "html";
+        privacy: StoryPrivacy;
+        allowUserIds?: string[];
+        disallowUserIds?: string[];
+        period?: number;
+        pinned?: boolean;
+        noforwards?: boolean;
+    }): Promise<{
+        id: number | undefined;
+        period: number;
+    }>;
+    editStory(chatId: string, storyId: number, opts: {
+        filePath?: string;
+        type?: "photo" | "video";
+        caption?: string;
+        parseMode?: "md" | "html";
+        privacy?: StoryPrivacy;
+        allowUserIds?: string[];
+        disallowUserIds?: string[];
+    }): Promise<{
+        changed: string[];
+    }>;
+    deleteStories(chatId: string, ids: number[]): Promise<{
+        deleted: number[];
+    }>;
+    sendStoryReaction(chatId: string, storyId: number, emoji: string, addToRecent?: boolean): Promise<void>;
+    exportStoryLink(chatId: string, storyId: number): Promise<{
+        link: string;
+    }>;
+    readStories(chatId: string, maxId: number): Promise<{
+        ids: number[];
+    }>;
+    toggleStoryPinned(chatId: string, ids: number[], pinned: boolean): Promise<{
+        affected: number[];
+    }>;
+    toggleStoryPinnedToTop(chatId: string, ids: number[]): Promise<{
+        ok: boolean;
+    }>;
+    activateStealthMode(past?: boolean, future?: boolean): Promise<void>;
+    getStoriesArchive(chatId: string, offsetId: number, limit: number): Promise<StoriesByIdSummary>;
+    reportStory(chatId: string, ids: number[], option: string, message: string): Promise<ReportResultSummary>;
+    getDiscussionMessage(chatId: string, messageId: number): Promise<DiscussionMessageSummary>;
+    getGroupsForDiscussion(): Promise<GroupsForDiscussionSummary>;
+    getMessageReadParticipants(chatId: string, messageId: number): Promise<ReadParticipantsSummary>;
+    getOutboxReadDate(chatId: string, messageId: number): Promise<{
+        readAt: string | null;
+    }>;
     private resolveInputGroupCall;
 }