v0.27.0

Added:

1. Add constructor options:
  * (#243) `options.polling.params` (by @GochoMugo, requested-by @sidelux)
1. Add methods:
  * (#74) *TelegramBot#removeReplyListener()* (by @githugger)
1. (#283) Add proper error handling (by @GochoMugo)
1. (#272) Add health-check endpoint (by @mironov)
  * `options.webHook.healthEndpoint`
1. (#152) Add test for TelegramBot#sendDocument() using 'fileOpts'
   param (by @evolun)
1. Document `options.webHook.host` (by @GochoMugo)
1. (#264) Add Bot API version to README (by @kamikazechaser)
1. Add examples:
  - (#271) WebHook on Heroku (by @TheBeastOfCaerbannog)
  - (#274) WebHook on Zeit Now (by @ferrari)

Changed:

1. (#147) Use *String#indexOf()*, instead of *RegExp#test()*, to
   find token in webhook request (by @AVVS)

Fixed:

* Fix bug:
  - (#275, #280) fix es6 syntax error on Node.js v4.x (by @CrazyAbdul)
  - (#276) promise.warning from `request-promise` (by @GochoMugo,
    reported-by @preco21)
  - (#281) fix handling error during polling (by @GochoMugo,
    reported-by @dimawebmaker)
  - (#284) fix error during deletion of already-set webhook, during
    polling (by @GochoMugo, reported-by @dcparga)
1. Fix links in documentation (by @Ni2c2k)

Author: GochoMugo

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,68 @@
+<!--
+This template includes two sections:
+1. Bug reporting
+2. Feature request
+3. Question
+
+Please remove whichever section that does not apply to your issue
+-->
+
+
+
+<!--********************************************************************
+Reporting a Bug.
+*********************************************************************-->
+
+> Bug Report
+
+I have read:
+
+* [Usage information](https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md)
+* [Help information](https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md)
+
+I am using the latest version of the library.
+
+### Expected Behavior
+
+<!-- Explain what you are trying to achieve -->
+
+### Actual Behavior
+
+<!-- Explain what happens, contrary to what you expected -->
+
+### Steps to reproduce the Behavior
+
+<!-- Explain how we can reproduce the bug -->
+
+
+
+<!--********************************************************************
+Feature Request.
+*********************************************************************-->
+
+> Feature Request
+
+I have:
+
+* searched for such a feature request (https://github.com/yagop/node-telegram-bot-api/labels/enhancement) and found none
+
+### Introduction
+
+<!-- Describe what value this feature would add, and in which use case,
+or scenario -->
+
+### Example
+
+<!-- A code snippet of how this feature would work, were it already
+implemented -->
+
+
+
+<!--********************************************************************
+Question.
+*********************************************************************-->
+
+> Question
+
+<!-- Ask your question here. Please be precise, adding as much detail
+as necessary. Also, add a code snippet(s) if possible. -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,23 @@
+<!--
+Mark whichever option below applies to this PR.
+For example, if your PR passes all tests, you would mark the option as so:
+- [x] All tests pass
+Note the 'x' in between the square brackets '[]'
+-->
+- [ ] All tests pass
+- [ ] I have run `npm run gen-doc`
+
+### Description
+
+<!-- Explain what you are trying to achieve with this PR -->
+
+### References
+
+<!--
+Add references to other documents/pages that are relevant to this
+PR, such as related issues, documentation, etc.
+
+For example,
+* Issue #1: https://github.com/yagop/node-telegram-bot-api/issues/1
+* Telegram Bot API - Getting updates: https://core.telegram.org/bots/api#getting-updates
+-->

CHANGELOG.md

@@ -7,6 +7,46 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 
 
+
+* * *
+
+## [0.27.0][0.27.0] - 2016-02-10
+
+Added:
+
+1. Add constructor options:
+  * (#243) `options.polling.params` (by @GochoMugo, requested-by @sidelux)
+1. Add methods:
+  * (#74) *TelegramBot#removeReplyListener()* (by @githugger)
+1. (#283) Add proper error handling (by @GochoMugo)
+1. (#272) Add health-check endpoint (by @mironov)
+  * `options.webHook.healthEndpoint`
+1. (#152) Add test for TelegramBot#sendDocument() using 'fileOpts'
+   param (by @evolun)
+1. Document `options.webHook.host` (by @GochoMugo)
+1. (#264) Add Bot API version to README (by @kamikazechaser)
+1. Add examples:
+  - (#271) WebHook on Heroku (by @TheBeastOfCaerbannog)
+  - (#274) WebHook on Zeit Now (by @Ferrari)
+
+Changed:
+
+1. (#147) Use *String#indexOf()*, instead of *RegExp#test()*, to
+   find token in webhook request (by @AVVS)
+
+Fixed:
+
+* Fix bug:
+  - (#275, #280) fix es6 syntax error on Node.js v4.x (by @crazyabdul)
+  - (#276) promise.warning from `request-promise` (by @GochoMugo,
+    reported-by @preco21)
+  - (#281) fix handling error during polling (by @GochoMugo,
+    reported-by @dimawebmaker)
+  - (#284) fix error during deletion of already-set webhook, during
+    polling (by @GochoMugo, reported-by @dcparga)
+1. Fix links in documentation (by @Ni2c2k)
+
+
 * * *
 
 ## [0.26.0][0.26.0] - 2016-01-20
@@ -67,4 +107,5 @@ Fixed:
 
 [0.25.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.25.0
 [0.26.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.26.0
-[Unreleased]:https://github.com/yagop/node-telegram-bot-api/compare/v0.26.0...master
+[0.27.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.27.0
+[Unreleased]:https://github.com/yagop/node-telegram-bot-api/compare/v0.27.0...master

README.md

@@ -1,4 +1,5 @@
-[![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api)
+ [![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-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)
  [![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)
@@ -53,24 +54,21 @@ bot.on('message', function (msg) {
 
 ## Documentation
 
-  * Usage ([release][usage-release] / [development][usage-dev])
-  * Examples ([release][examples-release] / [development][examples-dev])
-  * Help Information ([release][help-release] / [development][help-dev])
+  * [Usage][usage]
+  * [Examples][examples]
+  * [Help Information][help]
   * 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
+[usage]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md
+[examples]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples
+[help]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md
 [api-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/api.md
+[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md
 [contributing]:https://github.com/yagop/node-telegram-bot-api/tree/master/CONTRIBUTING.md
 
 
@@ -86,6 +84,7 @@ 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
+* [teleirc](https://github.com/FruitieX/teleirc): A simple Telegram ↔ IRC gateway
 
 
 * * *

doc/api.md

@@ -47,7 +47,8 @@ TelegramBot
     * [.getFileLink(fileId)](#TelegramBot+getFileLink) ⇒ <code>Promise</code>
     * [.downloadFile(fileId, downloadDir)](#TelegramBot+downloadFile) ⇒ <code>Promise</code>
     * [.onText(regexp, callback)](#TelegramBot+onText)
-    * [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage)
+    * [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage) ⇒ <code>Number</code>
+    * [.removeReplyListener(replyListenerId)](#TelegramBot+removeReplyListener) ⇒ <code>Object</code>
     * [.getChat(chatId)](#TelegramBot+getChat) ⇒ <code>Promise</code>
     * [.getChatAdministrators(chatId)](#TelegramBot+getChatAdministrators) ⇒ <code>Promise</code>
     * [.getChatMembersCount(chatId)](#TelegramBot+getChatMembersCount) ⇒ <code>Promise</code>
@@ -70,16 +71,20 @@ Emits `message` when a message arrives.
 | token | <code>String</code> |  | Bot Token |
 | [options] | <code>Object</code> |  |  |
 | [options.polling] | <code>Boolean</code> &#124; <code>Object</code> | <code>false</code> | Set true to enable polling or set options.  If a WebHook has been set, it will be deleted automatically. |
-| [options.polling.timeout] | <code>String</code> &#124; <code>Number</code> | <code>10</code> | Timeout in seconds for long polling |
+| [options.polling.timeout] | <code>String</code> &#124; <code>Number</code> | <code>10</code> | *Deprecated. Use `options.polling.params` instead*.  Timeout in seconds for long polling. |
 | [options.polling.interval] | <code>String</code> &#124; <code>Number</code> | <code>300</code> | Interval between requests in miliseconds |
 | [options.polling.autoStart] | <code>Boolean</code> | <code>true</code> | Start polling immediately |
+| [options.polling.params] | <code>Object</code> |  | Parameters to be used in polling API requests.  See https://core.telegram.org/bots/api#getupdates for more information. |
+| [options.polling.params.timeout] | <code>Number</code> | <code>10</code> | Timeout in seconds for long polling. |
 | [options.webHook] | <code>Boolean</code> &#124; <code>Object</code> | <code>false</code> | Set true to enable WebHook or set options |
+| [options.webHook.host] | <code>String</code> | <code>0.0.0.0</code> | Host to bind to |
 | [options.webHook.port] | <code>Number</code> | <code>8443</code> | Port to bind to |
 | [options.webHook.key] | <code>String</code> |  | Path to file with PEM private key for webHook server.  The file is read **synchronously**! |
 | [options.webHook.cert] | <code>String</code> |  | Path to file with PEM certificate (public) for webHook server.  The file is read **synchronously**! |
 | [options.webHook.pfx] | <code>String</code> |  | Path to file with PFX private key and certificate chain for webHook server.  The file is read **synchronously**! |
 | [options.webHook.autoOpen] | <code>Boolean</code> | <code>true</code> | Open webHook immediately |
 | [options.webHook.https] | <code>Object</code> |  | 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.webHook.healthEndpoint] | <code>String</code> | <code>/healthz</code> | An endpoint for health checks that always responds with 200 OK |
 | [options.onlyFirstMatch] | <code>Boolean</code> | <code>false</code> | Set to true to stop after first match. Otherwise, all regexps are executed |
 | [options.request] | <code>Object</code> |  | Options which will be added for all requests to telegram api.  See https://github.com/request/request#requestoptions-callback for more information. |
 | [options.baseApiUrl] | <code>String</code> | <code>https://api.telegram.org</code> | API Base URl; useful for proxying and testing |
@@ -592,16 +597,31 @@ Register a RegExp to test against an incomming text message.
 
 <a name="TelegramBot+onReplyToMessage"></a>
 
-### telegramBot.onReplyToMessage(chatId, messageId, callback)
+### telegramBot.onReplyToMessage(chatId, messageId, callback) ⇒ <code>Number</code>
 Register a reply to wait for a message response.
 
 **Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**Returns**: <code>Number</code> - id                    The ID of the inserted reply listener.  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | chatId | <code>Number</code> &#124; <code>String</code> | The chat id where the message cames from. |
 | messageId | <code>Number</code> &#124; <code>String</code> | The message id to be replied. |
-| callback | <code>function</code> | Callback will be called with the reply message. |
+| callback | <code>function</code> | Callback will be called with the reply  message. |
+
+<a name="TelegramBot+removeReplyListener"></a>
+
+### telegramBot.removeReplyListener(replyListenerId) ⇒ <code>Object</code>
+Removes a reply that has been prev. registered for a message response.
+
+**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>  
+**Returns**: <code>Object</code> - deletedListener      The removed reply listener if
+  found. This object has `id`, `chatId`, `messageId` and `callback`
+  properties. If not found, returns `null`.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| replyListenerId | <code>Number</code> | The ID of the reply listener. |
 
 <a name="TelegramBot+getChat"></a>
 

doc/help.md

@@ -172,4 +172,9 @@ Sources:
 
 *Not Done. Send PR please!*
 
+Sources:
+
+  * Issue #219: https://github.com/yagop/node-telegram-bot-api/issues/219
+
+
 ---

doc/usage.md

@@ -3,6 +3,7 @@
 1. [Events](#events)
 1. [WebHooks](#WebHooks)
 1. [Sending files](#sending-files)
+1. [Error handling](#error-handling)
 
 
 * * *
@@ -29,6 +30,8 @@
 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`
+1. `polling_error`: Error occurred during polling. See [polling errors](#polling-errors).
+1. `webhook_error`: Error occurred handling a webhook request. See [webhook errors](#webhook-errors).
 
 **Tip:** Its much better to listen a specific event rather than on
 `message` in order to stay safe from the content.
@@ -145,3 +148,60 @@ const bot = new TelegramBot(token, {
   filepath: false,
 });
 ```
+
+
+<a name="error-handling"></a>
+## Error handling
+
+Every `Error` object we pass back has the properties:
+
+* `code` (String):
+  * value is `EFATAL` if error was fatal e.g. network error
+  * value is `EPARSE` if response body could **not** be parsed
+  * value is `ETELEGRAM` if error was returned from Telegram servers
+* `response` ([http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)):
+  * available if `error.code` is **not** `EFATAL`
+* `response.body` (String|Object): Error response from Telegram
+  * type is `String` if `error.code` is `EPARSE`
+  * type is `Object` if `error.code` is `ETELEGRAM`
+
+For example, sending message to a non-existent user:
+
+```js
+bot.sendMessage(nonExistentUserId, 'text').catch(error => {
+  console.log(error.code);  // => 'ETELEGRAM'
+  console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' }
+});
+```
+
+<a name="polling-errors"></a>
+#### Polling errors
+
+An error may occur during polling. It is up to you to handle it
+as you see fit. You may decide to crash your bot after a maximum number
+of polling errors occurring. **It is all up to you.**
+
+By default, the polling error is just logged to stderr, if you do
+**not** handle this event yourself.
+
+Listen on the `'polling_error'` event. For example,
+
+```js
+bot.on('polling_error', (error) => {
+  console.log(error.code);  // => 'EFATAL'
+});
+```
+
+<a name="webhook-errors"></a>
+#### WebHook errors
+
+Just like with [polling errors](#polling-errors), you decide on how to
+handle it. By default, the error is logged to stderr.
+
+Listen on the `'webhook_error'` event. For example,
+
+```js
+bot.on('webhook_error', (error) => {
+  console.log(error.code);  // => 'EPARSE'
+});
+```

examples/herokuWebHook.js

@@ -0,0 +1,35 @@
+/**
+ * This example demonstrates setting up webhook
+ * on the Heroku platform.
+ */
+
+
+const TOKEN = process.env.TELEGRAM_TOKEN || 'YOUR_TELEGRAM_BOT_TOKEN';
+const TelegramBot = require('..');
+const options = {
+  webHook: {
+    // Port to which you should bind is assigned to $PORT variable
+    // See: https://devcenter.heroku.com/articles/dynos#local-environment-variables
+    port: process.env.PORT
+    // you do NOT need to set up certificates since Heroku provides
+    // the SSL certs already (https://<app-name>.herokuapp.com)
+    // Also no need to pass IP because on Heroku you need to bind to 0.0.0.0
+  }
+};
+// Heroku routes from port :443 to $PORT
+// Add URL of your app to env variable or enable Dyno Metadata
+// to get this automatically
+// See: https://devcenter.heroku.com/articles/dyno-metadata
+const url = process.env.APP_URL || 'https://<app-name>.herokuapp.com:443';
+const bot = new TelegramBot(TOKEN, options);
+
+
+// This informs the Telegram servers of the new webhook.
+// Note: we do not need to pass in the cert, as it already provided
+bot.setWebHook(`${url}/bot${TOKEN}`);
+
+
+// Just to ping!
+bot.on('message', function onMessage(msg) {
+  bot.sendMessage(msg.chat.id, 'I am alive on Heroku!');
+});

examples/httpsWebHook.js

@@ -26,5 +26,5 @@ bot.setWebHook(`${url}/bot${TOKEN}`, {
 
 // Just to ping!
 bot.on('message', function onMessage(msg) {
-  bot.sendMessage(msg.chat.id, "I'm alive!");
+  bot.sendMessage(msg.chat.id, 'I am alive!');
 });