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 type | Example |
|---|---|
| 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
| Command | What it sends | Caption (--caption) |
|---|---|---|
send | Text message | — (extra text) |
sendfile | File(s) as a document | ✓ |
sendphoto | Photo (multiple → album) | ✓ |
sendvideo | Video (multiple → album) | ✓ |
sendaudio | Audio / music | ✓ |
sendvoice | Voice message | ✓ |
sendvideonote | Video note | — |
sendsticker | Sticker (.tgs/.webp) | — |
sendcontact | Contact | — |
Text
tguser send "Hello!" --to work
tguser send "Hello!" work # positionallyThe --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 albumWithout --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 # albumAudio / Music
tguser sendaudio track.mp3 --to me --caption "Track"
tguser sendaudio one.mp3 two.mp3 --to me # multiple tracksVoice Message
tguser sendvoice voice.ogg --to me --caption "Voice"Video Note
tguser sendvideonote note.mp4 --to meSticker
tguser sendsticker sticker.webp --to meContact
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| Flag | Description |
|---|---|
--phone | Phone number (required) |
--first-name | First name (required) |
--last-name | Last name (optional) |
--to | Target |
Result
On a successful send, a panel is shown:
╭──────── ✓ Done ────────╮
│ Sent to work │
╰─────────────────────────╯If something goes wrong, see 07. Troubleshooting.