Skip to content

Commit 7304265

Browse files
GochoMugoGochoMugo
committed
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)
2 parents 54212da + b2afdeb commit 7304265

19 files changed

+783
-239
lines changed

‎.github/ISSUE_TEMPLATE.md

+68
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
<!--
2+
This template includes two sections:
3+
1. Bug reporting
4+
2. Feature request
5+
3. Question
6+
7+
Please remove whichever section that does not apply to your issue
8+
-->
9+
10+
11+
12+
<!--********************************************************************
13+
Reporting a Bug.
14+
*********************************************************************-->
15+
16+
> Bug Report
17+
18+
I have read:
19+
20+
* [Usage information](https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md)
21+
* [Help information](https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md)
22+
23+
I am using the latest version of the library.
24+
25+
### Expected Behavior
26+
27+
<!-- Explain what you are trying to achieve -->
28+
29+
### Actual Behavior
30+
31+
<!-- Explain what happens, contrary to what you expected -->
32+
33+
### Steps to reproduce the Behavior
34+
35+
<!-- Explain how we can reproduce the bug -->
36+
37+
38+
39+
<!--********************************************************************
40+
Feature Request.
41+
*********************************************************************-->
42+
43+
> Feature Request
44+
45+
I have:
46+
47+
* searched for such a feature request (https://github.com/yagop/node-telegram-bot-api/labels/enhancement) and found none
48+
49+
### Introduction
50+
51+
<!-- Describe what value this feature would add, and in which use case,
52+
or scenario -->
53+
54+
### Example
55+
56+
<!-- A code snippet of how this feature would work, were it already
57+
implemented -->
58+
59+
60+
61+
<!--********************************************************************
62+
Question.
63+
*********************************************************************-->
64+
65+
> Question
66+
67+
<!-- Ask your question here. Please be precise, adding as much detail
68+
as necessary. Also, add a code snippet(s) if possible. -->

‎.github/PULL_REQUEST_TEMPLATE.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
<!--
2+
Mark whichever option below applies to this PR.
3+
For example, if your PR passes all tests, you would mark the option as so:
4+
- [x] All tests pass
5+
Note the 'x' in between the square brackets '[]'
6+
-->
7+
- [ ] All tests pass
8+
- [ ] I have run `npm run gen-doc`
9+
10+
### Description
11+
12+
<!-- Explain what you are trying to achieve with this PR -->
13+
14+
### References
15+
16+
<!--
17+
Add references to other documents/pages that are relevant to this
18+
PR, such as related issues, documentation, etc.
19+
20+
For example,
21+
* Issue #1: https://github.com/yagop/node-telegram-bot-api/issues/1
22+
* Telegram Bot API - Getting updates: https://core.telegram.org/bots/api#getting-updates
23+
-->

‎CHANGELOG.md

+42-1
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,46 @@ This project adheres to [Semantic Versioning](http://semver.org/).
77

88

99

10+
11+
* * *
12+
13+
## [0.27.0][0.27.0] - 2016-02-10
14+
15+
Added:
16+
17+
1. Add constructor options:
18+
* (#243) `options.polling.params` (by @GochoMugo, requested-by @sidelux)
19+
1. Add methods:
20+
* (#74) *TelegramBot#removeReplyListener()* (by @githugger)
21+
1. (#283) Add proper error handling (by @GochoMugo)
22+
1. (#272) Add health-check endpoint (by @mironov)
23+
* `options.webHook.healthEndpoint`
24+
1. (#152) Add test for TelegramBot#sendDocument() using 'fileOpts'
25+
param (by @evolun)
26+
1. Document `options.webHook.host` (by @GochoMugo)
27+
1. (#264) Add Bot API version to README (by @kamikazechaser)
28+
1. Add examples:
29+
- (#271) WebHook on Heroku (by @TheBeastOfCaerbannog)
30+
- (#274) WebHook on Zeit Now (by @Ferrari)
31+
32+
Changed:
33+
34+
1. (#147) Use *String#indexOf()*, instead of *RegExp#test()*, to
35+
find token in webhook request (by @AVVS)
36+
37+
Fixed:
38+
39+
* Fix bug:
40+
- (#275, #280) fix es6 syntax error on Node.js v4.x (by @crazyabdul)
41+
- (#276) promise.warning from `request-promise` (by @GochoMugo,
42+
reported-by @preco21)
43+
- (#281) fix handling error during polling (by @GochoMugo,
44+
reported-by @dimawebmaker)
45+
- (#284) fix error during deletion of already-set webhook, during
46+
polling (by @GochoMugo, reported-by @dcparga)
47+
1. Fix links in documentation (by @Ni2c2k)
48+
49+
1050
* * *
1151

1252
## [0.26.0][0.26.0] - 2016-01-20
@@ -67,4 +107,5 @@ Fixed:
67107

68108
[0.25.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.25.0
69109
[0.26.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.26.0
70-
[Unreleased]:https://github.com/yagop/node-telegram-bot-api/compare/v0.26.0...master
110+
[0.27.0]:https://github.com/yagop/node-telegram-bot-api/releases/tag/v0.27.0
111+
[Unreleased]:https://github.com/yagop/node-telegram-bot-api/compare/v0.27.0...master

‎README.md

+10-11
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
[![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api)
1+
[![Bot API](http://img.shields.io/badge/Bot API-v2.3.1-00aced.svg)](https://core.telegram.org/bots/api)
2+
[![Build Status](https://travis-ci.org/yagop/node-telegram-bot-api.svg?branch=master)](https://travis-ci.org/yagop/node-telegram-bot-api)
23
[![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)
34
[![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)
45
[![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) {
5354

5455
## Documentation
5556

56-
* Usage ([release][usage-release] / [development][usage-dev])
57-
* Examples ([release][examples-release] / [development][examples-dev])
58-
* Help Information ([release][help-release] / [development][help-dev])
57+
* [Usage][usage]
58+
* [Examples][examples]
59+
* [Help Information][help]
5960
* API Reference ([release][api-release] / [development][api-dev])
6061
* [Contributing to the Project][contributing]
6162

6263
_**Note**: Development is done against the **master** branch. Code for the latest release
6364
resides on the **release** branch._
6465

65-
[usage-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/usage.md
66-
[examples-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/help.md
67-
[help-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/examples
68-
[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md
6966

70-
[usage-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md
71-
[examples-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md
72-
[help-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples
67+
[usage]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/usage.md
68+
[examples]:https://github.com/yagop/node-telegram-bot-api/tree/master/examples
69+
[help]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/help.md
7370
[api-dev]:https://github.com/yagop/node-telegram-bot-api/tree/master/doc/api.md
71+
[api-release]:https://github.com/yagop/node-telegram-bot-api/tree/release/doc/api.md
7472
[contributing]:https://github.com/yagop/node-telegram-bot-api/tree/master/CONTRIBUTING.md
7573

7674

@@ -86,6 +84,7 @@ Some things built using this library, and might interest you:
8684

8785
* [tgfancy](https://github.com/GochoMugo/tgfancy): A Fancy, Higher-Level Wrapper for Telegram Bot API
8886
* [node-telegram-bot-api-middleware](https://github.com/idchlife/node-telegram-bot-api-middleware): Middleware for node-telegram-bot-api
87+
* [teleirc](https://github.com/FruitieX/teleirc): A simple Telegram ↔ IRC gateway
8988

9089

9190
* * *

‎doc/api.md

+24-4
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,8 @@ TelegramBot
4747
* [.getFileLink(fileId)](#TelegramBot+getFileLink) ⇒ <code>Promise</code>
4848
* [.downloadFile(fileId, downloadDir)](#TelegramBot+downloadFile) ⇒ <code>Promise</code>
4949
* [.onText(regexp, callback)](#TelegramBot+onText)
50-
* [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage)
50+
* [.onReplyToMessage(chatId, messageId, callback)](#TelegramBot+onReplyToMessage) ⇒ <code>Number</code>
51+
* [.removeReplyListener(replyListenerId)](#TelegramBot+removeReplyListener) ⇒ <code>Object</code>
5152
* [.getChat(chatId)](#TelegramBot+getChat) ⇒ <code>Promise</code>
5253
* [.getChatAdministrators(chatId)](#TelegramBot+getChatAdministrators) ⇒ <code>Promise</code>
5354
* [.getChatMembersCount(chatId)](#TelegramBot+getChatMembersCount) ⇒ <code>Promise</code>
@@ -70,16 +71,20 @@ Emits `message` when a message arrives.
7071
| token | <code>String</code> | | Bot Token |
7172
| [options] | <code>Object</code> | | |
7273
| [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. |
73-
| [options.polling.timeout] | <code>String</code> &#124; <code>Number</code> | <code>10</code> | Timeout in seconds for long polling |
74+
| [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. |
7475
| [options.polling.interval] | <code>String</code> &#124; <code>Number</code> | <code>300</code> | Interval between requests in miliseconds |
7576
| [options.polling.autoStart] | <code>Boolean</code> | <code>true</code> | Start polling immediately |
77+
| [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. |
78+
| [options.polling.params.timeout] | <code>Number</code> | <code>10</code> | Timeout in seconds for long polling. |
7679
| [options.webHook] | <code>Boolean</code> &#124; <code>Object</code> | <code>false</code> | Set true to enable WebHook or set options |
80+
| [options.webHook.host] | <code>String</code> | <code>0.0.0.0</code> | Host to bind to |
7781
| [options.webHook.port] | <code>Number</code> | <code>8443</code> | Port to bind to |
7882
| [options.webHook.key] | <code>String</code> | | Path to file with PEM private key for webHook server. The file is read **synchronously**! |
7983
| [options.webHook.cert] | <code>String</code> | | Path to file with PEM certificate (public) for webHook server. The file is read **synchronously**! |
8084
| [options.webHook.pfx] | <code>String</code> | | Path to file with PFX private key and certificate chain for webHook server. The file is read **synchronously**! |
8185
| [options.webHook.autoOpen] | <code>Boolean</code> | <code>true</code> | Open webHook immediately |
8286
| [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. |
87+
| [options.webHook.healthEndpoint] | <code>String</code> | <code>/healthz</code> | An endpoint for health checks that always responds with 200 OK |
8388
| [options.onlyFirstMatch] | <code>Boolean</code> | <code>false</code> | Set to true to stop after first match. Otherwise, all regexps are executed |
8489
| [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. |
8590
| [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.
592597

593598
<a name="TelegramBot+onReplyToMessage"></a>
594599

595-
### telegramBot.onReplyToMessage(chatId, messageId, callback)
600+
### telegramBot.onReplyToMessage(chatId, messageId, callback) ⇒ <code>Number</code>
596601
Register a reply to wait for a message response.
597602

598603
**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>
604+
**Returns**: <code>Number</code> - id The ID of the inserted reply listener.
599605

600606
| Param | Type | Description |
601607
| --- | --- | --- |
602608
| chatId | <code>Number</code> &#124; <code>String</code> | The chat id where the message cames from. |
603609
| messageId | <code>Number</code> &#124; <code>String</code> | The message id to be replied. |
604-
| callback | <code>function</code> | Callback will be called with the reply message. |
610+
| callback | <code>function</code> | Callback will be called with the reply message. |
611+
612+
<a name="TelegramBot+removeReplyListener"></a>
613+
614+
### telegramBot.removeReplyListener(replyListenerId) ⇒ <code>Object</code>
615+
Removes a reply that has been prev. registered for a message response.
616+
617+
**Kind**: instance method of <code>[TelegramBot](#TelegramBot)</code>
618+
**Returns**: <code>Object</code> - deletedListener The removed reply listener if
619+
found. This object has `id`, `chatId`, `messageId` and `callback`
620+
properties. If not found, returns `null`.
621+
622+
| Param | Type | Description |
623+
| --- | --- | --- |
624+
| replyListenerId | <code>Number</code> | The ID of the reply listener. |
605625

606626
<a name="TelegramBot+getChat"></a>
607627

‎doc/help.md

+5
Original file line numberDiff line numberDiff line change
@@ -172,4 +172,9 @@ Sources:
172172

173173
*Not Done. Send PR please!*
174174

175+
Sources:
176+
177+
* Issue #219: https://github.com/yagop/node-telegram-bot-api/issues/219
178+
179+
175180
---

‎doc/usage.md

+60
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
1. [Events](#events)
44
1. [WebHooks](#WebHooks)
55
1. [Sending files](#sending-files)
6+
1. [Error handling](#error-handling)
67

78

89
* * *
@@ -29,6 +30,8 @@
2930
1. `edited_channel_post`: Received a new version of a channel post that is known to the bot and was edited
3031
1. `edited_channel_post_text`
3132
1. `edited_channel_post_caption`
33+
1. `polling_error`: Error occurred during polling. See [polling errors](#polling-errors).
34+
1. `webhook_error`: Error occurred handling a webhook request. See [webhook errors](#webhook-errors).
3235

3336
**Tip:** Its much better to listen a specific event rather than on
3437
`message` in order to stay safe from the content.
@@ -145,3 +148,60 @@ const bot = new TelegramBot(token, {
145148
filepath: false,
146149
});
147150
```
151+
152+
153+
<a name="error-handling"></a>
154+
## Error handling
155+
156+
Every `Error` object we pass back has the properties:
157+
158+
* `code` (String):
159+
* value is `EFATAL` if error was fatal e.g. network error
160+
* value is `EPARSE` if response body could **not** be parsed
161+
* value is `ETELEGRAM` if error was returned from Telegram servers
162+
* `response` ([http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage)):
163+
* available if `error.code` is **not** `EFATAL`
164+
* `response.body` (String|Object): Error response from Telegram
165+
* type is `String` if `error.code` is `EPARSE`
166+
* type is `Object` if `error.code` is `ETELEGRAM`
167+
168+
For example, sending message to a non-existent user:
169+
170+
```js
171+
bot.sendMessage(nonExistentUserId, 'text').catch(error => {
172+
console.log(error.code); // => 'ETELEGRAM'
173+
console.log(error.response.body); // => { ok: false, error_code: 400, description: 'Bad Request: chat not found' }
174+
});
175+
```
176+
177+
<a name="polling-errors"></a>
178+
#### Polling errors
179+
180+
An error may occur during polling. It is up to you to handle it
181+
as you see fit. You may decide to crash your bot after a maximum number
182+
of polling errors occurring. **It is all up to you.**
183+
184+
By default, the polling error is just logged to stderr, if you do
185+
**not** handle this event yourself.
186+
187+
Listen on the `'polling_error'` event. For example,
188+
189+
```js
190+
bot.on('polling_error', (error) => {
191+
console.log(error.code); // => 'EFATAL'
192+
});
193+
```
194+
195+
<a name="webhook-errors"></a>
196+
#### WebHook errors
197+
198+
Just like with [polling errors](#polling-errors), you decide on how to
199+
handle it. By default, the error is logged to stderr.
200+
201+
Listen on the `'webhook_error'` event. For example,
202+
203+
```js
204+
bot.on('webhook_error', (error) => {
205+
console.log(error.code); // => 'EPARSE'
206+
});
207+
```

‎examples/herokuWebHook.js

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
/**
2+
* This example demonstrates setting up webhook
3+
* on the Heroku platform.
4+
*/
5+
6+
7+
const TOKEN = process.env.TELEGRAM_TOKEN || 'YOUR_TELEGRAM_BOT_TOKEN';
8+
const TelegramBot = require('..');
9+
const options = {
10+
webHook: {
11+
// Port to which you should bind is assigned to $PORT variable
12+
// See: https://devcenter.heroku.com/articles/dynos#local-environment-variables
13+
port: process.env.PORT
14+
// you do NOT need to set up certificates since Heroku provides
15+
// the SSL certs already (https://<app-name>.herokuapp.com)
16+
// Also no need to pass IP because on Heroku you need to bind to 0.0.0.0
17+
}
18+
};
19+
// Heroku routes from port :443 to $PORT
20+
// Add URL of your app to env variable or enable Dyno Metadata
21+
// to get this automatically
22+
// See: https://devcenter.heroku.com/articles/dyno-metadata
23+
const url = process.env.APP_URL || 'https://<app-name>.herokuapp.com:443';
24+
const bot = new TelegramBot(TOKEN, options);
25+
26+
27+
// This informs the Telegram servers of the new webhook.
28+
// Note: we do not need to pass in the cert, as it already provided
29+
bot.setWebHook(`${url}/bot${TOKEN}`);
30+
31+
32+
// Just to ping!
33+
bot.on('message', function onMessage(msg) {
34+
bot.sendMessage(msg.chat.id, 'I am alive on Heroku!');
35+
});

‎examples/httpsWebHook.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -26,5 +26,5 @@ bot.setWebHook(`${url}/bot${TOKEN}`, {
2626

2727
// Just to ping!
2828
bot.on('message', function onMessage(msg) {
29-
bot.sendMessage(msg.chat.id, "I'm alive!");
29+
bot.sendMessage(msg.chat.id, 'I am alive!');
3030
});

0 commit comments

Comments
 (0)