diff --git a/README.md b/README.md index 1fb310d..3003c5c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Node.js Telegram Bot API -[![Bot API](http://img.shields.io/badge/Bot%20API-v3.0.0-00aced.svg)](https://core.telegram.org/bots/api) +[![Bot API](https://img.shields.io/badge/Bot%20API-v.3.1.0-00aced.svg)](https://core.telegram.org/bots/api) [![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api) [![Build status](https://ci.appveyor.com/api/projects/status/ujko6bsum3g5msjh/branch/master?svg=true)](https://ci.appveyor.com/project/yagop/node-telegram-bot-api/branch/master) [![Coverage Status](https://coveralls.io/repos/yagop/node-telegram-bot-api/badge.svg?branch=master)](https://coveralls.io/r/yagop/node-telegram-bot-api?branch=master) diff --git a/doc/api.md b/doc/api.md index 47c3d6e..0cd1369 100644 --- a/doc/api.md +++ b/doc/api.md @@ -38,6 +38,15 @@ TelegramBot * [.sendChatAction(chatId, action)](#TelegramBot+sendChatAction) ⇒ Promise * [.kickChatMember(chatId, userId)](#TelegramBot+kickChatMember) ⇒ Promise * [.unbanChatMember(chatId, userId)](#TelegramBot+unbanChatMember) ⇒ Promise + * [.restrictChatMember(chatId, userId, [options])](#TelegramBot+restrictChatMember) ⇒ Promise + * [.promoteChatMember(chatId, userId, [options])](#TelegramBot+promoteChatMember) ⇒ Promise + * [.exportChatInviteLink(chatId)](#TelegramBot+exportChatInviteLink) ⇒ Promise + * [.setChatPhoto(chatId, photo)](#TelegramBot+setChatPhoto) ⇒ Promise + * [.deleteChatPhoto(chatId)](#TelegramBot+deleteChatPhoto) ⇒ Promise + * [.setChatTitle(chatId, title)](#TelegramBot+setChatTitle) ⇒ Promise + * [.setChatDescription(chatId, description)](#TelegramBot+setChatDescription) ⇒ Promise + * [.pinChatMessage(chatId, messageId)](#TelegramBot+pinChatMessage) ⇒ Promise + * [.unpinChatMessage(chatId)](#TelegramBot+unpinChatMessage) ⇒ Promise * [.answerCallbackQuery(callbackQueryId, text, showAlert, [options])](#TelegramBot+answerCallbackQuery) ⇒ Promise * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ Promise * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ Promise @@ -422,6 +431,142 @@ the group for this to work. Returns True on success. | chatId | Number | String | Unique identifier for the target group or username of the target supergroup | | userId | String | Unique identifier of the target user | + + +### telegramBot.restrictChatMember(chatId, userId, [options]) ⇒ Promise +Use this method to restrict a user in a supergroup. +The bot must be an administrator in the supergroup for this to work +and must have the appropriate admin rights. Pass True for all boolean parameters +to lift restrictions from a user. Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#restrictchatmember + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target chat or username of the target supergroup | +| userId | String | Unique identifier of the target user | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.promoteChatMember(chatId, userId, [options]) ⇒ Promise +Use this method to promote or demote a user in a supergroup or a channel. +The bot must be an administrator in the chat for this to work +and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user. +Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#promotechatmember + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target chat or username of the target supergroup | +| userId | String | | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.exportChatInviteLink(chatId) ⇒ Promise +Use this method to export an invite link to a supergroup or a channel. +The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. +Returns exported invite link as String on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#exportchatinvitelink + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target chat or username of the target supergroup | + + + +### telegramBot.setChatPhoto(chatId, photo) ⇒ Promise +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. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setchatphoto + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| photo | stream.Stream | Buffer | A file path or a Stream. | + + + +### telegramBot.deleteChatPhoto(chatId) ⇒ Promise +Use this method to delete a chat photo. 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. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#deletechatphoto + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | + + + +### telegramBot.setChatTitle(chatId, title) ⇒ Promise +Use this method to change the title of a chat. Titles 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. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setchattitle + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| title | String | New chat title, 1-255 characters | + + + +### telegramBot.setChatDescription(chatId, description) ⇒ Promise +Use this method to change the description of a supergroup or a channel. +The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. +Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setchatdescription + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| description | String | New chat title, 1-255 characters | + + + +### telegramBot.pinChatMessage(chatId, messageId) ⇒ Promise +Use this method to pin a message in a supergroup. +The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. +Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#pinchatmessage + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| messageId | String | Identifier of a message to pin | + + + +### telegramBot.unpinChatMessage(chatId) ⇒ Promise +Use this method to unpin a message in a supergroup chat. +The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. +Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#unpinchatmessage + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | + ### telegramBot.answerCallbackQuery(callbackQueryId, text, showAlert, [options]) ⇒ Promise diff --git a/src/telegram.js b/src/telegram.js index 3d3b609..d78b11a 100644 --- a/src/telegram.js +++ b/src/telegram.js @@ -844,6 +844,157 @@ class TelegramBot extends EventEmitter { return this._request('unbanChatMember', { form }); } + /** + * Use this method to restrict a user in a supergroup. + * The bot must be an administrator in the supergroup for this to work + * and must have the appropriate admin rights. Pass True for all boolean parameters + * to lift restrictions from a user. Returns True on success. + * + * @param {Number|String} chatId Unique identifier for the target chat or username of the target supergroup + * @param {String} userId Unique identifier of the target user + * @param {Object} [options] Additional Telegram query options + * @return {Promise} + * @see https://core.telegram.org/bots/api#restrictchatmember + */ + restrictChatMember(chatId, userId, form = {}) { + form.chat_id = chatId; + form.user_id = userId; + return this._request('restrictChatMember', { form }); + } + + /** + * Use this method to promote or demote a user in a supergroup or a channel. + * The bot must be an administrator in the chat for this to work + * and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user. + * Returns True on success. + * + * @param {Number|String} chatId Unique identifier for the target chat or username of the target supergroup + * @param {String} userId + * @param {Object} [options] Additional Telegram query options + * @return {Promise} + * @see https://core.telegram.org/bots/api#promotechatmember + */ + promoteChatMember(chatId, userId, form = {}) { + form.chat_id = chatId; + form.user_id = userId; + return this._request('promoteChatMember', { form }); + } + + /** + * Use this method to export an invite link to a supergroup or a channel. + * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. + * Returns exported invite link as String on success. + * + * @param {Number|String} chatId Unique identifier for the target chat or username of the target supergroup + * @return {Promise} + * @see https://core.telegram.org/bots/api#exportchatinvitelink + */ + exportChatInviteLink(chatId, form = {}) { + form.chat_id = chatId; + return this._request('exportChatInviteLink', { form }); + } + + /** + * 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. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @param {stream.Stream|Buffer} photo A file path or a Stream. + * @return {Promise} + * @see https://core.telegram.org/bots/api#setchatphoto + */ + setChatPhoto(chatId, photo, options = {}) { + const opts = { + qs: options, + }; + opts.qs.chat_id = chatId; + try { + const sendData = this._formatSendData('photo', photo); + opts.formData = sendData[0]; + opts.qs.photo = sendData[1]; + } catch (ex) { + return Promise.reject(ex); + } + return this._request('setChatPhoto', opts); + } + + /** + * Use this method to delete a chat photo. 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. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @return {Promise} + * @see https://core.telegram.org/bots/api#deletechatphoto + */ + deleteChatPhoto(chatId, form = {}) { + form.chat_id = chatId; + return this._request('deleteChatPhoto', { form }); + } + + /** + * Use this method to change the title of a chat. Titles 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. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @param {String} title New chat title, 1-255 characters + * @return {Promise} + * @see https://core.telegram.org/bots/api#setchattitle + */ + setChatTitle(chatId, title, form = {}) { + form.chat_id = chatId; + form.title = title; + return this._request('setChatTitle', { form }) + } + + /** + * Use this method to change the description of a supergroup or a channel. + * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. + * Returns True on success. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @param {String} description New chat title, 1-255 characters + * @return {Promise} + * @see https://core.telegram.org/bots/api#setchatdescription + */ + setChatDescription(chatId, description, form = {}) { + form.chat_id = chatId; + form.description = description; + return this._request('setChatDescription', { form }) + } + + /** + * Use this method to pin a message in a supergroup. + * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. + * Returns True on success. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @param {String} messageId Identifier of a message to pin + * @return {Promise} + * @see https://core.telegram.org/bots/api#pinchatmessage + */ + pinChatMessage(chatId, messageId, form = {}) { + form.chat_id = chatId; + form.message_id = messageId; + return this._request('pinChatMessage', { form }); + } + + /** + * Use this method to unpin a message in a supergroup chat. + * The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. + * Returns True on success. + * + * @param {Number|String} chatId Unique identifier for the message recipient + * @return {Promise} + * @see https://core.telegram.org/bots/api#unpinchatmessage + */ + unpinChatMessage(chatId, form = {}) { + form.chat_id = chatId; + return this._request('unpinChatMessage', { form }); + } + /** * Use this method to send answers to callback queries sent from * inline keyboards. The answer will be displayed to the user as