diff --git a/doc/api.md b/doc/api.md index 1424e360..62a22638 100644 --- a/doc/api.md +++ b/doc/api.md @@ -161,10 +161,28 @@ TelegramBot * [.deleteMessages(chatId, messageIds, [options])](#TelegramBot+deleteMessages) ⇒ [ 'Promise' ].<Boolean> * [.getAvailableGifts([options])](#TelegramBot+getAvailableGifts) ⇒ Promise * [.sendGift(giftId, [options])](#TelegramBot+sendGift) ⇒ Promise - * [.verifyUser(userId)](#TelegramBot+verifyUser) ⇒ Promise - * [.verifyChat(chatId)](#TelegramBot+verifyChat) ⇒ Promise - * [.removeUserVerification(userId)](#TelegramBot+removeUserVerification) ⇒ Promise - * [.removeChatVerification(chatId)](#TelegramBot+removeChatVerification) ⇒ Promise + * [.giftPremiumSubscription(userId, monthCount, starCount, [options])](#TelegramBot+giftPremiumSubscription) ⇒ Promise + * [.verifyUser(userId, [options])](#TelegramBot+verifyUser) ⇒ Promise + * [.verifyChat(chatId, [options])](#TelegramBot+verifyChat) ⇒ Promise + * [.removeUserVerification(userId, [options])](#TelegramBot+removeUserVerification) ⇒ Promise + * [.removeChatVerification(chatId, [options])](#TelegramBot+removeChatVerification) ⇒ Promise + * [.readBusinessMessage(businessConnectionId, chatId, messageId, [options])](#TelegramBot+readBusinessMessage) ⇒ Promise + * [.deleteBusinessMessages(businessConnectionId, messageIds, [options])](#TelegramBot+deleteBusinessMessages) ⇒ Promise + * [.setBusinessAccountName(businessConnectionId, firstName, [options])](#TelegramBot+setBusinessAccountName) ⇒ Promise + * [.setBusinessAccountUsername(businessConnectionId, [options])](#TelegramBot+setBusinessAccountUsername) ⇒ Promise + * [.setBusinessAccountBio(businessConnectionId, [options])](#TelegramBot+setBusinessAccountBio) ⇒ Promise + * [.setBusinessAccountProfilePhoto(businessConnectionId, photo, [options])](#TelegramBot+setBusinessAccountProfilePhoto) ⇒ Promise + * [.removeBusinessAccountProfilePhoto(businessConnectionId, [options])](#TelegramBot+removeBusinessAccountProfilePhoto) ⇒ Promise + * [.setBusinessAccountGiftSettings(businessConnectionId, showGiftButton, acceptedGiftTypes, [options])](#TelegramBot+setBusinessAccountGiftSettings) ⇒ Promise + * [.getBusinessAccountStarBalance(businessConnectionId, [options])](#TelegramBot+getBusinessAccountStarBalance) ⇒ Promise + * [.transferBusinessAccountStars(businessConnectionId, starCount, [options])](#TelegramBot+transferBusinessAccountStars) ⇒ Promise + * [.getBusinessAccountGifts(businessConnectionId, [options])](#TelegramBot+getBusinessAccountGifts) ⇒ Promise + * [.convertGiftToStars(businessConnectionId, ownedGiftId, [options])](#TelegramBot+convertGiftToStars) ⇒ Promise + * [.upgradeGift(businessConnectionId, ownedGiftId, [options])](#TelegramBot+upgradeGift) ⇒ Promise + * [.transferGift(businessConnectionId, ownedGiftId, newOwnerChatId, [options])](#TelegramBot+transferGift) ⇒ Promise + * [.postStory(businessConnectionId, content, activePeriod, [options])](#TelegramBot+postStory) ⇒ Promise + * [.editStory(businessConnectionId, storyId, content, [options])](#TelegramBot+editStory) ⇒ Promise + * [.deleteStory(businessConnectionId, storyId, [options])](#TelegramBot+deleteStory) ⇒ Promise * _static_ * [.errors](#TelegramBot.errors) : Object * [.messageTypes](#TelegramBot.messageTypes) : [ 'Array' ].<String> @@ -188,6 +206,7 @@ Emits `message` when a message arrives. | [options.polling.autoStart] | Boolean | true | Start polling immediately | | [options.polling.params] | Object | | Parameters to be used in polling API requests. See https://core.telegram.org/bots/api#getupdates for more information. | | [options.polling.params.timeout] | Number | 10 | Timeout in seconds for long polling. | +| [options.polling.params.allowed_updates] | Array | | A JSON-serialized list of the update types you want your bot to receive. For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. | | [options.webHook] | Boolean \| Object | false | Set true to enable WebHook or set options | | [options.webHook.host] | String | "0.0.0.0" | Host to bind to | | [options.webHook.port] | Number | 8443 | Port to bind to | @@ -778,7 +797,7 @@ Use this method to send paid media. | --- | --- | --- | | chatId | Number \| String | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) | | starCount | Number | The number of Telegram Stars that must be paid to buy access to the media; 1-10000 | -| media | String \| stream.Stream \| Buffer | A file path or Stream. | +| media | Array | Array of [InputPaidMedia](https://core.telegram.org/bots/api#inputpaidmedia). The media property can bea String, Stream or Buffer. | | [options] | Object | Additional Telegram query options | @@ -2597,7 +2616,7 @@ Use this method to returns the list of gifts that can be sent by the bot to user | Param | Type | Description | | --- | --- | --- | -| [options] | Object | Additional Telegram query options | +| [options] | Object | Additional Telegram query options. | @@ -2611,11 +2630,27 @@ Use this method to sends a gift to the given user or channel chat. | Param | Type | Description | | --- | --- | --- | | giftId | String | Unique identifier of the gift | -| [options] | Object | Additional Telegram query options | +| [options] | Object | Additional Telegram query options. | + + + +### telegramBot.giftPremiumSubscription(userId, monthCount, starCount, [options]) ⇒ Promise +Use this method to sends a gift to the given user or channel chat. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#getavailablegifts + +| Param | Type | Description | +| --- | --- | --- | +| userId | Number | Unique identifier of the target user who will receive a Telegram Premium subscription. | +| monthCount | Number | Number of months the Telegram Premium subscription will be active for the user; must be one of 3, 6, or 12. | +| starCount | String | Number of Telegram Stars to pay for the Telegram Premium subscription; must be 1000 for 3 months, 1500 for 6 months, and 2500 for 12 months. | +| [options] | Object | Additional Telegram query options. | -### telegramBot.verifyUser(userId) ⇒ Promise +### telegramBot.verifyUser(userId, [options]) ⇒ Promise This method verifies a user [on behalf of the organization](https://telegram.org/verify#third-party-verification) which is represented by the bot. **Kind**: instance method of [TelegramBot](#TelegramBot) @@ -2624,11 +2659,12 @@ This method verifies a user [on behalf of the organization](https://telegram.org | Param | Type | Description | | --- | --- | --- | -| userId | Number | Unique identifier of the target user | +| userId | Number | Unique identifier of the target user. | +| [options] | Object | Additional Telegram query options. | -### telegramBot.verifyChat(chatId) ⇒ Promise +### telegramBot.verifyChat(chatId, [options]) ⇒ Promise This method verifies a chat [on behalf of the organization](https://telegram.org/verify#third-party-verification) which is represented by the bot. **Kind**: instance method of [TelegramBot](#TelegramBot) @@ -2637,11 +2673,12 @@ This method verifies a chat [on behalf of the organization](https://telegram.org | Param | Type | Description | | --- | --- | --- | -| chatId | Number | Unique identifier of the target chat | +| chatId | Number | Unique identifier of the target chat. | +| [options] | Object | Additional Telegram query options. | -### telegramBot.removeUserVerification(userId) ⇒ Promise +### telegramBot.removeUserVerification(userId, [options]) ⇒ Promise This method removes verification from a user who is currently verified [on behalf of the organization](https://telegram.org/verify#third-party-verification) which is represented by the bot. **Kind**: instance method of [TelegramBot](#TelegramBot) @@ -2651,10 +2688,11 @@ This method removes verification from a user who is currently verified [on behal | Param | Type | Description | | --- | --- | --- | | userId | Number | Unique identifier of the target user | +| [options] | Object | Additional Telegram query options | -### telegramBot.removeChatVerification(chatId) ⇒ Promise +### telegramBot.removeChatVerification(chatId, [options]) ⇒ Promise This method removes verification from a chat who is currently verified [on behalf of the organization](https://telegram.org/verify#third-party-verification) which is represented by the bot. **Kind**: instance method of [TelegramBot](#TelegramBot) @@ -2663,7 +2701,299 @@ This method removes verification from a chat who is currently verified [on behal | Param | Type | Description | | --- | --- | --- | -| chatId | Number | Unique identifier of the target chat | +| chatId | Number | Unique identifier of the target chat. | +| [options] | Object | Additional Telegram query options. | + + + +### telegramBot.readBusinessMessage(businessConnectionId, chatId, messageId, [options]) ⇒ Promise +This method marks incoming message as read on behalf of a business account. + +Requires the **can_read_messages** business bot right + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#readbusinessmessage + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection on behalf of which to read the message. | +| chatId | Number | Unique identifier of the chat in which the message was received. The chat must have been active in the last 24 hours. | +| messageId | Number | Unique identifier of the message to mark as read. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.deleteBusinessMessages(businessConnectionId, messageIds, [options]) ⇒ Promise +This method delete messages on behalf of a business account. + +Requires the **can_delete_outgoing_messages** business bot right to delete messages sent by the bot itself, or the **can_delete_all_messages business** bot right to delete any message. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#deletebusinessmessages + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection on behalf of which to delete the message. | +| messageIds | [ 'Array' ].<Number> | List of 1-100 identifiers of messages to delete. All messages **must be from the same chat**. | +| [options] | Object | Additional Telegram query options. | + + + +### telegramBot.setBusinessAccountName(businessConnectionId, firstName, [options]) ⇒ Promise +This method changes the first and last name of a managed business account. + +Requires the **can_change_name** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#setbusinessaccountname + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| firstName | String | The new value of the first name for the business account; 1-64 characters. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.setBusinessAccountUsername(businessConnectionId, [options]) ⇒ Promise +This method changes the username of a managed business account. + +Requires the **can_change_username** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#setbusinessaccountusername + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.setBusinessAccountBio(businessConnectionId, [options]) ⇒ Promise +This method changes the bio of a managed business account. + +Requires the **can_change_bio** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#setbusinessaccountbio + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.setBusinessAccountProfilePhoto(businessConnectionId, photo, [options]) ⇒ Promise +This method changes the profile photo of a managed business account. + +Requires the **can_edit_profile_photo** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#setbusinessaccountprofilephoto + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| photo | String \| stream.Stream \| Buffer | New profile photo. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.removeBusinessAccountProfilePhoto(businessConnectionId, [options]) ⇒ Promise +This method removes the current profile photo of a managed business account. + +Requires the **can_edit_profile_photo** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#removebusinessaccountprofilephoto + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.setBusinessAccountGiftSettings(businessConnectionId, showGiftButton, acceptedGiftTypes, [options]) ⇒ Promise +This method changes the privacy settings pertaining to incoming gifts in a managed business account. + +Requires the **can_change_gift_settings** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns true. +**See**: https://core.telegram.org/bots/api#setbusinessaccountgiftsettings + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| showGiftButton | Boolean | Pass True, if a button for sending a gift to the user or by the business account must always be shown in the input field. | +| acceptedGiftTypes | Object | Types of gifts accepted by the business account. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.getBusinessAccountStarBalance(businessConnectionId, [options]) ⇒ Promise +This method returns the amount of Telegram Stars owned by a managed business account. + +Requires the **can_view_gifts_and_stars** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns [StarAmount](https://core.telegram.org/bots/api#staramount). +**See**: https://core.telegram.org/bots/api#getbusinessaccountstarbalance + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.transferBusinessAccountStars(businessConnectionId, starCount, [options]) ⇒ Promise +This method transfers Telegram Stars from the business account balance to the bot's balance. + +Requires the **can_transfer_stars** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns True. +**See**: https://core.telegram.org/bots/api#transferbusinessaccountstars + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| starCount | Number | Number of Telegram Stars to transfer; 1-10000. | +| [options] | Object | Additional Telegram query options. | + + + +### telegramBot.getBusinessAccountGifts(businessConnectionId, [options]) ⇒ Promise +This method returns the gifts received and owned by a managed business account. + +Requires the **can_view_gifts_and_stars** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns [OwnedGifts](https://core.telegram.org/bots/api#ownedgifts). +**See**: https://core.telegram.org/bots/api#getbusinessaccountgifts + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.convertGiftToStars(businessConnectionId, ownedGiftId, [options]) ⇒ Promise +This method converts a given regular gift to Telegram Stars. + +Requires the **can_convert_gifts_to_stars** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns True. +**See**: https://core.telegram.org/bots/api#convertgifttostars + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| ownedGiftId | String | Unique identifier of the regular gift that should be converted to Telegram Stars. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.upgradeGift(businessConnectionId, ownedGiftId, [options]) ⇒ Promise +This method upgrades a given regular gift to a unique gift. + +Requires the **can_transfer_and_upgrade_gifts** business bot right. +Additionally requires the **can_transfer_stars** business bot right **if the upgrade is paid**. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns True. +**See**: https://core.telegram.org/bots/api#upgradegift + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| ownedGiftId | String | Unique identifier of the regular gift that should be upgraded to a unique one. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.transferGift(businessConnectionId, ownedGiftId, newOwnerChatId, [options]) ⇒ Promise +This method transfers an owned unique gift to another user. + +Requires the **can_transfer_and_upgrade_gifts** business bot right. +Additionally requires the **can_transfer_stars** business bot right **if the transfer is paid**. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns True. +**See**: https://core.telegram.org/bots/api#transfergift + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| ownedGiftId | String | Unique identifier of the regular gift that should be transferred. | +| newOwnerChatId | Number | Unique identifier of the chat which will own the gift. The chat **must be active in the last 24 hours**. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.postStory(businessConnectionId, content, activePeriod, [options]) ⇒ Promise +This method posts a story on behalf of a managed business account. + +Requires the **can_manage_stories** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns [Story](https://core.telegram.org/bots/api#story). +**See**: https://core.telegram.org/bots/api#poststory + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| content | Array | [InputStoryContent](https://core.telegram.org/bots/api#inputpaidmedia). The photo/video property can be String, Stream or Buffer. | +| activePeriod | Number | Unique identifier of the chat which will own the gift. The chat **must be active in the last 24 hours**. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.editStory(businessConnectionId, storyId, content, [options]) ⇒ Promise +This method edits a story previously posted by the bot on behalf of a managed business account. + +Requires the **can_manage_stories** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns [Story](https://core.telegram.org/bots/api#story). +**See**: https://core.telegram.org/bots/api#editstory + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| storyId | Number | Unique identifier of the story to edit. | +| content | Array | [InputStoryContent](https://core.telegram.org/bots/api#inputpaidmedia). The photo/video property can be String, Stream or Buffer. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.deleteStory(businessConnectionId, storyId, [options]) ⇒ Promise +This method deletes a story previously posted by the bot on behalf of a managed business account. + +Requires the **can_manage_stories** business bot right. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - On success, returns True. +**See**: https://core.telegram.org/bots/api#deletestory + +| Param | Type | Description | +| --- | --- | --- | +| businessConnectionId | String | Unique identifier of the business connection. | +| storyId | Number | Unique identifier of the story to delete. | +| [options] | Object | Additional Telegram query options. | diff --git a/src/telegram.js b/src/telegram.js index 4b22ed55..3d713d03 100644 --- a/src/telegram.js +++ b/src/telegram.js @@ -130,6 +130,8 @@ class TelegramBot extends EventEmitter { * @param {Object} [options.polling.params] Parameters to be used in polling API requests. * See https://core.telegram.org/bots/api#getupdates for more information. * @param {Number} [options.polling.params.timeout=10] Timeout in seconds for long polling. + * @param {Array} [options.polling.params.allowed_updates] A JSON-serialized list of the update types you want your bot to receive. + * For example, specify ["message", "edited_channel_post", "callback_query"] to only receive updates of these types. * @param {Boolean|Object} [options.webHook=false] Set true to enable WebHook or set options * @param {String} [options.webHook.host="0.0.0.0"] Host to bind to * @param {Number} [options.webHook.port=8443] Port to bind to @@ -923,6 +925,12 @@ class TelegramBot extends EventEmitter { /* eslint-enable no-param-reassign, prefer-rest-params */ } + // If allowed_updates is present and is an array, stringify it. + // If it's already a string (e.g., user did JSON.stringify), leave as is. + if (Array.isArray(form.allowed_updates)) { + form.allowed_updates = JSON.stringify(form.allowed_updates); + } + return this._request('getUpdates', { form }); }