39 operations. Every one takes the global flags (--json, --plain, -a/--account, --results-only, --select, --dry-run, --yes, --no-input, --flood-wait-max, -v) anywhere on the line.
| Command | Summary |
|---|---|
message compose |
Rewrite text with Telegram's AI |
message delete |
Delete messages for me or for everyone |
message dice list |
Which dice emoji exist and what counts as a win |
message edit |
Edit a message's text, caption, media or schedule |
message effect list |
Browse the animated message effects |
message entity list |
Parse or inspect formatted text and its entities |
message fact-check set |
Read, set or remove a message's fact-check |
message forward |
Forward or copy messages to one or many chats |
message game get |
A game's high-score table |
message game send |
Send a bot game into a chat |
message get |
Get one message with its full metadata |
message link |
Build a t.me link to a message |
message list |
Read a chat's message history |
message paid set |
Per-user paid-message settings and the Stars they earned |
message pin |
Pin a message in a chat |
message preview |
Fetch the link preview Telegram would attach to a URL |
message read |
Mark a chat, thread, mentions or media contents as read |
message read-receipt list |
Who read this message, and when |
message report |
Report messages for abuse |
message scheduled send |
Send scheduled messages now |
message search |
Search messages inside one chat |
message send |
Send a message to a chat |
message sponsored hide |
Hide sponsored messages for my account or my channel |
message sponsored list |
List the sponsored messages a chat would show |
message sponsored report |
Report or click through a sponsored message |
message suggested approve |
Approve a suggested post |
message suggested deny |
Decline a suggested post |
message suggested edit |
Change your own pending suggested post |
message summarize |
Summarize a long message with AI |
message thread disable |
Disable comments on a single channel post |
message thread list |
List the replies of a thread or the comments under a post |
message tone delete |
Delete a composition tone you authored |
message tone get |
Show one composition tone and preview it |
message tone list |
List AI composition tones |
message tone set |
Create, edit or install a composition tone |
message transcribe |
Transcribe a voice note or round video |
message translate |
Translate messages or text into a target language |
message unpin |
Unpin one message or every pinned message |
message view get |
Views and forwards counters for channel posts |
Rewrite text with Telegram's AI.
tlgr message compose [TEXT] [OPTIONS]
returns ComposeResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
TEXT |
text | no | Text to rewrite; '-' reads stdin. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--diff |
unified | inline | json |
--emojify |
flag | Add emoji. | |
--proofread |
flag | Fix grammar and spelling. | |
--rich |
path | Compose a rich body. | |
--send-to |
chat | Send the result instead of printing. | |
--stdin |
flag | Read from stdin. | |
--tone |
text | Rewrite in this tone. | |
--translate |
text | Translate into this language. |
$ tlgr message compose --proofread "im on my way" --jsonCatalog coverage (4 full, 1 partial)
Full: ai.compose, appearance.ai-compose-run, messages-core.ai-compose, messages-core.format-diff-entities
Partial: richmsg.compose-ai
Composing a rich body needs layer 229 and is refused with NOT_SUPPORTED.
Delete messages for me or for everyone.
In a channel or supergroup a delete is always for everyone — channels.deleteMessages has no revoke flag — so --for-me is only meaningful in private chats and basic groups.
tlgr message delete <CHAT> [MSG_ID]... [OPTIONS]
mutating · destructive (needs --yes off a TTY) · returns DeleteResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
text | any number | Ids or ranges (100-120). |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--ban |
flag | With --from: also ban the member. | |
--for-everyone/--no-for-everyone |
flag | True |
Revoke for everyone (the default for own messages). |
--for-me |
flag | Delete only from my own history. | |
--from |
user | Every message this member sent. | |
--report-spam |
flag | With --from: report as spam. | |
--revert |
flag | Revert an ephemeral message. | |
--scheduled |
flag | Delete scheduled messages instead. |
Also invocable as: tlgr msg delete, tlgr message rm
$ tlgr message delete @alice 12345 --jsonCatalog coverage (4 full, 1 partial)
Full: messages-core.delete-all-from-user, messages-core.delete-for-everyone, messages-core.delete-for-me, messages-core.scheduled-delete
Partial: messages-core.ephemeral-messages
--revert needs layer 229's ephemeral.* namespace and is refused.
Which dice emoji exist and what counts as a win.
tlgr message dice list [OPTIONS]
returns DiceCatalog
| Flag | Type | Default | Meaning |
|---|---|---|---|
--refresh |
flag | Re-read help.getAppConfig. | |
--stake |
flag | Also return the staked-dice game state. |
Also invocable as: tlgr dice list
$ tlgr message dice list --jsonCatalog coverage (3 full, 0 partial)
Full: dice.animation-assets, dice.list-emojis, dice.stake-info
Edit a message's text, caption, media or schedule.
MESSAGE_NOT_MODIFIED is success with already: true. --check asks messages.getMessageEditData whether the message may still be edited, which is not derivable from its date: pinned, scheduled and Saved-Messages posts have no 48-hour window.
tlgr message edit <CHAT> <MSG_ID> [TEXT] [OPTIONS]
mutating · idempotent (reports already) · returns EditResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id or link. |
TEXT |
text | no | New text. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--caption |
text | New media caption. | |
--caption-above |
flag | invert_media. | |
--check |
flag | Report whether this message is still editable and stop. | |
--entities |
json | Explicit entities. | |
--file |
path | Replace the media. | |
--no-preview |
flag | Drop the link preview. | |
--parse |
md | html | none |
--preview-above |
flag | invert_media. | |
--preview-url |
text | Change the previewed URL. | |
--repeat |
text | Change the repeat period (Premium). | |
--rich-markdown |
path | Replace the rich body. | |
--schedule |
text | Reschedule a scheduled message. | |
--toggle-task |
int | Flip a checkbox in a rich message. | |
--typing |
number | Type for N seconds first. |
Also invocable as: tlgr msg edit
$ tlgr message edit @alice 12345 "on my way (5 min)" --jsonCatalog coverage (4 full, 1 partial)
Full: messages-core.edit-caption, messages-core.edit-check-permission, messages-core.edit-text, messages-core.scheduled-reschedule
Partial: richmsg.tasks
Checklist tasks live in a layer-229 rich body; --toggle-task is refused.
Browse the animated message effects.
Effects apply to private chats only, and some need Premium to send.
tlgr message effect list [OPTIONS]
paginated (LOCAL cursor) · returns Page[Effect]
| Flag | Type | Default | Meaning |
|---|---|---|---|
--premium-only |
flag | Only effects that require Premium. | |
--refresh |
flag | Ignore the cached hash. |
Pagination is transport-level: --limit/-n, --cursor TOKEN, --all (walked inside the daemon, paced by the account's own rate limiter).
Also invocable as: tlgr effect list
$ tlgr message effect list --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.message-effects-catalog
Parse or inspect formatted text and its entities.
Offsets are UTF-16 code units, which is the classic third-party client bug: an emoji is one character and two units. Automatic entities are listed separately because the server re-derives them and sending them back is an error.
tlgr message entity list [TEXT] [OPTIONS]
runs without an account · returns EntityReport
| Argument | Type | Required | Meaning |
|---|---|---|---|
TEXT |
text | no | Text to parse; '-' reads stdin. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--entities |
json | Entities to render. | |
--offset-units |
utf16 | codepoint | byte |
--parse |
md | html | none |
--render |
md | html | text |
--stdin |
flag | Read from stdin. |
Also invocable as: tlgr message entities
$ tlgr message entity list --parse md "**hello** world" --jsonCatalog coverage (3 full, 0 partial)
Full: messages-core.entities-detect-local, messages-core.format-entity-offsets-utf16, messages-core.format-raw-entities-json
Read, set or remove a message's fact-check.
tlgr message fact-check set <CHAT> <MSG_ID> [OPTIONS]
mutating · returns FactCheck
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--clear |
flag | Remove the fact-check. | |
--parse |
md | html | none |
--set |
text | Fact-check text. |
$ tlgr message fact-check set @channel 42 --jsonCatalog coverage (2 full, 0 partial)
Full: messages-core.factcheck-edit, messages-core.factcheck-view
Forward or copy messages to one or many chats.
--as-copy is the same call with drop_author and fresh random ids, which is exactly what the GUI's 'forward without quoting' does.
tlgr message forward <CHAT> [MSG_ID]... [OPTIONS]
mutating · returns Page[ForwardedMessage]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Source chat. |
MSG_ID |
text | any number | Ids or ranges. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--as-copy |
flag | Re-send as a new message, not a forward. | |
--comment |
text | Send this alongside the forward. | |
--effect |
text | Animated message effect (private chats). | |
--no-author |
flag | drop_author: hide the sender. | |
--no-captions |
flag | drop_media_captions. | |
--paid-stars |
int | Agree to pay N Stars per message. | |
--protect, --noforwards |
flag | noforwards: block forwarding and saving. | |
--quick-reply |
text | Send through a business quick reply. | |
--repeat |
daily | weekly | biweekly |
--schedule |
text | Send later; 'online' means when the recipient is next online. | |
--send-as |
chat | Post as a channel or anonymously. | |
--silent |
flag | Send without a notification sound. | |
--to |
chat | Destination; repeatable. | |
--topic |
msg-id | Send inside a forum topic. | |
--typing |
number | Show a typing action first. | |
--typing-auto |
flag | Type for a duration estimated from the text length. | |
--video-at |
int | Start at a video timestamp. | |
--with-score |
flag | Keep a game's scoreboard. |
Also invocable as: tlgr msg forward
$ tlgr message forward @alice 12345 --to @bobby --jsonCatalog coverage (8 full, 0 partial)
Full: game.forward, messages-core.forward-as-copy-text, messages-core.forward-basic, messages-core.forward-hide-captions, messages-core.forward-hide-sender, messages-core.forward-options, messages-core.forward-to-many, messages-core.message-select-bulk
A game's high-score table.
tlgr message game get <CHAT> <MSG_ID> [OPTIONS]
returns GameInfo
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Game message id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--url |
flag | Print the HTML5 game URL. | |
--user |
user | Only this player. |
$ tlgr message game get @gamebot 42 --jsonCatalog coverage (1 full, 1 partial)
Full: game.high-scores
Partial: game.play
A CLI cannot render an HTML5 game; --url is refused with NOT_SUPPORTED.
Send a bot game into a chat.
tlgr message game send <CHAT> [OPTIONS]
mutating · returns Message
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--bot |
user | Bot that owns the game. | |
--reply-to |
msg-id | Reply to this id. | |
--short-name |
text | Game short name. | |
--silent |
flag | No notification. | |
--via-inline/--no-via-inline |
flag | True |
Relay the game through an inline query (the user-account path). |
$ tlgr message game send @group --bot @gamebot --short-name corsairs --jsonCatalog coverage (1 full, 0 partial)
Full: game.send
Get one message with its full metadata.
Entities (UTF-16 offsets), forward header, reply context, media summary, reactions including whether this account already reacted, views, and the fact-check when one exists.
tlgr message get <CHAT> <MSG_ID> [OPTIONS]
returns Message
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat the message is in. |
MSG_ID |
msg-id | yes | Message id or link. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--context |
int | Also return N messages around it. | |
--format |
md | html | text |
--full |
flag | Include restriction reasons and raw media. | |
--raw |
flag | Include the raw TL object. | |
--rich |
flag | Fetch the layer-229 rich body. | |
--scheduled |
flag | Read from the scheduled drawer. | |
--vcard-out |
path | Write an attached contact card. | |
--with-reply |
flag | Also resolve the replied-to message. |
Also invocable as: tlgr msg get
$ tlgr message get @alice 12345 --jsonCatalog coverage (16 full, 2 partial)
Full: bots.disabled-button, bots.inline-keyboard-render, bots.invoice-message-view, bots.reply-keyboard-render, calls.history-goto-message, contact.card-fields, dice.read-value, groups-channels-admin.monoforum-message-author, messages-core.message-copy-text, messages-core.message-forward-header, messages-core.message-get, messages-core.message-get-reply-context, messages-core.message-post-author, messages-core.message-restriction-reason, messages-core.reactions-count, messages-core.thread-view-original-post
Partial: bots.rich-message-view, richmsg.get
--rich is refused with NOT_SUPPORTED until Telethon carries layer 229.
Build a t.me link to a message.
A private supergroup produces a t.me/c/<internal id>/<msg id> link that only members can open; public says which form came back.
tlgr message link <CHAT> <MSG_ID> [OPTIONS]
returns LinkResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--at |
duration | Media timestamp. | |
--comment |
int | Link to a specific comment. | |
--embed |
flag | Embeddable link (?embed=1). | |
--poll-option |
int | Preselect a poll option. | |
--public |
flag | Prefer the @username form. | |
--single |
flag | Link to this message only (?single). | |
--task |
int | Link to a checklist task. | |
--topic |
flag | Link into the comment thread. |
$ tlgr message link @durov 42 --jsonCatalog coverage (4 full, 0 partial)
Full: groups-channels-admin.export-message-link, messages-core.message-link-create, poll.option-deep-link, todo.task-deep-link
Read a chat's message history.
Paginated history with the offsets Telegram actually has: older than an id (--before-id), newer than an id (--after-id), centred on one (--around), from a date (--date), only the unread tail (--unread), the scheduled drawer (--scheduled), or one media type (--type).
tlgr message list <CHAT> [OPTIONS]
paginated (HISTORY cursor) · returns Page[Message]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat to read. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--after-id |
msg-id | Newer than this id (min_id). | |
--around |
msg-id | Centre the page on this id. | |
--before-id |
msg-id | Older than this id (offset_id). | |
--date |
datetime | Jump to the first message of a date. | |
--delivery |
flag | Annotate own messages with sent/delivered/read state. | |
--entities/--no-entities |
flag | True |
Include entities. |
--ids |
text | Fetch exactly these ids or ranges. | |
--media/--no-media |
flag | True |
Include media metadata. |
--personal-channel |
user | A profile's channel posts. | |
--reactions/--no-reactions |
flag | True |
Include reactions. |
--reverse |
flag | Oldest first. | |
--saved-peer |
chat | In Saved Messages: one origin. | |
--scheduled |
flag | List the scheduled drawer. | |
--sender |
flag | Include sender info and admin rank. | |
--since |
datetime | Only messages after this time. | |
--topic |
msg-id | Only this topic / thread. | |
--type |
text | Media filter; 'pinned' is the pin list. | |
--unread |
flag | Only messages after the unread divider. | |
--until |
datetime | Only messages before this time. |
Pagination is transport-level: --limit/-n, --cursor TOKEN, --all (walked inside the daemon, paced by the account's own rate limiter).
Also invocable as: tlgr msg list
$ tlgr message list @alice --jsonCatalog coverage (15 full, 0 partial)
Full: bots.payment-service-messages, groupcall.service-messages, groups-channels-admin.monoforum-topic-history, messages-core.history-jump-to-date, messages-core.history-list, messages-core.history-unread-separator, messages-core.message-delivery-status, messages-core.message-jump-to, messages-core.message-sender-rank, messages-core.message-view-in-topic, messages-core.personal-channel-history, messages-core.pinned-list, messages-core.saved-dialog-history, messages-core.scheduled-list, stories.story-mention
Per-user paid-message settings and the Stars they earned.
--refund sends Stars back to the sender, so it is gated behind --yes. The global 'charge non-contacts' switch is a privacy setting and the per-group price is a chat setting; both belong to their own groups.
tlgr message paid set [USER] [OPTIONS]
mutating · returns PaidMessageSettings
| Argument | Type | Required | Meaning |
|---|---|---|---|
USER |
user | no | User. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--channel |
chat | Scope --revenue to a channel. | |
--charge |
flag | Re-enable the per-message fee. | |
--exempt |
flag | Let this user message me for free. | |
--refund |
flag | With --exempt: refund the Stars paid. | |
--revenue |
flag | Report Stars earned from paid messages. |
$ tlgr message paid set @alice --exempt --jsonCatalog coverage (2 full, 0 partial)
Full: messages-core.paid-messages-exempt-user, messages-core.paid-messages-revenue
Pin a message in a chat.
The pinned list is message list --type pinned.
tlgr message pin <CHAT> <MSG_ID> [OPTIONS]
mutating · idempotent (reports already) · returns PinResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id or link. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--both-sides |
flag | Also pin on the other side of a private chat. | |
--notify |
flag | Notify members (a pin is silent by default). | |
--topic |
msg-id | Pin inside a forum topic. |
Also invocable as: tlgr msg pin
$ tlgr message pin @alice 12345 --jsonCatalog coverage (3 full, 0 partial)
Full: groups-channels-admin.monoforum-pin, groups-channels-admin.pinned-messages, messages-core.pin-message
Fetch the link preview Telegram would attach to a URL.
Sending that preview as the media is message send --preview-url.
tlgr message preview <URL> [OPTIONS]
returns WebPagePreview
| Argument | Type | Required | Meaning |
|---|---|---|---|
URL |
text | yes | URL to preview. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--refresh |
flag | Bypass the cached webpage hash. |
$ tlgr message preview https://telegram.org --jsonCatalog coverage (1 full, 0 partial)
Full: webpage.preview-fetch
Mark a chat, thread, mentions or media contents as read.
A read receipt is visible to the other side and it also clears the badge in the account owner's own client, which may be their only reminder that they owe a reply.
tlgr message read <CHAT> [OPTIONS]
mutating · idempotent (reports already) · returns ReadResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat to mark read. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--contents |
text | Mark voice notes / round videos as listened. | |
--direct-to |
user | Read one monoforum topic. | |
--mentions |
flag | Mark all unread mentions as read. | |
--reactions |
flag | Mark all unread reactions as read. | |
--saved-peer |
chat | Read one saved dialog. | |
--topic |
msg-id | Read one forum topic. | |
--up-to |
msg-id | Read up to this id (default: latest). |
Also invocable as: tlgr msg read
$ tlgr message read @alice --jsonCatalog coverage (6 full, 0 partial)
Full: messages-core.monoforum-topic-manage, messages-core.read-mark-history, messages-core.read-message-contents, messages-core.report-message-delivery, messages-core.thread-read, messages-core.unread-mentions-read-all
Who read this message, and when.
tlgr message read-receipt list <CHAT> <MSG_ID> [OPTIONS]
returns ReadReceipts
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--users/--no-users |
flag | True |
Resolve reader ids to user objects. |
Also invocable as: tlgr message readers, tlgr msg read-receipts, tlgr message read-receipts
$ tlgr message read-receipt list @alice 12345 --jsonCatalog coverage (2 full, 0 partial)
Full: messages-core.read-date-private, messages-core.read-participants-group
Report messages for abuse.
The first call returns the option menu; pass --option to walk it. Reporting a chat or a user (rather than messages) belongs to the chat/user groups.
tlgr message report <CHAT> [MSG_ID]... [OPTIONS]
mutating · returns ReportResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
text | any number | Message ids. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--comment |
text | Free-text comment. | |
--from |
user | Report a member as spam. | |
--list-options |
flag | Return the report menu instead of reporting. | |
--not-spam |
flag | Report an anti-spam false positive. | |
--option |
text | Report-option key; repeatable. |
$ tlgr message report @channel 42 --list-options --jsonCatalog coverage (3 full, 0 partial)
Full: messages-core.report-antispam-false-positive, messages-core.report-message, messages-core.report-spam-participant
Send scheduled messages now.
Listing, editing and deleting the drawer are flags elsewhere: message list --scheduled, message edit --schedule, message delete --scheduled.
tlgr message scheduled send <CHAT> [MSG_ID]... [OPTIONS]
mutating · returns Page[ScheduledSent]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
text | one or more | Scheduled message ids. |
$ tlgr message scheduled send @alice 999 --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.scheduled-send-now
Search messages inside one chat.
Every filter messages.search has: text, sender, media type, date range, topic, saved dialog and reaction tag. --regex is a bounded local scan and says so, because Telegram has no regex search.
tlgr message search <CHAT> [QUERY] [OPTIONS]
paginated (SEARCH cursor) · returns Page[Message]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat to search. |
QUERY |
text | no | Text to find. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--calendar |
flag | Return the message calendar. | |
--count |
flag | Return per-filter counters instead of messages. | |
--from |
user | Only from this sender. | |
--hashtag |
text | Shorthand for '#tag'. | |
--ids |
text | Restrict to these ids. | |
--max-id |
int | Only ids below this. | |
--min-id |
int | Only ids above this. | |
--position |
int | Where this id sits in the filtered set. | |
--regex |
text | Client-side regex over the scan. | |
--reverse |
flag | Oldest first. | |
--saved-peer |
chat | One Saved-Messages dialog. | |
--scan |
int | 1000 |
How many messages --regex may scan. |
--scheduled |
flag | Search the scheduled drawer. | |
--since |
datetime | Only after this time. | |
--tag |
text | Saved-Messages reaction tag (Premium). | |
--topic |
msg-id | Restrict to a topic. | |
--type |
text | Media filter. | |
--until |
datetime | Only before this time. |
Pagination is transport-level: --limit/-n, --cursor TOKEN, --all (walked inside the daemon, paced by the account's own rate limiter).
Also invocable as: tlgr msg search
$ tlgr message search @alice "invoice" --jsonCatalog coverage (15 full, 0 partial)
Full: messages-core.message-position-in-filter, messages-core.saved-tags-search, messages-core.search-calendar-positions, messages-core.search-counters, messages-core.search-date-range, messages-core.search-filter-media-type, messages-core.search-calls-log, messages-core.search-from-user, messages-core.search-hashtag-in-chat, messages-core.search-in-chat-text, messages-core.search-in-saved-dialog, messages-core.search-in-topic, messages-core.search-local-regex, poll.search, reaction.search-by-tag
Send a message to a chat.
The universal composer: text, a file, an album, a sticker, a voice note, a dice, a contact card or a location, with every send-time option Telegram exposes. Text longer than 4096 UTF-16 units is refused unless --split is given, because silently truncating a message is worse than not sending it.
tlgr message send <CHAT> [TEXT] [OPTIONS]
mutating · returns Message
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Target chat or user. |
TEXT |
text | no | Message text; '-' reads stdin. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--as-file |
flag | Send the text as a .txt document. | |
--caption |
text | Caption for the attached media. | |
--caption-above |
flag | invert_media. | |
--clear-draft/--no-clear-draft |
flag | True |
Clear the chat draft on send. |
--comment-to |
int | Comment on a channel post. | |
--contact |
user | Send a contact card for a user. | |
--contact-first |
text | Contact first name. | |
--contact-last |
text | Contact last name. | |
--contact-phone |
text | Contact card phone. | |
--dice |
text | Send an animated dice/darts/slot. | |
--direct-to |
user | Answer in a monoforum topic. | |
--effect |
text | Animated message effect (private chats). | |
--entities |
json | Explicit entity vector (UTF-16). | |
--file |
text | Attach a file; repeat for an album. | |
--filename |
text | Filename for --as-file/stdin. | |
--gif |
text | Send a GIF/animation. | |
--invert-media |
flag | Alias of --preview-above/--caption-above. | |
--location |
text | Attach a static location. | |
--no-preview |
flag | Disable the link preview. | |
--paid-stars |
int | Agree to pay N Stars per message. | |
--parse |
md | html | none |
--poll |
json | Attach a poll. | |
--preview-above |
flag | Preview above the text. | |
--preview-large |
flag | force_large_media. | |
--preview-small |
flag | force_small_media. | |
--preview-url |
text | Preview this URL. | |
--price-stars |
int | Stars asked for the suggested post. | |
--price-ton |
int | TON asked for the suggested post. | |
--protect, --noforwards |
flag | noforwards: block forwarding and saving. | |
--publish-at |
datetime | Requested publication time. | |
--quick-reply |
text | Send through a business quick reply. | |
--quote |
text | Quote this exact substring of the replied message. | |
--quote-offset |
int | UTF-16 offset of --quote. | |
--random-id |
int | Explicit random_id so a retry is deduplicated. | |
--repeat |
daily | weekly | biweekly |
--reply-in |
chat | Chat --reply-to belongs to. | |
--reply-poll-option |
int | Reply to a poll option index. | |
--reply-task |
int | Reply to a checklist task id. | |
--reply-to |
msg-id | Reply to this message. | |
--reply-to-story |
int | Reply to a story of CHAT. | |
--rich-html |
path | Send a rich body (HTML). | |
--rich-markdown |
path | Send a rich body (Markdown). | |
--schedule |
text | Send later; 'online' means when the recipient is next online. | |
--screenshot |
flag | Send a screenshot-taken service notification. | |
--send-as |
chat | Post as a channel or anonymously. | |
--silent |
flag | Send without a notification sound. | |
--split |
flag | Split text longer than the limit. | |
--split-at |
int | 4096 |
Split threshold. |
--spoiler |
flag | Hide the media behind a spoiler. | |
--stdin |
flag | Read the body from stdin. | |
--sticker |
text | Send a sticker. | |
--suggest |
flag | Offer this as a suggested post. | |
--topic |
msg-id | Send inside a forum topic. | |
--ttl |
duration | Self-destruct timer. | |
--typing |
number | Show a typing action first. | |
--typing-auto |
flag | Type for a duration estimated from the text length. | |
--vcard |
path | vCard payload. | |
--video-note |
path | Send a round video. | |
--voice |
path | Send as a voice note. | |
--wait-slowmode |
flag | Wait out slow mode instead of failing. |
Also invocable as: tlgr send, tlgr msg send
$ tlgr message send @alice "on my way" --jsonCatalog coverage (55 full, 2 partial)
Full: bots.button-styles-icons, bots.paid-broadcast-floodskip, bots.paid-message-to-bot, bots.reply-keyboard-hide-force, bots.send-with-keyboard, contact.send-card, dialogs.draft-send, dice.send, effect.send, media.link-preview, messages-core.comments-post, messages-core.format-basic-styles, messages-core.format-blockquote, messages-core.format-code-and-pre, messages-core.format-custom-emoji, messages-core.format-expandable-blockquote, messages-core.format-formatted-date-entity, messages-core.format-hashtag-cashtag, messages-core.format-html-parse-mode, messages-core.format-markdown-parse-mode, messages-core.format-mention, messages-core.format-spoiler, messages-core.format-text-link, messages-core.link-preview-above-text, messages-core.link-preview-choose-url-and-size, messages-core.link-preview-disable, messages-core.reply-in-another-chat, messages-core.reply-to-checklist-task-or-poll-option, messages-core.reply-to-story, messages-core.reply-with-quote, messages-core.saved-messages-send, messages-core.saved-reminder, messages-core.screenshot-notification, messages-core.send-as-peer, messages-core.send-clear-draft, messages-core.send-in-direct-channel-messages, messages-core.send-long-text-split, messages-core.send-paid-message, messages-core.send-preflight-restrictions, messages-core.send-protected-content-message, messages-core.send-reply, messages-core.send-scheduled, messages-core.send-scheduled-repeating, messages-core.send-silent, messages-core.send-text, messages-core.send-text-as-file, messages-core.send-to-topic, messages-core.send-when-online, messages-core.send-with-effect, messages-core.suggest-post, poll.reply-to-option, todo.reply-to-task, updates.invoke-after-msg, updates.sync-random-id-dedup, webpage.send-as-media
Partial: messages-core.send-rich-message, richmsg.send
A layer-229 rich body is refused with NOT_SUPPORTED: the pinned Telethon speaks layer 227 and cannot serialise inputRichMessage*.
Hide sponsored messages for my account or my channel.
tlgr message sponsored hide [STATE] [OPTIONS]
mutating · idempotent (reports already) · returns SponsoredHidden
| Argument | Type | Required | Meaning |
|---|---|---|---|
STATE |
text | no | on = hide ads. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--chat |
chat | Disable ads in this channel instead. |
Also invocable as: tlgr ads hide
$ tlgr message sponsored hide on --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.sponsored-hide
List the sponsored messages a chat would show.
tlgr message sponsored list <CHAT> [OPTIONS]
returns Page[SponsoredMessage]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel or bot chat. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--mark-viewed |
flag | Also report the impressions. |
Also invocable as: tlgr ads list
$ tlgr message sponsored list @durov --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.sponsored-list
Report or click through a sponsored message.
tlgr message sponsored report <CHAT> <RANDOM_ID> [OPTIONS]
mutating · returns ReportResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat the ad appeared in. |
RANDOM_ID |
text | yes | Ad id from sponsored list. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--click |
flag | Report a click instead of a report. | |
--media |
flag | With --click: the click was on the media. | |
--option |
text | Report-option key from the menu. |
Also invocable as: tlgr ads report
$ tlgr message sponsored report @durov abc123 --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.sponsored-interact
Approve a suggested post.
Approving a paid suggestion spends the channel's Stars, so it needs --yes.
tlgr message suggested approve <CHAT> <MSG_ID> [OPTIONS]
mutating · destructive (needs --yes off a TTY) · returns SuggestedPostState
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel. |
MSG_ID |
msg-id | yes | Suggested post id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--price-stars |
int | Counter-offer in Stars. | |
--price-ton |
int | Counter-offer in TON. | |
--publish-at |
datetime | Publish then, not now. |
$ tlgr message suggested approve @channel 42 --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.suggested-post-approve-decline
Decline a suggested post.
tlgr message suggested deny <CHAT> <MSG_ID> [OPTIONS]
mutating · returns SuggestedPostState
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel. |
MSG_ID |
msg-id | yes | Suggested post id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--comment |
text | Reason sent back to the author. |
Also invocable as: tlgr message suggested decline
$ tlgr message suggested deny @channel 42 --jsonCatalog coverage (0 full, 1 partial)
Partial: messages-core.suggested-post-approve-decline
The decline half; message suggested approve covers the approve half.
Change your own pending suggested post.
Price bounds come from appConfig's stars_suggested_post_amount_min/max.
tlgr message suggested edit <CHAT> <MSG_ID> [OPTIONS]
mutating · returns SuggestedPostState
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel. |
MSG_ID |
msg-id | yes | My suggested post. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--add-offer |
flag | Attach a new offer to an already-sent post. | |
--price-stars |
int | New asking price in Stars. | |
--price-ton |
int | New asking price in TON. | |
--publish-at |
datetime | New requested publication time. | |
--text |
text | New text. |
$ tlgr message suggested edit @channel 42 --text "new copy" --jsonCatalog coverage (3 full, 0 partial)
Full: groups-channels-admin.suggested-post-counter-offer, groups-channels-admin.suggested-post-send, messages-core.suggested-post-edit-own-offer
Summarize a long message with AI.
Shares its quota with message compose; Premium raises it.
tlgr message summarize <CHAT> <MSG_ID> [OPTIONS]
returns SummaryResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Message id. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--lang, --to |
text | Summarize into this language. | |
--tone |
text | Composition tone. |
$ tlgr message summarize @alice 12345 --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.summarize-message
Disable comments on a single channel post.
Irreversible: the only mechanism Telegram offers is deleting the post's copy in the linked discussion group, which deletes the comments with it.
tlgr message thread disable <CHAT> <MSG_ID> [OPTIONS]
mutating · destructive (needs --yes off a TTY) · returns SuggestedPostState
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel. |
MSG_ID |
msg-id | yes | Post id. |
$ tlgr message thread disable @channel 4242 --jsonCatalog coverage (1 full, 0 partial)
Full: messages-core.comments-disable-on-post
List the replies of a thread or the comments under a post.
tlgr message thread list <CHAT> <ROOT_ID> [OPTIONS]
paginated (HISTORY cursor) · returns Page[Message]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel or group. |
ROOT_ID |
msg-id | yes | Post or thread root. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--around |
msg-id | Centre on a comment. | |
--resolve/--no-resolve |
flag | True |
Resolve the post into its discussion thread first. |
--reverse |
flag | Oldest first. |
Pagination is transport-level: --limit/-n, --cursor TOKEN, --all (walked inside the daemon, paced by the account's own rate limiter).
Also invocable as: tlgr message comments
$ tlgr message thread list @channel 4242 --jsonCatalog coverage (3 full, 0 partial)
Full: groups-channels-admin.comments-thread, messages-core.comments-view, messages-core.thread-view-replies
Delete a composition tone you authored.
tlgr message tone delete <SLUG> [OPTIONS]
mutating · destructive (needs --yes off a TTY) · returns Tone
| Argument | Type | Required | Meaning |
|---|---|---|---|
SLUG |
text | yes | Tone I authored. |
Also invocable as: tlgr ai tone delete
$ tlgr message tone delete formal --jsonCatalog coverage (0 full, 1 partial)
Partial: ai.tone-edit
The delete half of ai.tone-edit; message tone set covers the edit half.
Show one composition tone and preview it.
Examples are generated server-side and spend the AI quota.
tlgr message tone get <SLUG> [OPTIONS]
returns Tone
| Argument | Type | Required | Meaning |
|---|---|---|---|
SLUG |
text | yes | Tone slug. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--example |
int | 1 |
Generate N example rewrites. |
Also invocable as: tlgr ai tone get
$ tlgr message tone get formal --jsonCatalog coverage (1 full, 0 partial)
Full: ai.tone-example
List AI composition tones.
tlgr message tone list [OPTIONS]
paginated (LOCAL cursor) · returns Page[Tone]
| Flag | Type | Default | Meaning |
|---|---|---|---|
--installed |
flag | Only tones I installed. | |
--mine |
flag | Only tones I authored. | |
--refresh |
flag | Ignore the cached hash. |
Pagination is transport-level: --limit/-n, --cursor TOKEN, --all (walked inside the daemon, paced by the account's own rate limiter).
Also invocable as: tlgr ai tone list
$ tlgr message tone list --jsonCatalog coverage (3 full, 0 partial)
Full: ai.tones-list, appearance.ai-compose-tones, messages-core.ai-compose-tones
Create, edit or install a composition tone.
tlgr message tone set [SLUG] [OPTIONS]
mutating · returns Tone
| Argument | Type | Required | Meaning |
|---|---|---|---|
SLUG |
text | no | Existing tone; omit with --new. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--credit-me |
flag | Show me as the author. | |
--emoji-id |
int | Custom emoji icon (Premium). | |
--install |
flag | Install a shared tone. | |
--new |
flag | Create a new tone. | |
--prompt |
text | Tone prompt. | |
--title |
text | Tone title. | |
--uninstall |
flag | Uninstall it. |
Also invocable as: tlgr ai tone set
$ tlgr message tone set --new --title Formal --prompt "Rewrite formally" --jsonCatalog coverage (3 full, 0 partial)
Full: ai.tone-create, ai.tone-edit, ai.tone-install
Transcribe a voice note or round video.
tlgr message transcribe <CHAT> <MSG_ID> [OPTIONS]
returns Transcription
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | yes | Voice or round video. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--rate |
good | bad | |
--wait/--no-wait |
flag | True |
Poll until the transcription is final. |
$ tlgr message transcribe @alice 12345 --jsonCatalog coverage (1 full, 0 partial)
Full: media.transcribe-voice
Translate messages or text into a target language.
tlgr message translate [CHAT] [MSG_ID]... [OPTIONS]
returns Page[Translation]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | no | Chat. |
MSG_ID |
text | any number | Message ids. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--lang, --to |
text | Target language code. | |
--rich |
flag | Translate a layer-229 rich body. | |
--text |
text | Translate this text instead. |
$ tlgr message translate @alice 12345 --lang en --jsonCatalog coverage (2 full, 2 partial)
Full: dialogs.translate-messages, messages-core.translate-message
Partial: bots.rich-message-translate, richmsg.translate
Rich-body translation is layer 229 and refused with NOT_SUPPORTED.
Unpin one message or every pinned message.
tlgr message unpin <CHAT> [MSG_ID] [OPTIONS]
mutating · destructive (needs --yes off a TTY) · idempotent (reports already) · returns PinResult
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Chat. |
MSG_ID |
msg-id | no | Message id; omit with --all. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--direct-to |
user | Only this monoforum topic. | |
--topic |
msg-id | Only this forum topic. | |
--all |
flag | Unpin everything. |
Also invocable as: tlgr msg unpin
$ tlgr message unpin @alice 12345 --jsonCatalog coverage (2 full, 0 partial)
Full: messages-core.unpin-all, messages-core.unpin-message
Views and forwards counters for channel posts.
tlgr message view get <CHAT> [MSG_ID]... [OPTIONS]
returns Page[ViewCount]
| Argument | Type | Required | Meaning |
|---|---|---|---|
CHAT |
chat | yes | Channel. |
MSG_ID |
text | one or more | Post ids or ranges. |
| Flag | Type | Default | Meaning |
|---|---|---|---|
--increment |
flag | Actually register a view (off by default). | |
--listened-seconds |
int | Report real audio playback seconds. |
Also invocable as: tlgr message views
$ tlgr message view get @durov 42 --jsonCatalog coverage (2 full, 0 partial)
Full: messages-core.message-views-forwards, messages-core.report-music-listen