editMessageMedia

Returns: Message | True📎 Accepts files⌨️ KeyboardsOfficial docs ↗

Use this method to edit animation, audio, document, photo, or video messages, or to add media to text messages. If a message is part of a message album, then it can be edited only to an audio for audio albums, only to a document for document albums and to a photo or a video otherwise. When an inline message is edited, a new file can't be uploaded; use a previously uploaded file via its file_id or specify a URL. On success, if the edited message is not an inline message, the edited Message is returned, otherwise True is returned. Note that business messages that were not sent by the bot and do not contain an inline keyboard can only be edited within 48 hours from the time they were sent.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the message to be edited was sent

chat_idIntegerStringOptional

Required if inline\message\id is not specified. Unique identifier for the target chat or username of the target channel (in the format @channelusername)

message_idIntegerOptional

Required if inline\message\id is not specified. Identifier of the message to edit

inline_message_idStringOptional

Required if chat\id and message\id are not specified. Identifier of the inline message

mediaInputMediaRequired

A JSON-serialized object for a new media content of the message

reply_markupInlineKeyboardMarkupOptional⌨️ Keyboards

A JSON-serialized object for a new inline keyboard.

Returns

On success, Message | True is returned.

GramIO Usage

// Replace a message's photo from a callback_query handler
bot.on("callback_query", async (ctx) => {
    await ctx.editMedia(
        MediaInput.photo(await MediaUpload.url("https://example.com/new-photo.jpg")),
    );
    await ctx.answer();
});

// Replace media and update caption at the same time
bot.on("callback_query", async (ctx) => {
    await ctx.editMedia(
        MediaInput.video(await MediaUpload.path("./promo.mp4"), {
            caption: "Watch this!",
            supports_streaming: true,
        }),
    );
    await ctx.answer();
});

// Direct API call — replace media using a previously uploaded file_id
await bot.api.editMessageMedia({
    chat_id: 123456789,
    message_id: 42,
    media: MediaInput.photo("AgACAgIAAxkBAAI..."),  // file_id of an already uploaded photo
});

Errors

Code	Error	Cause
400	Bad Request: message is not modified	New media content is identical to the current one
400	Bad Request: message can't be edited	Message too old, sent by another bot, or the media type swap is disallowed by album restrictions
400	Bad Request: wrong file identifier/HTTP URL specified	file_id is invalid or the URL is inaccessible — verify the source
400	Bad Request: PHOTO_INVALID_DIMENSIONS	Uploaded image dimensions exceed Telegram's limits
400	Bad Request: chat not found	Invalid or inaccessible chat_id
400	Bad Request: message not found	message_id doesn't exist in the chat
403	Forbidden: bot was blocked by the user	User blocked the bot — catch and mark user as inactive
403	Forbidden: not enough rights	Bot lacks edit permissions in a channel
429	Too Many Requests: retry after N	Flood control — check retry_after, use auto-retry plugin

TIP

Use GramIO's auto-retry plugin to handle 429 errors automatically.

Tips & Gotchas

• Cannot upload new files for inline messages. When editing via inline_message_id, you must provide a file_id of a previously uploaded file or a public URL — local file uploads are rejected.
• Album (media group) type restrictions are strict. If the message is part of an album, you can only swap: audio in an audio album, document in a document album, and photo or video in any other album. Attempting to change the type causes a message can't be edited error.
• Can convert a plain text message to a media message. If the original message contained only text, you can add media to it using this method.
• Caption and media are edited atomically. Set the caption field inside the InputMedia* object (not a top-level param) to update the caption at the same time as the media.
• Business messages have a 48-hour edit window. Messages sent via a business connection by another user without an inline keyboard can only be edited within 48 hours of sending.
• Inline messages return true, not Message. When editing via inline_message_id, the method returns true on success instead of the updated Message object.

See Also

• editMessageCaption — edit only the caption without replacing the media
• editMessageText — edit a text message
• editMessageReplyMarkup — update only the inline keyboard
• Media input guide — MediaInput helpers for building InputMedia objects
• Media upload guide — MediaUpload.path(), .url(), .buffer() for file handling
• InputMedia — the union type accepted by the media parameter
• Keyboards overview — building inline keyboards with InlineKeyboard
• Message — the type returned on success for non-inline messages
• auto-retry plugin — automatic 429 retry handling