src/telegram: Add TelegramBot#sendMediaGroup()

References:

  * Telegram API documentation: https://core.telegram.org/bots/api#sendmediagroup

CHANGELOG.md

@@ -12,6 +12,7 @@ Added:
   * (#440) *TelegramBot#setChatStickerSet*, *TelegramBot#deleteChatStickerSet* (by @kamikazechaser)
 1. Support Bot API v3.5:
   * Support `provider_data` parameter in *TelegramBot#sendInvoice* (by @GochoMugo)
+  * Add method *TelegramBot#sendMediaGroup()* (by @GochoMugo)
 1. Add methods:
   * *TelegramBot#getFileStream* (#442) (by @GochoMugo, requested-by @Xaqron)
 1. Add options to *TelegramBot#stopPolling()* (by @GochoMugo)

doc/api.md

@@ -87,6 +87,7 @@ TelegramBot
         * [.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>
+        * [.sendMediaGroup(chatId, media, [options])](#TelegramBot+sendMediaGroup) ⇒ <code>Promise</code>
     * _static_
         * [.errors](#TelegramBot.errors) : <code>Object</code>
         * [.messageTypes](#TelegramBot.messageTypes) : <code>Array.&lt;String&gt;</code>
@@ -1279,6 +1280,29 @@ Returns True on success.
 | sticker | <code>String</code> | File identifier of the sticker |
 | [options] | <code>Object</code> | Additional Telegram query options |
 
+<a name="TelegramBot+sendMediaGroup"></a>
+
+### telegramBot.sendMediaGroup(chatId, media, [options]) ⇒ <code>Promise</code>
+Use this method to send a group of photos or videos as an album.
+On success, an array of the sent [Messages](https://core.telegram.org/bots/api#message)
+is returned.
+
+If you wish to [specify file options](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files),
+add a `fileOptions` property to the target input in `media`.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**See**
+
+- https://core.telegram.org/bots/api#sendmediagroup
+- https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| chatId | <code>String</code> | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
+| media | <code>Array</code> | A JSON-serialized array describing photos and videos to be sent, must include 2–10 items |
+| [options] | <code>Object</code> | Additional Telegram query options |
+
 <a name="TelegramBot.errors"></a>
 
 ### TelegramBot.errors : <code>Object</code>

src/telegram.js

@@ -1822,6 +1822,54 @@ class TelegramBot extends EventEmitter {
     form.sticker = sticker;
     return this._request('deleteStickerFromSet', { form });
   }
+
+  /**
+   * Use this method to send a group of photos or videos as an album.
+   * On success, an array of the sent [Messages](https://core.telegram.org/bots/api#message)
+   * is returned.
+   *
+   * If you wish to [specify file options](https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files),
+   * add a `fileOptions` property to the target input in `media`.
+   *
+   * @param  {String} chatId Unique identifier for the target chat or username of the target channel (in the format `@channelusername`)
+   * @param  {Array} media A JSON-serialized array describing photos and videos to be sent, must include 2–10 items
+   * @param  {Object} [options] Additional Telegram query options
+   * @return {Promise}
+   * @see https://core.telegram.org/bots/api#sendmediagroup
+   * @see https://github.com/yagop/node-telegram-bot-api/blob/master/doc/usage.md#sending-files
+   */
+  sendMediaGroup(chatId, media, options = {}) {
+    const opts = {
+      qs: options,
+    };
+    opts.qs.chat_id = chatId;
+
+    opts.formData = {};
+    const inputMedia = [];
+    let index = 0;
+    for (const input of media) {
+      const payload = Object.assign({}, input);
+      delete payload.media;
+      delete payload.fileOptions;
+      try {
+        const attachName = String(index);
+        const [formData, fileId] = this._formatSendData(attachName, input.media, input.fileOptions);
+        if (formData) {
+          opts.formData[attachName] = formData[attachName];
+          payload.media = `attach://${attachName}`;
+        } else {
+          payload.media = fileId;
+        }
+      } catch (ex) {
+        return Promise.reject(ex);
+      }
+      inputMedia.push(payload);
+      index++;
+    }
+    opts.qs.media = JSON.stringify(inputMedia);
+
+    return this._request('sendMediaGroup', opts);
+  }
 }
 
 module.exports = TelegramBot;

test/telegram.js

@@ -1409,4 +1409,31 @@ describe('TelegramBot', function telegramSuite() {
     });
     // Other tests (eg. Buffer, URL) are skipped, because they rely on the same features as sendPhoto.
   });
+
+  describe('#sendMediaGroup', function sendMediaGroupSuite() {
+    before(function before() {
+      utils.handleRatelimit(bot, 'sendMediaGroup', this);
+    });
+    it('should send group of photos/videos as album', function test() {
+      return bot.sendMediaGroup(USERID, [
+        {
+          type: 'photo',
+          media: `${__dirname}/data/photo.gif`,
+        },
+        {
+          type: 'video',
+          media: `${__dirname}/data/video.mp4`,
+        },
+        {
+          type: 'photo',
+          media: FILE_ID,
+        },
+      ], {
+        disable_notification: true,
+      }).then(resp => {
+        assert.ok(is.array(resp));
+        assert.equal(resp.length, 3);
+      });
+    });
+  });
 }); // End Telegram