node-telegram-bot-api-upgrades

Node.js module to interact with official Telegram Bot API. A bot token is needed, to obtain one, talk to @botfather and create a new bot.

npm install node-telegram-bot-api

var TelegramBot = require('node-telegram-bot-api');
 
var token = 'YOUR_TELEGRAM_BOT_TOKEN';
// Setup polling way
var bot = new TelegramBot(token, {polling: true});
 
// Matches /echo [whatever]
bot.onText(/\/echo (.+)/, function (msg, match) {
  var fromId = msg.from.id;
  var resp = match[1];
  bot.sendMessage(fromId, resp);
});
 
// Any kind of message
bot.on('message', function (msg) {
  var chatId = msg.chat.id;
  // photo can be: a file path, a stream or a Telegram file_id
  var photo = 'cats.png';
  bot.sendPhoto(chatId, photo, {caption: 'Lovely kittens'});
});

There are some other examples on examples.

Events

Every time TelegramBot receives a message, it emits a message. Depending on which 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 inline_query when receives an Inline Query and chosen_inline_result when receives a ChosenInlineResult. Bot must be enabled on inline mode

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:

# 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

Kind: global class
See: https://core.telegram.org/bots/api

TelegramBot
- new TelegramBot(token, [options])
- .getMe() ⇒ Promise
- .setWebHook(url, [cert])
- .getUpdates([timeout], [limit], [offset]) ⇒ Promise
- .sendMessage(chatId, text, [options]) ⇒ Promise
- .answerInlineQuery(inlineQueryId, results, [options]) ⇒ Promise
- .forwardMessage(chatId, fromChatId, messageId) ⇒ Promise
- .sendPhoto(chatId, photo, [options]) ⇒ Promise
- .sendAudio(chatId, audio, [options]) ⇒ Promise
- .sendDocument(chatId, doc, [options]) ⇒ Promise
- .sendSticker(chatId, sticker, [options]) ⇒ Promise
- .sendVideo(chatId, video, [options]) ⇒ Promise
- .sendVoice(chatId, voice, [options]) ⇒ Promise
- .sendChatAction(chatId, action) ⇒ Promise
- .getUserProfilePhotos(userId, [offset], [limit]) ⇒ Promise
- .sendLocation(chatId, latitude, longitude, [options]) ⇒ Promise
- .getFile(fileId) ⇒ Promise
- .getFileLink(fileId) ⇒ Promise
- .downloadFile(fileId, downloadDir) ⇒ Promise
- .onText(regexp, callback)
- .onReplyToMessage(chatId, messageId, callback)

new TelegramBot(token, [options])

Both request method to obtain messages are implemented. To use standard polling, set polling: true on options. Notice that webHook 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
[options.polling.timeout]	`String` \| `Number`	`10`	Polling time in seconds
[options.polling.interval]	`String` \| `Number`	`2000`	Interval between requests in miliseconds
[options.webHook]	`Boolean` \| `Object`	`false`	Set true to enable WebHook or set options
[options.webHook.key]	`String`		PEM private key to webHook server.
[options.webHook.cert]	`String`		PEM certificate (public) to webHook server.

telegramBot.getMe() ⇒ `Promise`

Returns basic information about the bot in form of a User object.

Kind: instance method of TelegramBot
See: https://core.telegram.org/bots/api#getme

telegramBot.setWebHook(url, [cert])

Specify an url to receive incoming updates via an outgoing webHook.

Kind: instance method of 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.
[cert]	`String` \| `stream.Stream`	PEM certificate key (public).

telegramBot.getUpdates([timeout], [limit], [offset]) ⇒ `Promise`

Use this method to receive incoming updates using long polling

Kind: instance method of TelegramBot
Returns: Promise - Updates
See: https://core.telegram.org/bots/api#getupdates

Param	Type	Description
[timeout]	`Number` \| `String`	Timeout in seconds for long polling.
[limit]	`Number` \| `String`	Limits the number of updates to be retrieved.
[offset]	`Number` \| `String`	Identifier of the first update to be returned.

telegramBot.sendMessage(chatId, text, [options]) ⇒ `Promise`

Send text message.

Kind: instance method of 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
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) ⇒ `Promise`

Forward messages of any kind.

Kind: instance method of 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

telegramBot.sendPhoto(chatId, photo, [options]) ⇒ `Promise`

Send photo

Kind: instance method of 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
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]) ⇒ `Promise`

Send Document

Kind: instance method of 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

telegramBot.sendSticker(chatId, sticker, [options]) ⇒ `Promise`

Send .webp stickers.

Kind: instance method of 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
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
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
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.getUserProfilePhotos(userId, [offset], [limit]) ⇒ `Promise`

Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object.

Kind: instance method of TelegramBot
See: https://core.telegram.org/bots/api#getuserprofilephotos

Param	Type	Description
userId	`Number` \| `String`	Unique identifier of the target user
[offset]	`Number`	Sequential number of the first photo to be returned. By default, all photos are returned.
[limit]	`Number`	Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100.

telegramBot.sendLocation(chatId, latitude, longitude, [options]) ⇒ `Promise`

Send location. Use this method to send point on the map.

Kind: instance method of 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.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
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
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
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)

Kind: instance method of 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)

Kind: instance method of 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.