mironov-node-telegram-bot-api v0.23.4

(https://img.shields.io/badge/💬 Telegram-nodetelegrambot__api-blue.svg) (https://img.shields.io/badge/💬 Telegram-Yago__Perez-blue.svg)

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

TelegramBot

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

• TelegramBot
  • new TelegramBot(token, [options])
  • .stopPolling() ⇒ Promise
  • .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], [fileOpts]) ⇒ Promise
  • .sendSticker(chatId, sticker, [options]) ⇒ Promise
  • .sendVideo(chatId, video, [options]) ⇒ Promise
  • .sendVoice(chatId, voice, [options]) ⇒ Promise
  • .sendChatAction(chatId, action) ⇒ Promise
  • .kickChatMember(chatId, userId) ⇒ Promise
  • .unbanChatMember(chatId, userId) ⇒ Promise
  • .answerCallbackQuery(callbackQueryId, text, showAlert, [options]) ⇒ Promise
  • .editMessageText(text, [options]) ⇒ Promise
  • .editMessageCaption(caption, [options]) ⇒ Promise
  • .editMessageReplyMarkup(replyMarkup, [options]) ⇒ 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.

telegramBot.stopPolling() ⇒ Promise

Stops polling after the last polling request resolves

Kind: instance method of TelegramBot
Returns: Promise - promise Promise, of last polling request

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

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

telegramBot.sendMessage(chatId, text, options) ⇒ Promise

Send text message.

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

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

telegramBot.forwardMessage(chatId, fromChatId, messageId) ⇒ Promise

Forward messages of any kind.

Kind: instance method of TelegramBot

telegramBot.sendPhoto(chatId, photo, options) ⇒ Promise

Send photo

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

telegramBot.sendAudio(chatId, audio, options) ⇒ Promise

Send audio

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

telegramBot.sendDocument(chatId, doc, options, fileOpts) ⇒ Promise

Send Document

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

telegramBot.sendSticker(chatId, sticker, options) ⇒ Promise

Send .webp stickers.

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

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

telegramBot.sendVoice(chatId, voice, options) ⇒ Promise

Send voice

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

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

telegramBot.kickChatMember(chatId, userId) ⇒ Promise

Use this method to kick a user from a group or a supergroup. In the case of supergroups, the user will not be able to return to the group on their own using invite links, etc., unless unbanned first. The bot must be an administrator in the group for this to work. Returns True on success.

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

telegramBot.unbanChatMember(chatId, userId) ⇒ Promise

Use this method to unban a previously kicked user in a supergroup. The user will not return to the group automatically, but will be able to join via link, etc. The bot must be an administrator in the group for this to work. Returns True on success.

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

telegramBot.answerCallbackQuery(callbackQueryId, text, showAlert, options) ⇒ Promise

Use this method to send answers to callback queries sent from inline keyboards. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert. On success, True is returned.

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

telegramBot.editMessageText(text, options) ⇒ Promise

Use this method to edit text messages sent by the bot or via the bot (for inline bots). On success, the edited Message is returned.

Note that you must provide one of chat_id, message_id, or inline_message_id in your request.

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

telegramBot.editMessageCaption(caption, options) ⇒ Promise

Use this method to edit captions of messages sent by the bot or via the bot (for inline bots). On success, the edited Message is returned.

Note that you must provide one of chat_id, message_id, or inline_message_id in your request.

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

telegramBot.editMessageReplyMarkup(replyMarkup, options) ⇒ Promise

Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots). On success, the edited Message is returned.

Note that you must provide one of chat_id, message_id, or inline_message_id in your request.

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

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

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

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

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

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

telegramBot.onText(regexp, callback)

Register a RegExp to test against an incomming text message.

Kind: instance method of TelegramBot

telegramBot.onReplyToMessage(chatId, messageId, callback)

Register a reply to wait for a message response.

Kind: instance method of TelegramBot