Media & Files

Media can be sent in 3 ways:

By URL — Provide an HTTP/HTTPS URL. Telegram downloads and sends it.
By File ID — Reuse a file already uploaded to Telegram’s servers.
By InputFile — Upload raw bytes generated in your code (e.g., User.getDataFile()).

sendPhoto

Sends a photo to a chat.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID or `@username`.
`photo`	String	Yes	URL, file ID, or InputFile of the photo.
`caption`	String	No	Photo caption (up to 1024 characters).
`parse_mode`	String	No	`"HTML"`, `"Markdown"`, or `"MarkdownV2"`.
`has_spoiler`	Boolean	No	If `True`, the photo is blurred until tapped.
`disable_notification`	Boolean	No	Sends silently.
`reply_to_message_id`	Integer	No	Reply to a specific message.
`reply_markup`	Object	No	Inline or reply keyboard.

BLP Example

# By URL
Bot.sendPhoto(
    chat_id=u,
    photo="https://example.com/image.jpg",
    caption="Here is a beautiful photo!",
    parse_mode="HTML"
)

# By File ID (reuse an existing photo)
Bot.sendPhoto(
    chat_id=u,
    photo="AgACAgIAAxkBAAMrZN...",
    caption="Reusing an uploaded photo."
)

# With spoiler blur
Bot.sendPhoto(
    chat_id=u,
    photo="https://example.com/surprise.jpg",
    has_spoiler=True,
    caption="Tap to reveal!"
)

sendAudio

Sends an audio file displayed in Telegram’s music player. Must be .MP3 or .M4A.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`audio`	String	Yes	URL, file ID, or InputFile of the audio.
`caption`	String	No	Caption (up to 1024 characters).
`parse_mode`	String	No	Formatting mode.
`duration`	Integer	No	Duration in seconds.
`performer`	String	No	Name of the performer.
`title`	String	No	Track title.
`thumbnail`	String	No	Thumbnail image URL or file ID.

BLP Example

Bot.sendAudio(
    chat_id=u,
    audio="https://example.com/song.mp3",
    caption="Listen to this track!",
    performer="Artist Name",
    title="Song Title",
    duration=210
)

sendDocument

Sends a general file.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`document`	String or InputFile	Yes	URL, file ID, or InputFile.
`caption`	String	No	Caption (up to 1024 characters).
`parse_mode`	String	No	Formatting mode.
`thumbnail`	String	No	Thumbnail image.
`disable_content_type_detection`	Boolean	No	Disables automatic content type detection.

BLP Example

# By URL
Bot.sendDocument(
    chat_id=u,
    document="https://example.com/file.pdf",
    caption="Here is the PDF file."
)

# Upload a dynamically generated file
file = User.getAllDataOfUser(u, output_format="json")
Bot.sendDocument(
    chat_id=u,
    document=file,
    caption="Your data export is ready!"
)

sendVideo

Sends a video file. Telegram clients support .MP4 videos.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`video`	String	Yes	URL, file ID, or InputFile.
`caption`	String	No	Caption (up to 1024 characters).
`parse_mode`	String	No	Formatting mode.
`duration`	Integer	No	Duration in seconds.
`width`	Integer	No	Video width.
`height`	Integer	No	Video height.
`thumbnail`	String	No	Thumbnail image.
`supports_streaming`	Boolean	No	If `True`, enables streaming playback.
`has_spoiler`	Boolean	No	Blurs the video until tapped.

BLP Example

Bot.sendVideo(
    chat_id=u,
    video="https://example.com/video.mp4",
    caption="Check out this video!",
    supports_streaming=True,
    width=1280,
    height=720
)

sendAnimation

Sends an animation (GIF or H.264/MPEG-4 video without sound).

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`animation`	String	Yes	URL, file ID, or InputFile.
`caption`	String	No	Caption (up to 1024 characters).
`parse_mode`	String	No	Formatting mode.
`duration`	Integer	No	Duration in seconds.
`width`	Integer	No	Animation width.
`height`	Integer	No	Animation height.
`has_spoiler`	Boolean	No	Blurs the animation until tapped.

BLP Example

Bot.sendAnimation(
    chat_id=u,
    animation="https://example.com/funny.gif",
    caption="Funny animation!"
)

sendVoice

Sends a voice message. Audio must be in .OGG format encoded with OPUS.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`voice`	String	Yes	URL, file ID, or InputFile of the `.ogg` audio.
`caption`	String	No	Caption.
`parse_mode`	String	No	Formatting mode.
`duration`	Integer	No	Duration in seconds.

BLP Example

Bot.sendVoice(
    chat_id=u,
    voice="https://example.com/voice.ogg",
    duration=30
)

sendVideoNote

Sends a rounded video note (max 1 minute). Used as video messages in Telegram.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`video_note`	String	Yes	URL, file ID, or InputFile. Must be square.
`duration`	Integer	No	Duration in seconds.
`length`	Integer	No	Video width/height (equal for square videos).
`thumbnail`	String	No	Thumbnail image.

BLP Example

Bot.sendVideoNote(
    chat_id=u,
    video_note="https://example.com/note.mp4",
    length=360,
    duration=30
)

sendMediaGroup

Sends a group of photos, videos, documents, or audios as an album.

Note: Only same-type media can be grouped together (e.g., only photos or only videos). Up to 10 items per group.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`media`	JSON String	Yes	A JSON-encoded array of `InputMedia` objects.
`disable_notification`	Boolean	No	Sends silently.

BLP Example

media_group = [
    {
        "type": "photo",
        "media": "https://example.com/photo1.jpg",
        "caption": "Photo 1"
    },
    {
        "type": "photo",
        "media": "https://example.com/photo2.jpg"
    },
    {
        "type": "photo",
        "media": "https://example.com/photo3.jpg"
    }
]

Bot.sendMediaGroup(
    chat_id=u,
    media=jsondumps(media_group)
)

editMessageMedia

Edits the media content of an existing message (animation, audio, document, photo, or video).

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Chat ID of the message to edit.
`message_id`	Integer	Yes	ID of the message to edit.
`media`	JSON String	Yes	JSON-encoded `InputMedia` object with the new media.
`reply_markup`	Object	No	New inline keyboard to attach.

InputMedia types: photo, video, animation, audio, document

BLP Example

new_media = {
    "type": "photo",
    "media": "https://example.com/new_photo.jpg",
    "caption": "Updated photo!"
}

Bot.editMessageMedia(
    chat_id=u,
    message_id=message.message_id,
    media=jsondumps(new_media)
)

sendSticker

Sends a static or animated .WEBP sticker.

Parameter	Type	Required	Description
`chat_id`	Integer or String	Yes	Target chat ID.
`sticker`	String	Yes	File ID of the sticker.
`emoji`	String	No	Emoji associated with the sticker.
`reply_to_message_id`	Integer	No	Reply to a message.

BLP Example

# Get sticker file_id from a received sticker message
sticker_id = message.sticker.file_id

Bot.sendSticker(
    chat_id=u,
    sticker=sticker_id
)

getFile

Gets basic info about a file and prepares it for downloading.

Parameter	Type	Required	Description
`file_id`	String	Yes	File identifier to get info about.

BLP Example

result = Bot.getFile(file_id=message.document.file_id)
file_path = result.result.file_path
download_url = f"https://api.telegram.org/file/bot{bot_token}/{file_path}"

Bot.sendMessage(chat_id=u, text=f"Download: {download_url}")

Getting Started

Language Reference

Telegram API Methods

Core Libraries (Libs)

Advanced & Tools

sendPhoto

sendAudio

sendDocument

sendVideo

sendAnimation

sendVoice

sendVideoNote

sendMediaGroup

editMessageMedia

sendSticker

getFile

​sendPhoto

​sendAudio

​sendDocument

​sendVideo

​sendAnimation

​sendVoice

​sendVideoNote

​sendMediaGroup

​editMessageMedia

​sendSticker

​getFile

sendPhoto

sendAudio

sendDocument

sendVideo

sendAnimation

sendVoice

sendVideoNote

sendMediaGroup

editMessageMedia

sendSticker

getFile