src/telegram: Improve sending files (#471)

References: * PR: https://github.com/yagop/node-telegram-bot-api/pull/471
2025-08-31 06:16:07 +00:00 · 2017-12-20 11:03:00 +03:00
parent f28416fbaf d7197998dd
commit 1a08221174
6 changed files with 373 additions and 138 deletions
--- a/doc/api.md
+++ b/doc/api.md
@@ -22,7 +22,7 @@ TelegramBot
        * [.closeWebHook()](#TelegramBot+closeWebHook) ⇒ <code>Promise</code>
        * [.hasOpenWebHook()](#TelegramBot+hasOpenWebHook) ⇒ <code>Boolean</code>
        * [.getMe([options])](#TelegramBot+getMe) ⇒ <code>Promise</code>
-        * [.setWebHook(url, [options])](#TelegramBot+setWebHook) ⇒ <code>Promise</code>
+        * [.setWebHook(url, [options], [fileOptions])](#TelegramBot+setWebHook) ⇒ <code>Promise</code>
        * [.deleteWebHook([options])](#TelegramBot+deleteWebHook) ⇒ <code>Promise</code>
        * [.getWebHookInfo([options])](#TelegramBot+getWebHookInfo) ⇒ <code>Promise</code>
        * [.getUpdates([options])](#TelegramBot+getUpdates) ⇒ <code>Promise</code>
@@ -30,20 +30,20 @@ TelegramBot
        * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ <code>Promise</code>
        * [.answerInlineQuery(inlineQueryId, results, [options])](#TelegramBot+answerInlineQuery) ⇒ <code>Promise</code>
        * [.forwardMessage(chatId, fromChatId, messageId, [options])](#TelegramBot+forwardMessage) ⇒ <code>Promise</code>
-        * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ <code>Promise</code>
-        * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ <code>Promise</code>
-        * [.sendDocument(chatId, doc, [options], [fileOpts])](#TelegramBot+sendDocument) ⇒ <code>Promise</code>
-        * [.sendSticker(chatId, sticker, [options])](#TelegramBot+sendSticker) ⇒ <code>Promise</code>
-        * [.sendVideo(chatId, video, [options])](#TelegramBot+sendVideo) ⇒ <code>Promise</code>
-        * [.sendVideoNote(chatId, videoNote, [options])](#TelegramBot+sendVideoNote) ⇒ <code>Promise</code>
-        * [.sendVoice(chatId, voice, [options])](#TelegramBot+sendVoice) ⇒ <code>Promise</code>
+        * [.sendPhoto(chatId, photo, [options], [fileOptions])](#TelegramBot+sendPhoto) ⇒ <code>Promise</code>
+        * [.sendAudio(chatId, audio, [options], [fileOptions])](#TelegramBot+sendAudio) ⇒ <code>Promise</code>
+        * [.sendDocument(chatId, doc, [options], [fileOptions])](#TelegramBot+sendDocument) ⇒ <code>Promise</code>
+        * [.sendSticker(chatId, sticker, [options], [fileOptions])](#TelegramBot+sendSticker) ⇒ <code>Promise</code>
+        * [.sendVideo(chatId, video, [options], [fileOptions])](#TelegramBot+sendVideo) ⇒ <code>Promise</code>
+        * [.sendVideoNote(chatId, videoNote, [options], [fileOptions])](#TelegramBot+sendVideoNote) ⇒ <code>Promise</code>
+        * [.sendVoice(chatId, voice, [options], [fileOptions])](#TelegramBot+sendVoice) ⇒ <code>Promise</code>
        * [.sendChatAction(chatId, action, [options])](#TelegramBot+sendChatAction) ⇒ <code>Promise</code>
        * [.kickChatMember(chatId, userId, [options])](#TelegramBot+kickChatMember) ⇒ <code>Promise</code>
        * [.unbanChatMember(chatId, userId, [options])](#TelegramBot+unbanChatMember) ⇒ <code>Promise</code>
        * [.restrictChatMember(chatId, userId, [options])](#TelegramBot+restrictChatMember) ⇒ <code>Promise</code>
        * [.promoteChatMember(chatId, userId, [options])](#TelegramBot+promoteChatMember) ⇒ <code>Promise</code>
        * [.exportChatInviteLink(chatId, [options])](#TelegramBot+exportChatInviteLink) ⇒ <code>Promise</code>
-        * [.setChatPhoto(chatId, photo, [options])](#TelegramBot+setChatPhoto) ⇒ <code>Promise</code>
+        * [.setChatPhoto(chatId, photo, [options], [fileOptions])](#TelegramBot+setChatPhoto) ⇒ <code>Promise</code>
        * [.deleteChatPhoto(chatId, [options])](#TelegramBot+deleteChatPhoto) ⇒ <code>Promise</code>
        * [.setChatTitle(chatId, title, [options])](#TelegramBot+setChatTitle) ⇒ <code>Promise</code>
        * [.setChatDescription(chatId, description, [options])](#TelegramBot+setChatDescription) ⇒ <code>Promise</code>
@@ -82,9 +82,9 @@ TelegramBot
        * [.answerShippingQuery(shippingQueryId, ok, [options])](#TelegramBot+answerShippingQuery) ⇒ <code>Promise</code>
        * [.answerPreCheckoutQuery(preCheckoutQueryId, ok, [options])](#TelegramBot+answerPreCheckoutQuery) ⇒ <code>Promise</code>
        * [.getStickerSet(name, [options])](#TelegramBot+getStickerSet) ⇒ <code>Promise</code>
-        * [.uploadStickerFile(userId, pngSticker, [options])](#TelegramBot+uploadStickerFile) ⇒ <code>Promise</code>
-        * [.createNewStickerSet(userId, name, title, pngSticker, emojis, [options])](#TelegramBot+createNewStickerSet) ⇒ <code>Promise</code>
-        * [.addStickerToSet(userId, name, pngSticker, emojis, [options])](#TelegramBot+addStickerToSet) ⇒ <code>Promise</code>
+        * [.uploadStickerFile(userId, pngSticker, [options], [fileOptions])](#TelegramBot+uploadStickerFile) ⇒ <code>Promise</code>
+        * [.createNewStickerSet(userId, name, title, pngSticker, emojis, [options], [fileOptions])](#TelegramBot+createNewStickerSet) ⇒ <code>Promise</code>
+        * [.addStickerToSet(userId, name, pngSticker, emojis, [options], [fileOptions])](#TelegramBot+addStickerToSet) ⇒ <code>Promise</code>
        * [.setStickerPositionInSet(sticker, position, [options])](#TelegramBot+setStickerPositionInSet) ⇒ <code>Promise</code>
        * [.deleteStickerFromSet(sticker, [options])](#TelegramBot+deleteStickerFromSet) ⇒ <code>Promise</code>
    * _static_
@@ -227,7 +227,7 @@ Returns basic information about the bot in form of a `User` object.

 <a name="TelegramBot+setWebHook"></a>

-### telegramBot.setWebHook(url, [options]) ⇒ <code>Promise</code>
+### telegramBot.setWebHook(url, [options], [fileOptions]) ⇒ <code>Promise</code>
 Specify an url to receive incoming updates via an outgoing webHook.
 This method has an [older, compatible signature][setWebHook-v0.25.0]
 that is being deprecated.
@@ -240,6 +240,7 @@ that is being deprecated.
 | url | <code>String</code> | URL where Telegram will make HTTP Post. Leave empty to delete webHook. |
 | [options] | <code>Object</code> | Additional Telegram query options |
 | [options.certificate] | <code>String</code> &#124; <code>stream.Stream</code> | PEM certificate key (public). |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+deleteWebHook"></a>

@@ -341,50 +342,64 @@ Forward messages of any kind.

 <a name="TelegramBot+sendPhoto"></a>

-### telegramBot.sendPhoto(chatId, photo, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendPhoto(chatId, photo, [options], [fileOptions]) ⇒ <code>Promise</code>
 Send photo

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**See**: https://core.telegram.org/bots/api#sendphoto  
+**See**
+
+- https://core.telegram.org/bots/api#sendphoto
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | photo | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or a Stream. Can also be a `file_id` previously uploaded |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendAudio"></a>

-### telegramBot.sendAudio(chatId, audio, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendAudio(chatId, audio, [options], [fileOptions]) ⇒ <code>Promise</code>
 Send audio

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**See**: https://core.telegram.org/bots/api#sendaudio  
+**See**
+
+- https://core.telegram.org/bots/api#sendaudio
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | audio | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendDocument"></a>

-### telegramBot.sendDocument(chatId, doc, [options], [fileOpts]) ⇒ <code>Promise</code>
+### telegramBot.sendDocument(chatId, doc, [options], [fileOptions]) ⇒ <code>Promise</code>
 Send Document

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**See**: https://core.telegram.org/bots/api#sendDocument  
+**See**
+
+- https://core.telegram.org/bots/api#sendDocument
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | doc | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
 | [options] | <code>Object</code> | Additional Telegram query options |
-| [fileOpts] | <code>Object</code> | Optional file related meta-data |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendSticker"></a>

-### telegramBot.sendSticker(chatId, sticker, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendSticker(chatId, sticker, [options], [fileOptions]) ⇒ <code>Promise</code>
 Send .webp stickers.

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
@@ -395,49 +410,65 @@ Send .webp stickers.
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | sticker | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. Stickers are WebP format files. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendVideo"></a>

-### telegramBot.sendVideo(chatId, video, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendVideo(chatId, video, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document).

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**See**: https://core.telegram.org/bots/api#sendvideo  
+**See**
+
+- https://core.telegram.org/bots/api#sendvideo
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | video | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or Stream. Can also be a `file_id` previously uploaded. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendVideoNote"></a>

-### telegramBot.sendVideoNote(chatId, videoNote, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendVideoNote(chatId, videoNote, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to send rounded square videos of upto 1 minute long.

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
 **Info**: The length parameter is actually optional. However, the API (at time of writing) requires you to always provide it until it is fixed.  
-**See**: https://core.telegram.org/bots/api#sendvideonote  
+**See**
+
+- https://core.telegram.org/bots/api#sendvideonote
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | videoNote | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or Stream. Can also be a `file_id` previously uploaded. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendVoice"></a>

-### telegramBot.sendVoice(chatId, voice, [options]) ⇒ <code>Promise</code>
+### telegramBot.sendVoice(chatId, voice, [options], [fileOptions]) ⇒ <code>Promise</code>
 Send voice

 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
-**See**: https://core.telegram.org/bots/api#sendvoice  
+**See**
+
+- https://core.telegram.org/bots/api#sendvoice
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+

 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | voice | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+sendChatAction"></a>

@@ -543,7 +574,7 @@ Returns exported invite link as String on success.

 <a name="TelegramBot+setChatPhoto"></a>

-### telegramBot.setChatPhoto(chatId, photo, [options]) ⇒ <code>Promise</code>
+### telegramBot.setChatPhoto(chatId, photo, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to set a new profile photo for the chat. Photos can't be changed for private chats.
 The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.
 Returns True on success.
@@ -556,6 +587,7 @@ Returns True on success.
 | chatId | <code>Number</code> &#124; <code>String</code> | Unique identifier for the message recipient |
 | photo | <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or a Stream. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+deleteChatPhoto"></a>

@@ -1150,7 +1182,7 @@ Use this method to get a sticker set. On success, a [StickerSet](https://core.te

 <a name="TelegramBot+uploadStickerFile"></a>

-### telegramBot.uploadStickerFile(userId, pngSticker, [options]) ⇒ <code>Promise</code>
+### telegramBot.uploadStickerFile(userId, pngSticker, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to upload a .png file with a sticker for later use in *createNewStickerSet* and *addStickerToSet* methods (can be used multiple
 times). Returns the uploaded [File](https://core.telegram.org/bots/api#file) on success.

@@ -1162,10 +1194,11 @@ times). Returns the uploaded [File](https://core.telegram.org/bots/api#file) on
 | userId | <code>Number</code> | User identifier of sticker file owner |
 | pngSticker | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | A file path or a Stream. Can also be a `file_id` previously uploaded. **Png** image with the  sticker, must be up to 512 kilobytes in size, dimensions must not exceed 512px, and either width or height must be exactly 512px. |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+createNewStickerSet"></a>

-### telegramBot.createNewStickerSet(userId, name, title, pngSticker, emojis, [options]) ⇒ <code>Promise</code>
+### telegramBot.createNewStickerSet(userId, name, title, pngSticker, emojis, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to create new sticker set owned by a user.
 The bot will be able to edit the created sticker set.
 Returns True on success.
@@ -1185,10 +1218,11 @@ Returns True on success.
 | pngSticker | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | Png image with the sticker, must be up to 512 kilobytes in size,  dimensions must not exceed 512px, and either width or height must be exactly 512px. |
 | emojis | <code>String</code> | One or more emoji corresponding to the sticker |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+addStickerToSet"></a>

-### telegramBot.addStickerToSet(userId, name, pngSticker, emojis, [options]) ⇒ <code>Promise</code>
+### telegramBot.addStickerToSet(userId, name, pngSticker, emojis, [options], [fileOptions]) ⇒ <code>Promise</code>
 Use this method to add a new sticker to a set created by the bot.
 Returns True on success.

@@ -1206,6 +1240,7 @@ Returns True on success.
 | pngSticker | <code>String</code> &#124; <code>stream.Stream</code> &#124; <code>Buffer</code> | Png image with the sticker, must be up to 512 kilobytes in size,  dimensions must not exceed 512px, and either width or height must be exactly 512px |
 | emojis | <code>String</code> | One or more emoji corresponding to the sticker |
 | [options] | <code>Object</code> | Additional Telegram query options |
+| [fileOptions] | <code>Object</code> | Optional file related meta-data |

 <a name="TelegramBot+setStickerPositionInSet"></a>

--- a/doc/usage.md
+++ b/doc/usage.md
@@ -116,6 +116,63 @@ const url = 'https://telegram.org/img/t_logo.png';
 bot.sendPhoto(chatId, url);
 ```

+If you wish to explicitly specify the filename or
+[MIME type](http://en.wikipedia.org/wiki/Internet_media_type),
+you may pass an additional argument as file options, like so:
+
+```js
+const fileOptions = {
+  // Explicitly specify the file name.
+  filename: 'customfilename',
+  // Explicitly specify the MIME type.
+  contentType: 'audio/mpeg',
+};
+bot.sendAudio(chatId, data, {}, fileOptions);
+```
+
+**NOTE:** You **MUST** provide an empty object (`{}`) in place of
+*Additional Telegram query options*, if you have **no** query options
+to specify. For example,
+
+```js
+// WRONG!
+// 'fileOptions' will be taken as additional Telegram query options!!!
+bot.sendAudio(chatId, data, fileOptions);
+
+// RIGHT!
+bot.sendAudio(chatId, data, {}, fileOptions);
+```
+
+
+<a name="sending-files-options"></a>
+### File Options (metadata)
+
+When sending files, the library automatically resolves
+the `filename` and `contentType` properties.
+**For now, this has to be manually activated using environment
+variable `NTBA_FIX_350`.**
+
+In order of highest-to-lowest precedence in searching for
+a value, when resolving the `filename`:
+
+*(`fileOptions` is the Object argument passed to the method.
+The "file" argument passed to the method can be a `Stream`,
+`Buffer` or `filepath`.)*
+
+1. Is `fileOptions.filename` explictly defined?
+1. Does `Stream#path` exist?
+1. Is `filepath` provided?
+1. Default to `"filename"`
+
+And the `contentType`:
+
+1. Is `fileOptions.contentType` explictly-defined?
+1. Does `Stream#path` exist?
+1. Try detecting file-type from the `Buffer`
+1. Is `filepath` provided?
+1. Is `fileOptions.filename` explicitly defined?
+1. Default to `"application/octet-stream"`
+
 <a name="sending-files-performance"></a>
 ### Performance Issue