sendAnimation

Returns: Message📎 Accepts files✏️ Formattable text⌨️ KeyboardsOfficial docs ↗

Use this method to send animation files (GIF or H.264/MPEG-4 AVC video without sound). On success, the sent Message is returned. Bots can currently send animation files of up to 50 MB in size, this limit may be changed in the future.

Parameters

business_connection_idStringOptional

Unique identifier of the business connection on behalf of which the message will be sent

chat_idIntegerStringRequired

Unique identifier for the target chat or username of the target channel (in the format @channelusername)

message_thread_idIntegerOptional

Unique identifier for the target message thread (topic) of a forum; for forum supergroups and private chats of bots with forum topic mode enabled only

direct_messages_topic_idIntegerOptional

Identifier of the direct messages topic to which the message will be sent; required if the message is sent to a direct messages chat

animationInputFileStringRequired📎 Files

Animation to send. Pass a file\_id as String to send an animation that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get an animation from the Internet, or upload a new animation using multipart/form-data. More information on Sending Files »

durationIntegerOptional

Duration of sent animation in seconds

widthIntegerOptional

Animation width

heightIntegerOptional

Animation height

thumbnailInputFileStringOptional📎 Files

Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass "attach://attach\name>" if the thumbnail was uploaded using multipart/form-data under attach\name>. More information on Sending Files »

captionStringOptional✏️ FormattableminLen 0maxLen 1024

Animation caption (may also be used when resending animation by file\_id), 0-1024 characters after entities parsing

parse_modeStringOptional

Mode for parsing entities in the animation caption. See formatting options for more details.

caption_entitiesMessageEntity[]Optional

A JSON-serialized list of special entities that appear in the caption, which can be specified instead of parse\_mode

show_caption_above_mediaBooleanOptional

Pass True, if the caption must be shown above the message media

has_spoilerBooleanOptional

Pass True if the animation needs to be covered with a spoiler animation

disable_notificationBooleanOptional

Sends the message silently. Users will receive a notification with no sound.

protect_contentBooleanOptional

Protects the contents of the sent message from forwarding and saving

allow_paid_broadcastBooleanOptional

Pass True to allow up to 1000 messages per second, ignoring broadcasting limits for a fee of 0.1 Telegram Stars per message. The relevant Stars will be withdrawn from the bot's balance

message_effect_idStringOptional

Unique identifier of the message effect to be added to the message; for private chats only

suggested_post_parametersSuggestedPostParametersOptional

A JSON-serialized object containing the parameters of the suggested post to send; for direct messages chats only. If the message is sent as a reply to another suggested post, then that suggested post is automatically declined.

reply_parametersReplyParametersOptional

Description of the message to reply to

reply_markupInlineKeyboardMarkupReplyKeyboardMarkupReplyKeyboardRemoveForceReplyOptional⌨️ Keyboards

Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove a reply keyboard or to force a reply from the user

Returns

On success, the Message object is returned.

GramIO Usage

Send an animation from a public URL using the context shorthand inside a message handler:

bot.on("message", async (ctx) => {
  await ctx.sendAnimation(
    "https://media.giphy.com/media/26xBwdIuRJiAIqHLa/giphy.gif",
    { caption: "Here's your animation!" }
  );
});

Reply to the user's message with an animation using replyWithAnimation:

bot.on("message", async (ctx) => {
  await ctx.replyWithAnimation(
    "https://media.giphy.com/media/26xBwdIuRJiAIqHLa/giphy.gif",
    { caption: "Replying with animation" }
  );
});

Upload a local GIF file using MediaUpload.path:

bot.on("message", async (ctx) => {
  await ctx.sendAnimation(await MediaUpload.path("./assets/hello.gif"), {
    caption: "Uploaded from disk",
    duration: 3,
    width: 480,
    height: 270,
  });
});

Send a spoiler-wrapped animation with a caption:

bot.on("message", async (ctx) => {
  await ctx.sendAnimation(
    "AgACAgIAAxkBAAIB...", // file_id
    {
      caption: format`${bold("Spoiler!")} Tap to reveal.`,
      has_spoiler: true,
    }
  );
});

Direct API call with bot.api.sendAnimation (useful outside handlers):

const msg = await bot.api.sendAnimation({
  chat_id: 123456789,
  animation: await MediaUpload.url(
    "https://media.giphy.com/media/26xBwdIuRJiAIqHLa/giphy.gif"
  ),
  caption: "Sent via direct API call",
  width: 480,
  height: 270,
  duration: 5,
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	The chat_id is invalid, the bot has never interacted with the user, or the chat does not exist.
400	Bad Request: wrong file identifier/HTTP URL specified	The file_id is malformed or the URL is unreachable / returns a non-media response.
400	Bad Request: failed to get HTTP URL content	Telegram could not download the animation from the provided HTTP URL. Check the URL is publicly accessible.
400	Bad Request: PHOTO_INVALID_DIMENSIONS	The uploaded file does not meet dimension expectations for animated media. Provide correct width/height.
400	Bad Request: file is too big	The animation exceeds the 50 MB server-side limit. Compress or trim the file before uploading.
403	Forbidden: bot was blocked by the user	The user blocked the bot. Remove them from your active user list.
429	Too Many Requests: retry after N	Flood control triggered. Back off for the specified number of seconds.

TIP

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

Tips & Gotchas

• 50 MB hard limit. Animations larger than 50 MB are rejected. Compress the GIF or use a short MPEG-4 clip instead.
• GIF vs MP4. Telegram internally converts GIFs to MP4 for efficient delivery. Sending an MP4 with no audio is more bandwidth-friendly and avoids re-encoding.
• Thumbnail is only applied for new uploads. If you pass a file_id, Telegram ignores the thumbnail parameter entirely.
• has_spoiler blurs the preview. The animation plays normally after the user taps the spoiler overlay. This works in private chats, groups, and channels.
• Caption limit is 1024 characters. Unlike sendMessage (4096 chars), animation captions are capped. Truncate or split long text.
• show_caption_above_media places the caption text above the animation instead of below — useful for storytelling-style posts.

See Also

• Media Upload guide — file_id, URL, path, buffer upload patterns
• Formatting guide — bold, italic, and entity-based caption formatting
• Keyboards overview — attaching inline or reply keyboards
• sendVideo — send MP4 video with audio
• sendDocument — send files without media player rendering
• sendPhoto — send static images
• Animation type — structure of the returned animation object
• Message type — full structure of the returned message