Skip to content

Commit

Permalink
v0.27.0
Browse files Browse the repository at this point in the history
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)
  • Loading branch information
GochoMugo committed Feb 10, 2017
2 parents 54212da + b2afdeb commit 7304265
Show file tree
Hide file tree
Showing 19 changed files with 783 additions and 239 deletions.
68 changes: 68 additions & 0 deletions .github/ISSUE_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -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. -->
23 changes: 23 additions & 0 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
@@ -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
-->
43 changes: 42 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
21 changes: 10 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -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)
Expand Down Expand Up @@ -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


Expand All @@ -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


* * *
Expand Down
28 changes: 24 additions & 4 deletions doc/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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 |
Expand Down Expand Up @@ -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>

Expand Down
5 changes: 5 additions & 0 deletions doc/help.md
Original file line number Diff line number Diff line change
Expand Up @@ -172,4 +172,9 @@ Sources:

*Not Done. Send PR please!*

Sources:

* Issue #219: https://github.com/yagop/node-telegram-bot-api/issues/219


---
60 changes: 60 additions & 0 deletions doc/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
1. [Events](#events)
1. [WebHooks](#WebHooks)
1. [Sending files](#sending-files)
1. [Error handling](#error-handling)


* * *
Expand All @@ -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.
Expand Down Expand Up @@ -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'
});
```
35 changes: 35 additions & 0 deletions examples/herokuWebHook.js
Original file line number Diff line number Diff line change
@@ -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!');
});
2 changes: 1 addition & 1 deletion examples/httpsWebHook.js
Original file line number Diff line number Diff line change
Expand Up @@ -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!');
});
Loading

0 comments on commit 7304265

Please sign in to comment.