Skip to content
Sending Messages

Sending Messages

tguser can send text and various media types from your account. Before sending, you must sign in.

Where to Send: the Target (--to)

The target is the recipient. It is specified via the --to flag or positionally. Supported forms:

Target typeExample
Saved chat name (alias)--to work
Numeric ID--to -1001234567890
Username--to @durov
Saved Messages (yourself)--to me

Aliases are configured with the chat command — see 04. Chat Management. Don’t know the numeric ID? See 08. Chat Discovery.

Two Syntaxes

All media commands accept arguments in two ways — pick whichever you prefer:

# via flags
tguser sendphoto a.png b.png --to work --caption "Photos"

# positionally
tguser sendphoto a.png b.png work "Photos"

How positional arguments are parsed: consecutive leading tokens that exist as files on disk are treated as content; the next token is the target (if --to is not set), and the token after it is the caption (if --caption is not set).

Therefore, if a file at the given path does not exist, it will be mistaken for the target. Check your paths.

Command Overview

CommandWhat it sendsCaption (--caption)
sendText message— (extra text)
sendfileFile(s) as a document✓
sendphotoPhoto (multiple → album)✓
sendvideoVideo (multiple → album)✓
sendaudioAudio / music✓
sendvoiceVoice message✓
sendvideonoteVideo note—
sendstickerSticker (.tgs/.webp)—
sendcontactContact—

Text

tguser send "Hello!" --to work
tguser send "Hello!" work            # positionally

The --caption flag is optional for text; if set, its value is appended to the message after a blank line:

tguser send "Title" --to me --caption "Details below"

Files (Documents)

tguser sendfile report.pdf --to work --caption "Report"
tguser sendfile a.zip b.zip --to work          # multiple documents
tguser sendfile a.zip b.zip --to work --group  # group into an album

Without --group, documents are sent as separate messages. With -G/--group, multiple documents are sent as an album. Telegram allows up to 10 documents per album, so larger sets are automatically split into groups of 10. The caption applies only to the first document of the entire send.

Photos

tguser sendphoto photo.png --to me --caption "Screenshot"
tguser sendphoto p1.png p2.png p3.png --to work --caption "Gallery"

With two or more files, photos are sent as an album; the caption applies to the first photo.

Video

tguser sendvideo clip.mp4 --to me --caption "Recording"
tguser sendvideo a.mp4 b.mp4 --to work          # album

Audio / Music

tguser sendaudio track.mp3 --to me --caption "Track"
tguser sendaudio one.mp3 two.mp3 --to me        # multiple tracks

Voice Message

tguser sendvoice voice.ogg --to me --caption "Voice"

Video Note

tguser sendvideonote note.mp4 --to me

Sticker

tguser sendsticker sticker.webp --to me

Contact

Send a contact (name + phone number):

# via flags
tguser sendcontact --phone +15551234567 --first-name John --last-name Doe --to work

# positionally: <phone> <first> [last] <target>
tguser sendcontact +15551234567 John Doe work
tguser sendcontact +15551234567 John work          # without a last name
FlagDescription
--phonePhone number (required)
--first-nameFirst name (required)
--last-nameLast name (optional)
--toTarget

Result

On a successful send, a panel is shown:

╭──────── ✓ Done ────────╮
│ Sent to work           │
╰─────────────────────────╯

If something goes wrong, see 07. Troubleshooting.