diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..c845c46 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,74 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to making participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, gender identity and expression, level of experience, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or +advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies both within project spaces and in public spaces +when an individual is representing the project or its community. Examples of +representing a project or community include using an official project e-mail +address, posting via an official social media account, or acting as an appointed +representative at an online or offline event. Representation of a project may be +further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at mugo@forfuture.co.ke. All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at [http://contributor-covenant.org/version/1/4][version] + +[homepage]: http://contributor-covenant.org +[version]: http://contributor-covenant.org/version/1/4/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5e2f50c..8774044 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,14 +1,49 @@ -If you are willing to contribute, first you should know I will love you and the Telegram Bot comunity too. +# Contributing -Other considerations: +> If you are willing to contribute, first you should know that +> I will love you and so will the Telegram Bot community. + +Before proceeding any further, read the following documents: + +1. [code of conduct][coc] +1. [software license][license] + +[coc]:https://github.com/yagop/node-telegram-bot-api/blob/master/CODE_OF_CONDUCT.md +[license]:https://github.com/yagop/node-telegram-bot-api/blob/master/LICENSE.md + + +### General Information + +**Updating API Reference i.e. generating `doc/api.md`:** + +Run: -- `README.md` is generated by the inline jsdoc with `npm run gen-doc`. -- Provide tests for your methods. For running tests you need to set some environment variables: ```bash -export TEST_TELEGRAM_TOKEN="123456:AAGoASDFJKnlj6uSQLIhjhBgOUY" # Your bot token -export TEST_USER_ID="66368736" # User wich the bot will send the messages (can be yours ID) -export TEST_GROUP_ID="-163889657" # A Telegram group which the bot have access -npm run test +$ npm run gen-doc ``` -- The code is transpilled with babel on Git Hook prepublish -- E=mc² + + +--- + + +**Running tests:** + +Please read `test/README.md` for more information. + + +--- + + +**Transpiling ES6 for older Node.js versions:** + +We use babel to transpile the code: + +```bash +$ npm run build +``` + + +--- + + +> E=mc² diff --git a/README.hbs b/README.hbs deleted file mode 100644 index 6b814e7..0000000 --- a/README.hbs +++ /dev/null @@ -1,74 +0,0 @@ -[![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) [![bitHound Score](https://www.bithound.io/github/yagop/node-telegram-bot-api/badges/score.svg)](https://www.bithound.io/github/yagop/node-telegram-bot-api) [![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬 Telegram-node__telegram__bot__api-blue.svg)](https://telegram.me/node_telegram_bot_api) [![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) - -Node.js module to interact with official [Telegram Bot API](https://core.telegram.org/bots/api). A bot token is needed, to obtain one, talk to [@botfather](https://telegram.me/BotFather) and create a new bot. - -```sh -npm install node-telegram-bot-api -``` - -```js -var TelegramBot = require('node-telegram-bot-api'); - -// replace the value below with the Telegram token you receive from @BotFather -var token = 'YOUR_TELEGRAM_BOT_TOKEN'; - -// Create a bot that uses 'polling' to fetch new updates -var bot = new TelegramBot(token, { polling: true }); - -// Matches "/echo [whatever]" -bot.onText(/\/echo (.+)/, function (msg, match) { - // 'msg' is the received Message from Telegram - // 'match' is the result of executing the regexp above on the text content - // of the message - - var chatId = msg.chat.id; - var resp = match[1]; // the captured "whatever" - - // send back the matched "whatever" to the chat - bot.sendMessage(chatId, resp); -}); - -// Listen for any kind of message. There are different kinds of -// messages. -bot.on('message', function (msg) { - var chatId = msg.chat.id; - - // send a message to the chat acknowledging receipt of their message - bot.sendMessage(chatId, "Received your message"); -}); -``` - -There are some other examples on [examples](https://github.com/yagop/node-telegram-bot-api/tree/master/examples). - -### Events -Every time TelegramBot receives a message, it emits a `message`. Depending on which [message](https://core.telegram.org/bots/api#message) was received, emits an event from this ones: `text`, `audio`, `document`, `photo`, `sticker`, `video`, `voice`, `contact`, `location`, `new_chat_participant`, `left_chat_participant`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`. Its much better to listen a specific event rather than a `message` in order to stay safe from the content. -TelegramBot emits `callback_query` when receives a [Callback Query](https://core.telegram.org/bots/api#callbackquery). -TelegramBot emits `inline_query` when receives an [Inline Query](https://core.telegram.org/bots/api#inlinequery) and `chosen_inline_result` when receives a [ChosenInlineResult](https://core.telegram.org/bots/api#choseninlineresult). Bot must be enabled on [inline mode](https://core.telegram.org/bots/api#inline-mode). -TelegramBot emits `channel_post` on a new incoming channel post of any kind. -TelegramBot emits `edited_message` when a message is edited, and also `edited_message_text` or `edited_message_caption` depending on which type of message was edited. -TelegramBot emits `edited_channel_post` when a channel post is edited, and also `edited_channel_post_text` or `edited_channel_post_caption` depending on which type of channel post was edited. -* * * - -### WebHooks - -Telegram only supports HTTPS connections to WebHooks, in order to set a WebHook a private key file and public certificate must be used. Since August 29, 2015 Telegram supports self signed ones, to generate them: -```bash -# Our private cert will be key.pem, keep in private this file. -openssl genrsa -out key.pem 2048 -# Our public certificate will be crt.pem -openssl req -new -sha256 -key key.pem -out crt.pem -``` -Once they are generated, the `crt.pem` can be provided to `telegramBot.setWebHook(url, crt)` as `crt`. - -## API Reference -{{#class name="TelegramBot"~}} -{{>header~}} -{{>body~}} -{{>member-index~}} -{{>members~}} -{{/class}} -* * * - -[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert -[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates -[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos diff --git a/README.md b/README.md index bd84e57..d62ab21 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,20 @@ -[![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) [![bitHound Score](https://www.bithound.io/github/yagop/node-telegram-bot-api/badges/score.svg)](https://www.bithound.io/github/yagop/node-telegram-bot-api) [![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬 Telegram-node__telegram__bot__api-blue.svg)](https://telegram.me/node_telegram_bot_api) [![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) +[![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) + [![bitHound Score](https://www.bithound.io/github/yagop/node-telegram-bot-api/badges/score.svg)](https://www.bithound.io/github/yagop/node-telegram-bot-api) + [![https://telegram.me/node_telegram_bot_api](https://img.shields.io/badge/💬 Telegram-node__telegram__bot__api-blue.svg)](https://telegram.me/node_telegram_bot_api) + [![https://telegram.me/Yago_Perez](https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)](https://telegram.me/Yago_Perez) Node.js module to interact with official [Telegram Bot API](https://core.telegram.org/bots/api). A bot token is needed, to obtain one, talk to [@botfather](https://telegram.me/BotFather) and create a new bot. +**Installation:** + ```sh npm install node-telegram-bot-api ``` +**Sample Usage:** + ```js var TelegramBot = require('node-telegram-bot-api'); @@ -38,738 +47,55 @@ bot.on('message', function (msg) { }); ``` -There are some other examples on [examples](https://github.com/yagop/node-telegram-bot-api/tree/master/examples). - -### Events -Every time TelegramBot receives a message, it emits a `message`. Depending on which [message](https://core.telegram.org/bots/api#message) was received, emits an event from this ones: `text`, `audio`, `document`, `photo`, `sticker`, `video`, `voice`, `contact`, `location`, `new_chat_participant`, `left_chat_participant`, `new_chat_title`, `new_chat_photo`, `delete_chat_photo`, `group_chat_created`. Its much better to listen a specific event rather than a `message` in order to stay safe from the content. -TelegramBot emits `callback_query` when receives a [Callback Query](https://core.telegram.org/bots/api#callbackquery). -TelegramBot emits `inline_query` when receives an [Inline Query](https://core.telegram.org/bots/api#inlinequery) and `chosen_inline_result` when receives a [ChosenInlineResult](https://core.telegram.org/bots/api#choseninlineresult). Bot must be enabled on [inline mode](https://core.telegram.org/bots/api#inline-mode). -TelegramBot emits `channel_post` on a new incoming channel post of any kind. -TelegramBot emits `edited_message` when a message is edited, and also `edited_message_text` or `edited_message_caption` depending on which type of message was edited. -TelegramBot emits `edited_channel_post` when a channel post is edited, and also `edited_channel_post_text` or `edited_channel_post_caption` depending on which type of channel post was edited. -* * * - -### WebHooks - -Telegram only supports HTTPS connections to WebHooks, in order to set a WebHook a private key file and public certificate must be used. Since August 29, 2015 Telegram supports self signed ones, to generate them: -```bash -# Our private cert will be key.pem, keep in private this file. -openssl genrsa -out key.pem 2048 -# Our public certificate will be crt.pem -openssl req -new -sha256 -key key.pem -out crt.pem -``` -Once they are generated, the `crt.pem` can be provided to `telegramBot.setWebHook(url, crt)` as `crt`. - -## API Reference - - -## TelegramBot -TelegramBot - -**Kind**: global class -**See**: https://core.telegram.org/bots/api - -* [TelegramBot](#TelegramBot) - * [new TelegramBot(token, [options])](#new_TelegramBot_new) - * [.startPolling([options])](#TelegramBot+startPolling) ⇒ Promise - * ~~[.initPolling([options])](#TelegramBot+initPolling) ⇒ Promise~~ - * [.stopPolling()](#TelegramBot+stopPolling) ⇒ Promise - * [.isPolling()](#TelegramBot+isPolling) ⇒ Boolean - * [.openWebHook()](#TelegramBot+openWebHook) ⇒ Promise - * [.closeWebHook()](#TelegramBot+closeWebHook) ⇒ Promise - * [.hasOpenWebHook()](#TelegramBot+hasOpenWebHook) ⇒ Boolean - * [.getMe()](#TelegramBot+getMe) ⇒ Promise - * [.setWebHook(url, [options])](#TelegramBot+setWebHook) ⇒ Promise - * [.deleteWebHook()](#TelegramBot+deleteWebHook) ⇒ Promise - * [.getWebHookInfo()](#TelegramBot+getWebHookInfo) ⇒ Promise - * [.getUpdates([options])](#TelegramBot+getUpdates) ⇒ Promise - * [.processUpdate(update)](#TelegramBot+processUpdate) - * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ Promise - * [.answerInlineQuery(inlineQueryId, results, [options])](#TelegramBot+answerInlineQuery) ⇒ Promise - * [.forwardMessage(chatId, fromChatId, messageId, [options])](#TelegramBot+forwardMessage) ⇒ Promise - * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ Promise - * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ Promise - * [.sendDocument(chatId, doc, [options], [fileOpts])](#TelegramBot+sendDocument) ⇒ Promise - * [.sendSticker(chatId, sticker, [options])](#TelegramBot+sendSticker) ⇒ Promise - * [.sendVideo(chatId, video, [options])](#TelegramBot+sendVideo) ⇒ Promise - * [.sendVoice(chatId, voice, [options])](#TelegramBot+sendVoice) ⇒ Promise - * [.sendChatAction(chatId, action)](#TelegramBot+sendChatAction) ⇒ Promise - * [.kickChatMember(chatId, userId)](#TelegramBot+kickChatMember) ⇒ Promise - * [.unbanChatMember(chatId, userId)](#TelegramBot+unbanChatMember) ⇒ Promise - * [.answerCallbackQuery(callbackQueryId, text, showAlert, [options])](#TelegramBot+answerCallbackQuery) ⇒ Promise - * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ Promise - * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ Promise - * [.editMessageReplyMarkup(replyMarkup, [options])](#TelegramBot+editMessageReplyMarkup) ⇒ Promise - * [.getUserProfilePhotos(userId, [options])](#TelegramBot+getUserProfilePhotos) ⇒ Promise - * [.sendLocation(chatId, latitude, longitude, [options])](#TelegramBot+sendLocation) ⇒ Promise - * [.sendVenue(chatId, latitude, longitude, title, address, [options])](#TelegramBot+sendVenue) ⇒ Promise - * [.sendContact(chatId, phoneNumber, firstName, [options])](#TelegramBot+sendContact) ⇒ Promise - * [.getFile(fileId)](#TelegramBot+getFile) ⇒ Promise - * [.getFileLink(fileId)](#TelegramBot+getFileLink) ⇒ Promise - * [.downloadFile(fileId, downloadDir)](#TelegramBot+downloadFile) ⇒ Promise - * [.onText(regexp, callback)](#TelegramBot+onText) - * [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage) - * [.getChat(chatId)](#TelegramBot+getChat) ⇒ Promise - * [.getChatAdministrators(chatId)](#TelegramBot+getChatAdministrators) ⇒ Promise - * [.getChatMembersCount(chatId)](#TelegramBot+getChatMembersCount) ⇒ Promise - * [.getChatMember(chatId, userId)](#TelegramBot+getChatMember) ⇒ Promise - * [.leaveChat(chatId)](#TelegramBot+leaveChat) ⇒ Promise - * [.sendGame(chatId, gameShortName, [options])](#TelegramBot+sendGame) ⇒ Promise - * [.setGameScore(userId, score, [options])](#TelegramBot+setGameScore) ⇒ Promise - * [.getGameHighScores(userId, [options])](#TelegramBot+getGameHighScores) ⇒ Promise - - - -### new TelegramBot(token, [options]) -Both request method to obtain messages are implemented. To use standard polling, set `polling: true` -on `options`. Notice that [webHook](https://core.telegram.org/bots/api#setwebhook) will need a SSL certificate. -Emits `message` when a message arrives. - - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| token | String | | Bot Token | -| [options] | Object | | | -| [options.polling] | Boolean | Object | false | Set true to enable polling or set options. If a WebHook has been set, it will be deleted automatically. | -| [options.polling.timeout] | String | Number | 10 | Timeout in seconds for long polling | -| [options.polling.interval] | String | Number | 300 | Interval between requests in miliseconds | -| [options.polling.autoStart] | Boolean | true | Start polling immediately | -| [options.webHook] | Boolean | Object | false | Set true to enable WebHook or set options | -| [options.webHook.port] | Number | 8443 | Port to bind to | -| [options.webHook.key] | String | | Path to file with PEM private key for webHook server. The file is read **synchronously**! | -| [options.webHook.cert] | String | | Path to file with PEM certificate (public) for webHook server. The file is read **synchronously**! | -| [options.webHook.pfx] | String | | Path to file with PFX private key and certificate chain for webHook server. The file is read **synchronously**! | -| [options.webHook.autoOpen] | Boolean | true | Open webHook immediately | -| [options.webHook.https] | Object | | Options to be passed to `https.createServer()`. Note that `options.webHook.key`, `options.webHook.cert` and `options.webHook.pfx`, if provided, will be used to override `key`, `cert` and `pfx` in this object, respectively. See https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener for more information. | -| [options.onlyFirstMatch] | Boolean | false | Set to true to stop after first match. Otherwise, all regexps are executed | -| [options.request] | Object | | Options which will be added for all requests to telegram api. See https://github.com/request/request#requestoptions-callback for more information. | -| [options.baseApiUrl] | String | https://api.telegram.org | API Base URl; useful for proxying and testing | -| [options.filepath] | Boolean | true | Allow passing file-paths as arguments when sending files, such as photos using `TelegramBot#sendPhoto()`. | - - - -### telegramBot.startPolling([options]) ⇒ Promise -Start polling. -Rejects returned promise if a WebHook is being used by this instance. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - -| Param | Type | Default | Description | -| --- | --- | --- | --- | -| [options] | Object | | | -| [options.restart] | Boolean | true | Consecutive calls to this method causes polling to be restarted | - - - -### ~~telegramBot.initPolling([options]) ⇒ Promise~~ -***Deprecated*** - -Alias of `TelegramBot#startPolling()`. This is **deprecated**. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - -| Param | Type | -| --- | --- | -| [options] | Object | - - - -### telegramBot.stopPolling() ⇒ Promise -Stops polling after the last polling request resolves. -Multiple invocations do nothing if polling is already stopped. -Returning the promise of the last polling request is **deprecated**. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - - -### telegramBot.isPolling() ⇒ Boolean -Return true if polling. Otherwise, false. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - - -### telegramBot.openWebHook() ⇒ Promise -Open webhook. -Multiple invocations do nothing if webhook is already open. -Rejects returned promise if Polling is being used by this instance. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - - -### telegramBot.closeWebHook() ⇒ Promise -Close webhook after closing all current connections. -Multiple invocations do nothing if webhook is already closed. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**Returns**: Promise - promise - - -### telegramBot.hasOpenWebHook() ⇒ Boolean -Return true if using webhook and it is open i.e. accepts connections. -Otherwise, false. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - - -### telegramBot.getMe() ⇒ Promise -Returns basic information about the bot in form of a `User` object. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getme - - -### telegramBot.setWebHook(url, [options]) ⇒ Promise -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. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#setwebhook - -| Param | Type | Description | -| --- | --- | --- | -| url | String | URL where Telegram will make HTTP Post. Leave empty to delete webHook. | -| [options] | Object | Additional Telegram query options | -| [options.certificate] | String | stream.Stream | PEM certificate key (public). | - - - -### telegramBot.deleteWebHook() ⇒ Promise -Use this method to remove webhook integration if you decide to -switch back to getUpdates. Returns True on success. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#deletewebhook - - -### telegramBot.getWebHookInfo() ⇒ Promise -Use this method to get current webhook status. -On success, returns a [WebhookInfo](https://core.telegram.org/bots/api#webhookinfo) object. -If the bot is using getUpdates, will return an object with the -url field empty. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getwebhookinfo - - -### telegramBot.getUpdates([options]) ⇒ Promise -Use this method to receive incoming updates using long polling. -This method has an [older, compatible signature][getUpdates-v0.25.0] -that is being deprecated. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getupdates - -| Param | Type | Description | -| --- | --- | --- | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.processUpdate(update) -Process an update; emitting the proper events and executing regexp -callbacks. This method is useful should you be using a different -way to fetch updates, other than those provided by TelegramBot. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#update - -| Param | Type | -| --- | --- | -| update | Object | - - - -### telegramBot.sendMessage(chatId, text, [options]) ⇒ Promise -Send text message. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendmessage - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| text | String | Text of the message to be sent | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.answerInlineQuery(inlineQueryId, results, [options]) ⇒ Promise -Send answers to an inline query. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#answerinlinequery - -| Param | Type | Description | -| --- | --- | --- | -| inlineQueryId | String | Unique identifier of the query | -| results | Array.<InlineQueryResult> | An array of results for the inline query | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.forwardMessage(chatId, fromChatId, messageId, [options]) ⇒ Promise -Forward messages of any kind. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| fromChatId | Number | String | Unique identifier for the chat where the original message was sent | -| messageId | Number | String | Unique message identifier | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendPhoto(chatId, photo, [options]) ⇒ Promise -Send photo - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendphoto - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| photo | String | stream.Stream | Buffer | A file path or a Stream. Can also be a `file_id` previously uploaded | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendAudio(chatId, audio, [options]) ⇒ Promise -Send audio - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendaudio - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| audio | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendDocument(chatId, doc, [options], [fileOpts]) ⇒ Promise -Send Document - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendDocument - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| doc | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | -| [options] | Object | Additional Telegram query options | -| [fileOpts] | Object | Optional file related meta-data | - - - -### telegramBot.sendSticker(chatId, sticker, [options]) ⇒ Promise -Send .webp stickers. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendsticker - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| sticker | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. Stickers are WebP format files. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendVideo(chatId, video, [options]) ⇒ Promise -Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document). - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendvideo - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| video | String | stream.Stream | Buffer | A file path or Stream. Can also be a `file_id` previously uploaded. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendVoice(chatId, voice, [options]) ⇒ Promise -Send voice - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendvoice - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| voice | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendChatAction(chatId, action) ⇒ Promise -Send chat action. -`typing` for text messages, -`upload_photo` for photos, `record_video` or `upload_video` for videos, -`record_audio` or `upload_audio` for audio files, `upload_document` for general files, -`find_location` for location data. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendchataction - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| action | String | Type of action to broadcast. | - - - -### telegramBot.kickChatMember(chatId, userId) ⇒ Promise -Use this method to kick a user from a group or a supergroup. -In the case of supergroups, the user will not be able to return -to the group on their own using invite links, etc., unless unbanned -first. The bot must be an administrator in the group for this to work. -Returns True on success. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#kickchatmember - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | -| userId | String | Unique identifier of the target user | - - - -### telegramBot.unbanChatMember(chatId, userId) ⇒ Promise -Use this method to unban a previously kicked user in a supergroup. -The user will not return to the group automatically, but will be -able to join via link, etc. The bot must be an administrator in -the group for this to work. Returns True on success. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#unbanchatmember - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | -| userId | String | Unique identifier of the target user | - - - -### telegramBot.answerCallbackQuery(callbackQueryId, text, showAlert, [options]) ⇒ Promise -Use this method to send answers to callback queries sent from -inline keyboards. The answer will be displayed to the user as -a notification at the top of the chat screen or as an alert. -On success, True is returned. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#answercallbackquery - -| Param | Type | Description | -| --- | --- | --- | -| callbackQueryId | Number | String | Unique identifier for the query to be answered | -| text | String | Text of the notification. If not specified, nothing will be shown to the user | -| showAlert | Boolean | Whether to show an alert or a notification at the top of the screen | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.editMessageText(text, [options]) ⇒ Promise -Use this method to edit text messages sent by the bot or via -the bot (for inline bots). On success, the edited Message is -returned. - -Note that you must provide one of chat_id, message_id, or -inline_message_id in your request. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#editmessagetext - -| Param | Type | Description | -| --- | --- | --- | -| text | String | New text of the message | -| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | - - - -### telegramBot.editMessageCaption(caption, [options]) ⇒ Promise -Use this method to edit captions of messages sent by the -bot or via the bot (for inline bots). On success, the -edited Message is returned. - -Note that you must provide one of chat_id, message_id, or -inline_message_id in your request. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#editmessagecaption - -| Param | Type | Description | -| --- | --- | --- | -| caption | String | New caption of the message | -| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | - - - -### telegramBot.editMessageReplyMarkup(replyMarkup, [options]) ⇒ Promise -Use this method to edit only the reply markup of messages -sent by the bot or via the bot (for inline bots). -On success, the edited Message is returned. - -Note that you must provide one of chat_id, message_id, or -inline_message_id in your request. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#editmessagetext - -| Param | Type | Description | -| --- | --- | --- | -| replyMarkup | Object | A JSON-serialized object for an inline keyboard. | -| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | - - - -### telegramBot.getUserProfilePhotos(userId, [options]) ⇒ Promise -Use this method to get a list of profile pictures for a user. -Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos) object. -This method has an [older, compatible signature][getUserProfilePhotos-v0.25.0] -that is being deprecated. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getuserprofilephotos - -| Param | Type | Description | -| --- | --- | --- | -| userId | Number | String | Unique identifier of the target user | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendLocation(chatId, latitude, longitude, [options]) ⇒ Promise -Send location. -Use this method to send point on the map. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendlocation - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| latitude | Float | Latitude of location | -| longitude | Float | Longitude of location | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendVenue(chatId, latitude, longitude, title, address, [options]) ⇒ Promise -Send venue. -Use this method to send information about a venue. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendvenue - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| latitude | Float | Latitude of location | -| longitude | Float | Longitude of location | -| title | String | Name of the venue | -| address | String | Address of the venue | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.sendContact(chatId, phoneNumber, firstName, [options]) ⇒ Promise -Send contact. -Use this method to send phone contacts. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendcontact - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| phoneNumber | String | Contact's phone number | -| firstName | String | Contact's first name | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.getFile(fileId) ⇒ Promise -Get file. -Use this method to get basic info about a file and prepare it for downloading. -Attention: link will be valid for 1 hour. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getfile - -| Param | Type | Description | -| --- | --- | --- | -| fileId | String | File identifier to get info about | - - - -### telegramBot.getFileLink(fileId) ⇒ Promise -Get link for file. -Use this method to get link for file for subsequent use. -Attention: link will be valid for 1 hour. - -This method is a sugar extension of the (getFile)[#getfilefileid] method, -which returns just path to file on remote server (you will have to manually build full uri after that). - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**Returns**: Promise - promise Promise which will have *fileURI* in resolve callback -**See**: https://core.telegram.org/bots/api#getfile - -| Param | Type | Description | -| --- | --- | --- | -| fileId | String | File identifier to get info about | - - - -### telegramBot.downloadFile(fileId, downloadDir) ⇒ Promise -Downloads file in the specified folder. -This is just a sugar for (getFile)[#getfilefiled] method - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**Returns**: Promise - promise Promise, which will have *filePath* of downloaded file in resolve callback - -| Param | Type | Description | -| --- | --- | --- | -| fileId | String | File identifier to get info about | -| downloadDir | String | Absolute path to the folder in which file will be saved | - - - -### telegramBot.onText(regexp, callback) -Register a RegExp to test against an incomming text message. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - -| Param | Type | Description | -| --- | --- | --- | -| regexp | RegExp | RegExp to be executed with `exec`. | -| callback | function | Callback will be called with 2 parameters, the `msg` and the result of executing `regexp.exec` on message text. | - - - -### telegramBot.onReplyToMessage(chatId, messageId, callback) -Register a reply to wait for a message response. - -**Kind**: instance method of [TelegramBot](#TelegramBot) - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | The chat id where the message cames from. | -| messageId | Number | String | The message id to be replied. | -| callback | function | Callback will be called with the reply message. | - - - -### telegramBot.getChat(chatId) ⇒ Promise -Use this method to get up to date information about the chat -(current name of the user for one-on-one conversations, current -username of a user, group or channel, etc.). - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getchat - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target chat or username of the target supergroup or channel | - - - -### telegramBot.getChatAdministrators(chatId) ⇒ Promise -Returns the administrators in a chat in form of an Array of `ChatMember` objects. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getchatadministrators - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | - - - -### telegramBot.getChatMembersCount(chatId) ⇒ Promise -Use this method to get the number of members in a chat. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getchatmemberscount - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | - - - -### telegramBot.getChatMember(chatId, userId) ⇒ Promise -Use this method to get information about a member of a chat. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getchatmember - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | -| userId | String | Unique identifier of the target user | - - - -### telegramBot.leaveChat(chatId) ⇒ Promise -Leave a group, supergroup or channel. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#leavechat - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the target group or username of the target supergroup (in the format @supergroupusername) | - - - -### telegramBot.sendGame(chatId, gameShortName, [options]) ⇒ Promise -Use this method to send a game. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#sendgame - -| Param | Type | Description | -| --- | --- | --- | -| chatId | Number | String | Unique identifier for the message recipient | -| gameShortName | String | name of the game to be sent. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.setGameScore(userId, score, [options]) ⇒ Promise -Use this method to set the score of the specified user in a game. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#setgamescore - -| Param | Type | Description | -| --- | --- | --- | -| userId | String | Unique identifier of the target user | -| score | Number | New score value. | -| [options] | Object | Additional Telegram query options | - - - -### telegramBot.getGameHighScores(userId, [options]) ⇒ Promise -Use this method to get data for high score table. - -**Kind**: instance method of [TelegramBot](#TelegramBot) -**See**: https://core.telegram.org/bots/api#getgamehighscores - -| Param | Type | Description | -| --- | --- | --- | -| userId | String | Unique identifier of the target user | -| [options] | Object | Additional Telegram query options | * * * -[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert -[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates -[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos + +## Documentation + + * Usage ([release][usage-release] / [development][usage-dev]) + * Examples ([release][examples-release] / [development][examples-dev]) + * Help Information ([release][help-release] / [development][help-dev]) + * API Reference ([release][api-release] / [development][api-dev]) + * [Contributing to the Project][contributing] + +_**Note**: Development is done against the **master** branch. Code for the latest release +resides on the **release** branch._ + +[usage-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/usage.md +[examples-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/help.md +[help-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/examples +[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md + +[usage-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md +[examples-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md +[help-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples +[api-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/api.md +[contributing]:https://github.com/yagop/node-telegram-bot-api/tree/master/CONTRIBUTING.md + + +* * * + + +## Our Community + +We have a [Telegram channel][tg-channel] where we post updates on +the Project. Head over and subscribe! + +Some things built using this library, and might interest you: + +* [tgfancy](https://github.com/GochoMugo/tgfancy): A Fancy, Higher-Level Wrapper for Telegram Bot API +* [node-telegram-bot-api-middleware](https://github.com/idchlife/node-telegram-bot-api-middleware): Middleware for node-telegram-bot-api + + +* * * + + +## License Information + +**The MIT License (MIT)** + +Copyright (c) 2015 Yago + + +[tg-channel]:https://telegram.me/node_telegram_bot_api diff --git a/doc/api.hbs b/doc/api.hbs new file mode 100644 index 0000000..13f2af7 --- /dev/null +++ b/doc/api.hbs @@ -0,0 +1,15 @@ +# API Reference + +{{#class name="TelegramBot"~}} +{{>header~}} +{{>body~}} +{{>member-index~}} +{{>members~}} +{{/class}} +* * * + + +[usage-sending-files-performance]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md#sending-files-performance +[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert +[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates +[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos diff --git a/doc/api.md b/doc/api.md new file mode 100644 index 0000000..9fa7798 --- /dev/null +++ b/doc/api.md @@ -0,0 +1,716 @@ +# API Reference + + + +## TelegramBot +TelegramBot + +**Kind**: global class +**See**: https://core.telegram.org/bots/api + +* [TelegramBot](#TelegramBot) + * [new TelegramBot(token, [options])](#new_TelegramBot_new) + * [.startPolling([options])](#TelegramBot+startPolling) ⇒ Promise + * ~~[.initPolling([options])](#TelegramBot+initPolling) ⇒ Promise~~ + * [.stopPolling()](#TelegramBot+stopPolling) ⇒ Promise + * [.isPolling()](#TelegramBot+isPolling) ⇒ Boolean + * [.openWebHook()](#TelegramBot+openWebHook) ⇒ Promise + * [.closeWebHook()](#TelegramBot+closeWebHook) ⇒ Promise + * [.hasOpenWebHook()](#TelegramBot+hasOpenWebHook) ⇒ Boolean + * [.getMe()](#TelegramBot+getMe) ⇒ Promise + * [.setWebHook(url, [options])](#TelegramBot+setWebHook) ⇒ Promise + * [.deleteWebHook()](#TelegramBot+deleteWebHook) ⇒ Promise + * [.getWebHookInfo()](#TelegramBot+getWebHookInfo) ⇒ Promise + * [.getUpdates([options])](#TelegramBot+getUpdates) ⇒ Promise + * [.processUpdate(update)](#TelegramBot+processUpdate) + * [.sendMessage(chatId, text, [options])](#TelegramBot+sendMessage) ⇒ Promise + * [.answerInlineQuery(inlineQueryId, results, [options])](#TelegramBot+answerInlineQuery) ⇒ Promise + * [.forwardMessage(chatId, fromChatId, messageId, [options])](#TelegramBot+forwardMessage) ⇒ Promise + * [.sendPhoto(chatId, photo, [options])](#TelegramBot+sendPhoto) ⇒ Promise + * [.sendAudio(chatId, audio, [options])](#TelegramBot+sendAudio) ⇒ Promise + * [.sendDocument(chatId, doc, [options], [fileOpts])](#TelegramBot+sendDocument) ⇒ Promise + * [.sendSticker(chatId, sticker, [options])](#TelegramBot+sendSticker) ⇒ Promise + * [.sendVideo(chatId, video, [options])](#TelegramBot+sendVideo) ⇒ Promise + * [.sendVoice(chatId, voice, [options])](#TelegramBot+sendVoice) ⇒ Promise + * [.sendChatAction(chatId, action)](#TelegramBot+sendChatAction) ⇒ Promise + * [.kickChatMember(chatId, userId)](#TelegramBot+kickChatMember) ⇒ Promise + * [.unbanChatMember(chatId, userId)](#TelegramBot+unbanChatMember) ⇒ Promise + * [.answerCallbackQuery(callbackQueryId, text, showAlert, [options])](#TelegramBot+answerCallbackQuery) ⇒ Promise + * [.editMessageText(text, [options])](#TelegramBot+editMessageText) ⇒ Promise + * [.editMessageCaption(caption, [options])](#TelegramBot+editMessageCaption) ⇒ Promise + * [.editMessageReplyMarkup(replyMarkup, [options])](#TelegramBot+editMessageReplyMarkup) ⇒ Promise + * [.getUserProfilePhotos(userId, [options])](#TelegramBot+getUserProfilePhotos) ⇒ Promise + * [.sendLocation(chatId, latitude, longitude, [options])](#TelegramBot+sendLocation) ⇒ Promise + * [.sendVenue(chatId, latitude, longitude, title, address, [options])](#TelegramBot+sendVenue) ⇒ Promise + * [.sendContact(chatId, phoneNumber, firstName, [options])](#TelegramBot+sendContact) ⇒ Promise + * [.getFile(fileId)](#TelegramBot+getFile) ⇒ Promise + * [.getFileLink(fileId)](#TelegramBot+getFileLink) ⇒ Promise + * [.downloadFile(fileId, downloadDir)](#TelegramBot+downloadFile) ⇒ Promise + * [.onText(regexp, callback)](#TelegramBot+onText) + * [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage) + * [.getChat(chatId)](#TelegramBot+getChat) ⇒ Promise + * [.getChatAdministrators(chatId)](#TelegramBot+getChatAdministrators) ⇒ Promise + * [.getChatMembersCount(chatId)](#TelegramBot+getChatMembersCount) ⇒ Promise + * [.getChatMember(chatId, userId)](#TelegramBot+getChatMember) ⇒ Promise + * [.leaveChat(chatId)](#TelegramBot+leaveChat) ⇒ Promise + * [.sendGame(chatId, gameShortName, [options])](#TelegramBot+sendGame) ⇒ Promise + * [.setGameScore(userId, score, [options])](#TelegramBot+setGameScore) ⇒ Promise + * [.getGameHighScores(userId, [options])](#TelegramBot+getGameHighScores) ⇒ Promise + + + +### new TelegramBot(token, [options]) +Both request method to obtain messages are implemented. To use standard polling, set `polling: true` +on `options`. Notice that [webHook](https://core.telegram.org/bots/api#setwebhook) will need a SSL certificate. +Emits `message` when a message arrives. + + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| token | String | | Bot Token | +| [options] | Object | | | +| [options.polling] | Boolean | Object | false | Set true to enable polling or set options. If a WebHook has been set, it will be deleted automatically. | +| [options.polling.timeout] | String | Number | 10 | Timeout in seconds for long polling | +| [options.polling.interval] | String | Number | 300 | Interval between requests in miliseconds | +| [options.polling.autoStart] | Boolean | true | Start polling immediately | +| [options.webHook] | Boolean | Object | false | Set true to enable WebHook or set options | +| [options.webHook.port] | Number | 8443 | Port to bind to | +| [options.webHook.key] | String | | Path to file with PEM private key for webHook server. The file is read **synchronously**! | +| [options.webHook.cert] | String | | Path to file with PEM certificate (public) for webHook server. The file is read **synchronously**! | +| [options.webHook.pfx] | String | | Path to file with PFX private key and certificate chain for webHook server. The file is read **synchronously**! | +| [options.webHook.autoOpen] | Boolean | true | Open webHook immediately | +| [options.webHook.https] | Object | | Options to be passed to `https.createServer()`. Note that `options.webHook.key`, `options.webHook.cert` and `options.webHook.pfx`, if provided, will be used to override `key`, `cert` and `pfx` in this object, respectively. See https://nodejs.org/api/https.html#https_https_createserver_options_requestlistener for more information. | +| [options.onlyFirstMatch] | Boolean | false | Set to true to stop after first match. Otherwise, all regexps are executed | +| [options.request] | Object | | Options which will be added for all requests to telegram api. See https://github.com/request/request#requestoptions-callback for more information. | +| [options.baseApiUrl] | String | https://api.telegram.org | API Base URl; useful for proxying and testing | +| [options.filepath] | Boolean | true | Allow passing file-paths as arguments when sending files, such as photos using `TelegramBot#sendPhoto()`. See [usage information][usage-sending-files-performance] for more information on this option and its consequences. | + + + +### telegramBot.startPolling([options]) ⇒ Promise +Start polling. +Rejects returned promise if a WebHook is being used by this instance. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + +| Param | Type | Default | Description | +| --- | --- | --- | --- | +| [options] | Object | | | +| [options.restart] | Boolean | true | Consecutive calls to this method causes polling to be restarted | + + + +### ~~telegramBot.initPolling([options]) ⇒ Promise~~ +***Deprecated*** + +Alias of `TelegramBot#startPolling()`. This is **deprecated**. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + +| Param | Type | +| --- | --- | +| [options] | Object | + + + +### telegramBot.stopPolling() ⇒ Promise +Stops polling after the last polling request resolves. +Multiple invocations do nothing if polling is already stopped. +Returning the promise of the last polling request is **deprecated**. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + + +### telegramBot.isPolling() ⇒ Boolean +Return true if polling. Otherwise, false. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + + +### telegramBot.openWebHook() ⇒ Promise +Open webhook. +Multiple invocations do nothing if webhook is already open. +Rejects returned promise if Polling is being used by this instance. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + + +### telegramBot.closeWebHook() ⇒ Promise +Close webhook after closing all current connections. +Multiple invocations do nothing if webhook is already closed. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - promise + + +### telegramBot.hasOpenWebHook() ⇒ Boolean +Return true if using webhook and it is open i.e. accepts connections. +Otherwise, false. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + + +### telegramBot.getMe() ⇒ Promise +Returns basic information about the bot in form of a `User` object. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getme + + +### telegramBot.setWebHook(url, [options]) ⇒ Promise +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. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setwebhook + +| Param | Type | Description | +| --- | --- | --- | +| url | String | URL where Telegram will make HTTP Post. Leave empty to delete webHook. | +| [options] | Object | Additional Telegram query options | +| [options.certificate] | String | stream.Stream | PEM certificate key (public). | + + + +### telegramBot.deleteWebHook() ⇒ Promise +Use this method to remove webhook integration if you decide to +switch back to getUpdates. Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#deletewebhook + + +### telegramBot.getWebHookInfo() ⇒ Promise +Use this method to get current webhook status. +On success, returns a [WebhookInfo](https://core.telegram.org/bots/api#webhookinfo) object. +If the bot is using getUpdates, will return an object with the +url field empty. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getwebhookinfo + + +### telegramBot.getUpdates([options]) ⇒ Promise +Use this method to receive incoming updates using long polling. +This method has an [older, compatible signature][getUpdates-v0.25.0] +that is being deprecated. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getupdates + +| Param | Type | Description | +| --- | --- | --- | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.processUpdate(update) +Process an update; emitting the proper events and executing regexp +callbacks. This method is useful should you be using a different +way to fetch updates, other than those provided by TelegramBot. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#update + +| Param | Type | +| --- | --- | +| update | Object | + + + +### telegramBot.sendMessage(chatId, text, [options]) ⇒ Promise +Send text message. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendmessage + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| text | String | Text of the message to be sent | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.answerInlineQuery(inlineQueryId, results, [options]) ⇒ Promise +Send answers to an inline query. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#answerinlinequery + +| Param | Type | Description | +| --- | --- | --- | +| inlineQueryId | String | Unique identifier of the query | +| results | Array.<InlineQueryResult> | An array of results for the inline query | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.forwardMessage(chatId, fromChatId, messageId, [options]) ⇒ Promise +Forward messages of any kind. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| fromChatId | Number | String | Unique identifier for the chat where the original message was sent | +| messageId | Number | String | Unique message identifier | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendPhoto(chatId, photo, [options]) ⇒ Promise +Send photo + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendphoto + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| photo | String | stream.Stream | Buffer | A file path or a Stream. Can also be a `file_id` previously uploaded | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendAudio(chatId, audio, [options]) ⇒ Promise +Send audio + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendaudio + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| audio | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendDocument(chatId, doc, [options], [fileOpts]) ⇒ Promise +Send Document + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendDocument + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| doc | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | +| [fileOpts] | Object | Optional file related meta-data | + + + +### telegramBot.sendSticker(chatId, sticker, [options]) ⇒ Promise +Send .webp stickers. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendsticker + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| sticker | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. Stickers are WebP format files. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendVideo(chatId, video, [options]) ⇒ Promise +Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document). + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendvideo + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| video | String | stream.Stream | Buffer | A file path or Stream. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendVoice(chatId, voice, [options]) ⇒ Promise +Send voice + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendvoice + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| voice | String | stream.Stream | Buffer | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendChatAction(chatId, action) ⇒ Promise +Send chat action. +`typing` for text messages, +`upload_photo` for photos, `record_video` or `upload_video` for videos, +`record_audio` or `upload_audio` for audio files, `upload_document` for general files, +`find_location` for location data. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendchataction + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| action | String | Type of action to broadcast. | + + + +### telegramBot.kickChatMember(chatId, userId) ⇒ Promise +Use this method to kick a user from a group or a supergroup. +In the case of supergroups, the user will not be able to return +to the group on their own using invite links, etc., unless unbanned +first. The bot must be an administrator in the group for this to work. +Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#kickchatmember + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | +| userId | String | Unique identifier of the target user | + + + +### telegramBot.unbanChatMember(chatId, userId) ⇒ Promise +Use this method to unban a previously kicked user in a supergroup. +The user will not return to the group automatically, but will be +able to join via link, etc. The bot must be an administrator in +the group for this to work. Returns True on success. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#unbanchatmember + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | +| userId | String | Unique identifier of the target user | + + + +### telegramBot.answerCallbackQuery(callbackQueryId, text, showAlert, [options]) ⇒ Promise +Use this method to send answers to callback queries sent from +inline keyboards. The answer will be displayed to the user as +a notification at the top of the chat screen or as an alert. +On success, True is returned. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#answercallbackquery + +| Param | Type | Description | +| --- | --- | --- | +| callbackQueryId | Number | String | Unique identifier for the query to be answered | +| text | String | Text of the notification. If not specified, nothing will be shown to the user | +| showAlert | Boolean | Whether to show an alert or a notification at the top of the screen | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.editMessageText(text, [options]) ⇒ Promise +Use this method to edit text messages sent by the bot or via +the bot (for inline bots). On success, the edited Message is +returned. + +Note that you must provide one of chat_id, message_id, or +inline_message_id in your request. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#editmessagetext + +| Param | Type | Description | +| --- | --- | --- | +| text | String | New text of the message | +| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | + + + +### telegramBot.editMessageCaption(caption, [options]) ⇒ Promise +Use this method to edit captions of messages sent by the +bot or via the bot (for inline bots). On success, the +edited Message is returned. + +Note that you must provide one of chat_id, message_id, or +inline_message_id in your request. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#editmessagecaption + +| Param | Type | Description | +| --- | --- | --- | +| caption | String | New caption of the message | +| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | + + + +### telegramBot.editMessageReplyMarkup(replyMarkup, [options]) ⇒ Promise +Use this method to edit only the reply markup of messages +sent by the bot or via the bot (for inline bots). +On success, the edited Message is returned. + +Note that you must provide one of chat_id, message_id, or +inline_message_id in your request. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#editmessagetext + +| Param | Type | Description | +| --- | --- | --- | +| replyMarkup | Object | A JSON-serialized object for an inline keyboard. | +| [options] | Object | Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here) | + + + +### telegramBot.getUserProfilePhotos(userId, [options]) ⇒ Promise +Use this method to get a list of profile pictures for a user. +Returns a [UserProfilePhotos](https://core.telegram.org/bots/api#userprofilephotos) object. +This method has an [older, compatible signature][getUserProfilePhotos-v0.25.0] +that is being deprecated. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getuserprofilephotos + +| Param | Type | Description | +| --- | --- | --- | +| userId | Number | String | Unique identifier of the target user | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendLocation(chatId, latitude, longitude, [options]) ⇒ Promise +Send location. +Use this method to send point on the map. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendlocation + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| latitude | Float | Latitude of location | +| longitude | Float | Longitude of location | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendVenue(chatId, latitude, longitude, title, address, [options]) ⇒ Promise +Send venue. +Use this method to send information about a venue. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendvenue + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| latitude | Float | Latitude of location | +| longitude | Float | Longitude of location | +| title | String | Name of the venue | +| address | String | Address of the venue | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.sendContact(chatId, phoneNumber, firstName, [options]) ⇒ Promise +Send contact. +Use this method to send phone contacts. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendcontact + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| phoneNumber | String | Contact's phone number | +| firstName | String | Contact's first name | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.getFile(fileId) ⇒ Promise +Get file. +Use this method to get basic info about a file and prepare it for downloading. +Attention: link will be valid for 1 hour. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getfile + +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | + + + +### telegramBot.getFileLink(fileId) ⇒ Promise +Get link for file. +Use this method to get link for file for subsequent use. +Attention: link will be valid for 1 hour. + +This method is a sugar extension of the (getFile)[#getfilefileid] method, +which returns just path to file on remote server (you will have to manually build full uri after that). + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - promise Promise which will have *fileURI* in resolve callback +**See**: https://core.telegram.org/bots/api#getfile + +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | + + + +### telegramBot.downloadFile(fileId, downloadDir) ⇒ Promise +Downloads file in the specified folder. +This is just a sugar for (getFile)[#getfilefiled] method + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**Returns**: Promise - promise Promise, which will have *filePath* of downloaded file in resolve callback + +| Param | Type | Description | +| --- | --- | --- | +| fileId | String | File identifier to get info about | +| downloadDir | String | Absolute path to the folder in which file will be saved | + + + +### telegramBot.onText(regexp, callback) +Register a RegExp to test against an incomming text message. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + +| Param | Type | Description | +| --- | --- | --- | +| regexp | RegExp | RegExp to be executed with `exec`. | +| callback | function | Callback will be called with 2 parameters, the `msg` and the result of executing `regexp.exec` on message text. | + + + +### telegramBot.onReplyToMessage(chatId, messageId, callback) +Register a reply to wait for a message response. + +**Kind**: instance method of [TelegramBot](#TelegramBot) + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | The chat id where the message cames from. | +| messageId | Number | String | The message id to be replied. | +| callback | function | Callback will be called with the reply message. | + + + +### telegramBot.getChat(chatId) ⇒ Promise +Use this method to get up to date information about the chat +(current name of the user for one-on-one conversations, current +username of a user, group or channel, etc.). + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getchat + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target chat or username of the target supergroup or channel | + + + +### telegramBot.getChatAdministrators(chatId) ⇒ Promise +Returns the administrators in a chat in form of an Array of `ChatMember` objects. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getchatadministrators + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | + + + +### telegramBot.getChatMembersCount(chatId) ⇒ Promise +Use this method to get the number of members in a chat. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getchatmemberscount + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | + + + +### telegramBot.getChatMember(chatId, userId) ⇒ Promise +Use this method to get information about a member of a chat. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getchatmember + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup | +| userId | String | Unique identifier of the target user | + + + +### telegramBot.leaveChat(chatId) ⇒ Promise +Leave a group, supergroup or channel. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#leavechat + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the target group or username of the target supergroup (in the format @supergroupusername) | + + + +### telegramBot.sendGame(chatId, gameShortName, [options]) ⇒ Promise +Use this method to send a game. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#sendgame + +| Param | Type | Description | +| --- | --- | --- | +| chatId | Number | String | Unique identifier for the message recipient | +| gameShortName | String | name of the game to be sent. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.setGameScore(userId, score, [options]) ⇒ Promise +Use this method to set the score of the specified user in a game. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#setgamescore + +| Param | Type | Description | +| --- | --- | --- | +| userId | String | Unique identifier of the target user | +| score | Number | New score value. | +| [options] | Object | Additional Telegram query options | + + + +### telegramBot.getGameHighScores(userId, [options]) ⇒ Promise +Use this method to get data for high score table. + +**Kind**: instance method of [TelegramBot](#TelegramBot) +**See**: https://core.telegram.org/bots/api#getgamehighscores + +| Param | Type | Description | +| --- | --- | --- | +| userId | String | Unique identifier of the target user | +| [options] | Object | Additional Telegram query options | + +* * * + + +[usage-sending-files-performance]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md#sending-files-performance +[setWebHook-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#telegrambotsetwebhookurl-cert +[getUpdates-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUpdates +[getUserProfilePhotos-v0.25.0]:https://github.com/yagop/node-telegram-bot-api/tree/4e5a493cadfaad5589a8d79e55d9e0d103000ce4#TelegramBot+getUserProfilePhotos diff --git a/doc/help.md b/doc/help.md new file mode 100644 index 0000000..6759bb2 --- /dev/null +++ b/doc/help.md @@ -0,0 +1,175 @@ +# Help Information + +* [Common Pitfalls](#pitfalls) +* [FAQs](#faqs) + + +* * * + + + +## Common Pitfalls + +1. [Failing to receive reply with `ReplyToMessage`](#reply-to-message) + + +--- + + + +**Failing to receive reply with `ReplyToMessage`** + +The user has to **manually reply** to your message, by tapping on the +bot's message and select *Reply*. + +Sources: + + * Issue #113: https://github.com/yagop/node-telegram-bot-api/issues/113 + + +* * * + + + +## Frequently Asked Questions + +> Check out [all questions ever asked][questions] on our Github Issues. + +[questions]:https://github.com/yagop/node-telegram-bot-api/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Aquestion%20 + +1. [How do I send GIFs?](#gifs) +1. [Why and When do I need a certificate when using WebHooks?](#webhook-cert) +1. [How do I know when a user leaves a chat?](#leave-chat) +1. [What does this error mean?](#error-meanings) +1. [How do I know the selected option in reply keyboard?](#reply-keyboard) +1. [How do I send multiple message in correct sequence?](#ordered-sending) +1. [How do I run my bot behind a proxy?](#proxy) +1. [Can you add feature X to the library?](#new-feature) +1. [Is this scalable?](#scalable) + + +--- + + +**How do I send GIFs?** + +You might be trying to send your animated GIFs using *TelegramBot#sendPhoto()*. +The method mostly supports static images. As noted by the community, +it seems you need to send them as documents, using *TelegramBot#sendDocument()*. + + +```js +bot.sendDocument(chatId, "cat.gif"); +``` + +Sources: + + * Issue #11: https://github.com/yagop/node-telegram-bot-api/issues/11 + + +--- + + + +**Why and When do I need a certificate when using WebHooks?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #63: https://github.com/yagop/node-telegram-bot-api/issues/63 + * Issue #125: https://github.com/yagop/node-telegram-bot-api/issues/125 + + +--- + + +**How do I know when a user leaves a chat?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #248: https://github.com/yagop/node-telegram-bot-api/issues/248 + + +--- + + + +**What does this error mean?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #73: https://github.com/yagop/node-telegram-bot-api/issues/73 + * Issue #99: https://github.com/yagop/node-telegram-bot-api/issues/99 + * Issue #101: https://github.com/yagop/node-telegram-bot-api/issues/101 + * Issue #107: https://github.com/yagop/node-telegram-bot-api/issues/107 + * Issue #156: https://github.com/yagop/node-telegram-bot-api/issues/156 + * Issue #170: https://github.com/yagop/node-telegram-bot-api/issues/170 + * Issue #244: https://github.com/yagop/node-telegram-bot-api/issues/244 + + +--- + + + +**How do I know the selected option in reply keyboard?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #108: https://github.com/yagop/node-telegram-bot-api/issues/108 + + +--- + + + +**How do I send multiple message in correct sequence?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #240: https://github.com/yagop/node-telegram-bot-api/issues/240 + + +--- + + + +**How do I run my bot behind a proxy?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #122: https://github.com/yagop/node-telegram-bot-api/issues/122 + * Issue #253: https://github.com/yagop/node-telegram-bot-api/issues/253 + + +--- + + + +**Can you add feature X to the library?** + +*Not Done. Send PR please!* + +Sources: + + * Issue #238: https://github.com/yagop/node-telegram-bot-api/issues/238 + + +--- + + +**Is this scalable?** + +*Not Done. Send PR please!* + +--- diff --git a/doc/usage.md b/doc/usage.md new file mode 100644 index 0000000..c2fb4f0 --- /dev/null +++ b/doc/usage.md @@ -0,0 +1,147 @@ +# Usage + +1. [Events](#events) +1. [WebHooks](#WebHooks) +1. [Sending files](#sending-files) + + +* * * + + + +## Events + +*TelegramBot* is an event-emitter that emits the following events: + +1. `message`: Received a new incoming [Message][message] of any kind + 1. Depending on the properties of the [Message][message], one of these + events will **ALSO** be emitted: `text`, `audio`, `document`, `photo`, + `sticker`, `video`, `voice`, `contact`, `location`, + `new_chat_participant`, `left_chat_participant`, `new_chat_title`, + `new_chat_photo`, `delete_chat_photo`, `group_chat_created` +1. `callback_query`: Received a new incoming [Callback Query][callback-query] +1. `inline_query`: Received a new incoming [Inline Query][inline-query] +1. `chosen_inline_result`: Received result of an inline query i.e. [ChosenInlineResult][chosen-inline-result] +1. `channel_post`: Received a new incoming channel post of any kind +1. `edited_message`: Received a new version of a message that is known to the bot and was edited + 1. `edited_message_text` + 1. `edited_message_caption` +1. `edited_channel_post`: Received a new version of a channel post that is known to the bot and was edited + 1. `edited_channel_post_text` + 1. `edited_channel_post_caption` + +**Tip:** Its much better to listen a specific event rather than on +`message` in order to stay safe from the content. + +**Tip:** Bot must be enabled on [inline mode][inline-mode] for receive some +messages. + +[update]:https://core.telegram.org/bots/api#update +[message]:https://core.telegram.org/bots/api#message +[callback-query]:https://core.telegram.org/bots/api#callbackquery +[inline-query]:https://core.telegram.org/bots/api#inlinequery +[chosen-inline-result]:https://core.telegram.org/bots/api#choseninlineresult +[inline-mode]:https://core.telegram.org/bots/api#inline-mode + + +* * * + + + +## WebHooks + +Telegram only supports HTTPS connections to WebHooks. +Therefore, in order to set a WebHook, you will need a SSL certificate. +Since August 29, 2015 Telegram supports self-signed ones, thus, you can +generate them: + +```bash +# Our private cert will be key.pem, keep this file private +$ openssl genrsa -out key.pem 2048 + +# Our public certificate will be crt.pem +$ openssl req -new -sha256 -key key.pem -out crt.pem +``` + +Once they are generated, the `crt.pem` should be uploaded, when setting up +your webhook. For example, + +```js +bot.setWebHook("public-url.com", { + certificate: "path/to/crt.pem", // Path to your crt.pem +}); +``` + +**Note:** If you encounter an error, like +`Error: error:0906D06C:PEM routines:PEM_read_bio:no start line`, +you may want to proceed to [this issue][issue-63] for more information. + +[issue-63]:https://github.com/yagop/node-telegram-bot-api/issues/63 + + +* * * + + + +## Sending files + +The library makes it easy to get started sending files. *By default*, you +may provide a **file-path** and the library will handle reading it for you. +For example, + +```js +bot.sendAudio(chatId, "path/to/audio.mp3"); +``` + +You may also pass in a **Readable Stream** from which data will be piped. +For example, + +```js +const stream = fs.createReadStream("path/to/audio.mp3"); +bot.sendAudio(chatId, stream); +``` + +You may also pass in a **Buffer** containing the contents of your file. +For example, + +```js +const buffer = fs.readFileSync("path/to/audio.mp3"); // sync! that's sad! :-( Just making a point! +bot.sendAudio(chatId, buffer); +``` + +If you already have a **File ID**, you earlier retrieved from Telegram, +you may pass it in, for example: + +```js +const fileId = getFileIdSomehow(); +bot.sendAudio(chatId, fileId); +``` + +Some API methods, such as *SendPhoto*, allow passing a **HTTP URL**, that +the Telegram servers will use to download the file. For example, + +```js +const url = "https://telegram.org/img/t_logo.png"; +bot.sendPhoto(chatId, url); +``` + + +### Performance Issue: + +To support providing file-paths to methods that send files involves +performing a file operation, i.e. *fs.existsSync()*, that checks for +the existence of the file at the provided path. While the cost of +this operation *might* be negligible in most use cases, if you want +to squeeze the best performance out of this library, you may wish to +disable this behavior. + +This will mean that you will **NOT** be able to pass in file-paths. +You will have to use Streams or Buffers to provide the file contents. + +Disabling this behavior: + +```js +const bot = new TelegramBot(token, { + filepath: false, +}); +``` diff --git a/package.json b/package.json index abd92fd..739eff6 100644 --- a/package.json +++ b/package.json @@ -14,7 +14,7 @@ "bot" ], "scripts": { - "gen-doc": "jsdoc2md --files src/telegram.js --template README.hbs > README.md", + "gen-doc": "jsdoc2md --files src/telegram.js --template doc/api.hbs > doc/api.md", "build": "babel -d ./lib src", "prepublish": "npm run build && npm run gen-doc", "eslint": "eslint ./src ./test ./examples", diff --git a/src/telegram.js b/src/telegram.js index 61881da..f454c27 100644 --- a/src/telegram.js +++ b/src/telegram.js @@ -64,7 +64,8 @@ class TelegramBot extends EventEmitter { * See https://github.com/request/request#requestoptions-callback for more information. * @param {String} [options.baseApiUrl=https://api.telegram.org] API Base URl; useful for proxying and testing * @param {Boolean} [options.filepath=true] Allow passing file-paths as arguments when sending files, - * such as photos using `TelegramBot#sendPhoto()`. + * such as photos using `TelegramBot#sendPhoto()`. See [usage information][usage-sending-files-performance] + * for more information on this option and its consequences. * @see https://core.telegram.org/bots/api */ constructor(token, options = {}) { diff --git a/test/README.md b/test/README.md index 72321d3..382e502 100644 --- a/test/README.md +++ b/test/README.md @@ -13,6 +13,10 @@ export TEST_GROUP_ID= # Game short name which to use in some of the tests, e.g. TelegramBot#sendGame() export TEST_GAME_SHORT_NAME= -# Run tests +# Run ALL tests npm run test + +# Run individual tests +npm run eslint # static-analysis +npm run mocha # mocha tests ```