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.
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.
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 | <code>String</code> | | Bot Token |
| [options] | <code>Object</code> | | |
| [options.polling] | <code>Boolean</code>|<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>|<code>Number</code> | <code>10</code> | Timeout in seconds for long polling |
| [options.polling.interval] | <code>String</code>|<code>Number</code> | <code>300</code> | Interval between requests in miliseconds |
| [options.webHook] | <code>Boolean</code>|<code>Object</code> | <code>false</code> | Set true to enable WebHook or set options |
| [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.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.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 |
| [options.filepath] | <code>Boolean</code> | <code>true</code> | Allow passing file-paths as arguments when sending files, such as photos using `TelegramBot#sendPhoto()`. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| photo | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path or a Stream. Can also be a `file_id` previously uploaded |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| audio | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| doc | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| sticker | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. Stickers are WebP format files. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| video | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path or Stream. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| voice | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the target group or username of the target supergroup (in the format @supergroupusername) |
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 | <code>String</code> | | Bot Token |
| [options] | <code>Object</code> | | |
| [options.polling] | <code>Boolean</code>|<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>|<code>Number</code> | <code>10</code> | Timeout in seconds for long polling |
| [options.polling.interval] | <code>String</code>|<code>Number</code> | <code>300</code> | Interval between requests in miliseconds |
| [options.webHook] | <code>Boolean</code>|<code>Object</code> | <code>false</code> | Set true to enable WebHook or set options |
| [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.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.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 |
| [options.filepath] | <code>Boolean</code> | <code>true</code> | 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. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| photo | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path or a Stream. Can also be a `file_id` previously uploaded |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| audio | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| doc | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| sticker | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. Stickers are WebP format files. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| video | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path or Stream. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the message recipient |
| voice | <code>String</code>|<code>stream.Stream</code>|<code>Buffer</code> | A file path, Stream or Buffer. Can also be a `file_id` previously uploaded. |
| chatId | <code>Number</code>|<code>String</code> | Unique identifier for the target group or username of the target supergroup (in the format @supergroupusername) |
GochoMugo
9 years ago