sendVideoNote

Returns: Message📎 Accepts files⌨️ KeyboardsOfficial docs ↗

As of v.4.0, Telegram clients support rounded square MPEG4 videos of up to 1 minute long. Use this method to send video messages. On success, the sent Message is returned.

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

video_noteInputFileStringRequired📎 Files

Video note to send. Pass a file\_id as String to send a video note that exists on the Telegram servers (recommended) or upload a new video using multipart/form-data. More information on Sending Files ». Sending video notes by a URL is currently unsupported

durationIntegerOptional

Duration of sent video in seconds

lengthIntegerOptional

Video width and height, i.e. diameter of the video message

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 »

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 a video note by file_id (fastest — no re-upload)
bot.command("vidnote", (ctx) =>
  ctx.sendVideoNote(
    "DQACAgIAAxkBAAIBjmXzPexample_videonote_file_id_hereQ"
  )
);

// Upload a local square MPEG4 video note with dimensions
bot.command("circle", async (ctx) => {
  const videoNote = await MediaUpload.path("./assets/greeting.mp4");
  return ctx.sendVideoNote(videoNote, {
    duration: 10,
    length: 480, // diameter in pixels — video must be square
  });
});

// Upload video note with a custom JPEG thumbnail
bot.command("thumb", async (ctx) => {
  const videoNote = await MediaUpload.path("./assets/note.mp4");
  const thumbnail = await MediaUpload.path("./assets/note_thumb.jpg");
  return ctx.sendVideoNote(videoNote, {
    duration: 20,
    length: 360,
    thumbnail,
  });
});

// Reply with a video note (sets reply_parameters automatically)
bot.command("reply", async (ctx) => {
  const videoNote = await MediaUpload.path("./assets/response.mp4");
  return ctx.replyWithVideoNote(videoNote, { duration: 5, length: 240 });
});

Errors

Code	Error	Cause
400	Bad Request: chat not found	Invalid or inaccessible chat_id — verify the chat exists and the bot is a member
400	Bad Request: VIDEO_NOTE_INVALID	The provided file_id does not refer to a video note
400	Bad Request: failed to get HTTP URL content	Video notes cannot be sent via URL — upload required
400	Bad Request: wrong video note length	length value is outside the acceptable range or the video is not square
400	Bad Request: VIDEO_NOTE_LENGTH_INVALID	Same as above via a different code path
413	Request Entity Too Large	Uploaded file exceeds the size limit
403	Forbidden: bot was blocked by the user	The target user has blocked the bot
403	Forbidden: not enough rights	Bot lacks can_send_media_messages permission in the group/channel
429	Too Many Requests: retry after N	Flood control triggered — use the auto-retry plugin to handle this automatically

Auto-retry for 429 errors

Install the @gramio/auto-retry plugin to transparently handle flood-wait errors without manual retry logic.

Tips & Gotchas

• Video notes cannot be sent via URL. Unlike regular videos, sendVideoNote does not accept HTTP URLs as the video_note parameter — you must upload the file directly using MediaUpload.path() or pass an existing file_id.
• The video must be square. Telegram crops video notes into a circle, so the source video must have equal width and height. Non-square videos may be rejected or displayed incorrectly.
• Maximum 1 minute duration. Video notes are capped at 60 seconds. Files longer than that will be rejected.
• length is the diameter, not width+height. Pass the pixel diameter of the square video (e.g. 360 for a 360×360 video). This is a single integer, not an array.
• Cache file_id after the first upload. Capture message.videoNote.file_id from the returned MessageContext and persist it to avoid re-uploading on repeat sends.
• Thumbnails must be fresh JPEG files. Thumbnail file_id values from previous messages cannot be reused — always upload a new JPEG file under 200 kB and at most 320×320 px.

See Also

• sendVideo — Send a full-length MPEG4 video with caption
• sendVoice — Send an audio voice message
• sendAnimation — Send a GIF or silent MP4 animation
• VideoNote — The VideoNote type embedded in Message
• Media upload guide — Upload files using MediaUpload helpers
• sendMessage — Send a plain text message