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');

// 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.

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 callback_query when receives a Callback Query. TelegramBot emits inline_query when receives an Inline Query and chosen_inline_result when receives a ChosenInlineResult. Bot must be enabled on 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:

# 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])
  • .initPolling()
  • .stopPolling() ⇒ Promise
  • .isPolling() ⇒ Boolean
  • .openWebHook()
  • .closeWebHook() ⇒ Promise
  • .hasOpenWebHook() ⇒ Boolean
  • .getMe() ⇒ Promise
  • .setWebHook(url, [options])
  • .deleteWebHook() ⇒ Promise
  • .getWebHookInfo() ⇒ Promise
  • .getUpdates([options]) ⇒ Promise
  • .processUpdate(update)
  • .sendMessage(chatId, text, [options]) ⇒ Promise
  • .answerInlineQuery(inlineQueryId, results, [options]) ⇒ Promise
  • .forwardMessage(chatId, fromChatId, messageId, [options]) ⇒ 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, [options]) ⇒ Promise
  • .sendLocation(chatId, latitude, longitude, [options]) ⇒ Promise
  • .sendVenue(chatId, latitude, longitude, title, address, [options]) ⇒ Promise
  • .sendContact(chatId, phoneNumber, firstName, [options]) ⇒ Promise
  • .getFile(fileId) ⇒ Promise
  • .getFileLink(fileId) ⇒ Promise
  • .downloadFile(fileId, downloadDir) ⇒ Promise
  • .onText(regexp, callback)
  • .onReplyToMessage(chatId, messageId, callback)
  • .getChat(chatId) ⇒ Promise
  • .getChatAdministrators(chatId) ⇒ Promise
  • .getChatMembersCount(chatId) ⇒ Promise
  • .getChatMember(chatId, userId) ⇒ Promise
  • .leaveChat(chatId) ⇒ Promise
  • .sendGame(chatId, gameShortName, [options]) ⇒ Promise
  • .setGameScore(userId, score, [options]) ⇒ Promise
  • .getGameHighScores(userId, [options]) ⇒ Promise

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	Timeout in seconds for long polling
[options.polling.interval]	String | Number	300	Interval between requests in miliseconds
[options.polling.autoStart]	Boolean	true	Start polling immediately
[options.webHook]	Boolean | Object	false	Set true to enable WebHook or set options
[options.webHook.port]	Number	8443	Port to bind to
[options.webHook.key]	String		Path to file with PEM private key for webHook server. The file is read synchronously!
[options.webHook.cert]	String		Path to file with PEM certificate (public) for webHook server. The file is read synchronously!
[options.webHook.pfx]	String		Path to file with PFX private key and certificate chain for webHook server. The file is read synchronously!
[options.webHook.autoOpen]	Boolean	true	Open webHook immediately
[options.webHook.https]	Object		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]	Boolean	false	Set to true to stop after first match. Otherwise, all regexps are executed
[options.request]	Object		Options which will be added for all requests to telegram api. See https://github.com/request/request#requestoptions-callback for more information.
[options.baseApiUrl]	String	https://api.telegram.org	API Base URl; useful for proxying and testing

telegramBot.initPolling()

Start polling

Kind: instance method of TelegramBot

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.isPolling() ⇒ Boolean

Return true if polling. Otherwise, false.

Kind: instance method of TelegramBot

telegramBot.openWebHook()

Open webhook

Kind: instance method of TelegramBot

telegramBot.closeWebHook() ⇒ Promise

Close webhook after closing all current connections

Kind: instance method of TelegramBot
Returns: Promise - promise

telegramBot.hasOpenWebHook() ⇒ Boolean

Return true if using webhook and it is open i.e. accepts connections. Otherwise, false.

Kind: instance method of TelegramBot

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, [options])

Specify an url to receive incoming updates via an outgoing webHook. This method has an older, compatible signature that is being deprecated.

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.
[options]	Object	Additional Telegram query options
[options.certificate]	String | stream.Stream	PEM certificate key (public).

telegramBot.deleteWebHook() ⇒ Promise

Use this method to remove webhook integration if you decide to switch back to getUpdates. Returns True on success.

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

telegramBot.getWebHookInfo() ⇒ Promise

Use this method to get current webhook status. On success, returns a WebhookInfo object. If the bot is using getUpdates, will return an object with the url field empty.

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

telegramBot.getUpdates([options]) ⇒ Promise

Use this method to receive incoming updates using long polling. This method has an older, compatible signature that is being deprecated.

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

Param	Type	Description
[options]	Object	Additional Telegram query options

telegramBot.processUpdate(update)

Process an update; emitting the proper events and executing regexp callbacks. This method is useful should you be using a different way to fetch updates, other than those provided by TelegramBot.

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

Param	Type
update	Object

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, [options]) ⇒ 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
[options]	Object	Additional Telegram query options

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], [fileOpts]) ⇒ 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
[fileOpts]	Object	Optional file related meta-data

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.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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup
userId	String	Unique identifier of the target user

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup
userId	String	Unique identifier of the target user

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

Param	Type	Description
callbackQueryId	Number | String	Unique identifier for the query to be answered
text	String	Text of the notification. If not specified, nothing will be shown to the user
showAlert	Boolean	Whether to show an alert or a notification at the top of the screen
[options]	Object	Additional Telegram query options

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

Param	Type	Description
text	String	New text of the message
[options]	Object	Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here)

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

Param	Type	Description
caption	String	New caption of the message
[options]	Object	Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here)

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

Param	Type	Description
replyMarkup	Object	A JSON-serialized object for an inline keyboard.
[options]	Object	Additional Telegram query options (provide either one of chat_id, message_id, or inline_message_id here)

telegramBot.getUserProfilePhotos(userId, [options]) ⇒ Promise

Use this method to get a list of profile pictures for a user. Returns a UserProfilePhotos object. This method has an older, compatible signature that is being deprecated.

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
[options]	Object	Additional Telegram query options

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.sendVenue(chatId, latitude, longitude, title, address, [options]) ⇒ Promise

Send venue. Use this method to send information about a venue.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the message recipient
latitude	Float	Latitude of location
longitude	Float	Longitude of location
title	String	Name of the venue
address	String	Address of the venue
[options]	Object	Additional Telegram query options

telegramBot.sendContact(chatId, phoneNumber, firstName, [options]) ⇒ Promise

Send contact. Use this method to send phone contacts.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the message recipient
phoneNumber	String	Contact's phone number
firstName	String	Contact's first name
[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)

Register a RegExp to test against an incomming text message.

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)

Register a reply to wait for a message response.

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.

telegramBot.getChat(chatId) ⇒ Promise

Use this method to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.).

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target chat or username of the target supergroup or channel

telegramBot.getChatAdministrators(chatId) ⇒ Promise

Returns the administrators in a chat in form of an Array of ChatMember objects.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup

telegramBot.getChatMembersCount(chatId) ⇒ Promise

Use this method to get the number of members in a chat.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup

telegramBot.getChatMember(chatId, userId) ⇒ Promise

Use this method to get information about a member of a chat.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup
userId	String	Unique identifier of the target user

telegramBot.leaveChat(chatId) ⇒ Promise

Leave a group, supergroup or channel.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the target group or username of the target supergroup (in the format @supergroupusername)

telegramBot.sendGame(chatId, gameShortName, [options]) ⇒ Promise

Use this method to send a game.

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

Param	Type	Description
chatId	Number | String	Unique identifier for the message recipient
gameShortName	String	name of the game to be sent.
[options]	Object	Additional Telegram query options

telegramBot.setGameScore(userId, score, [options]) ⇒ Promise

Use this method to set the score of the specified user in a game.

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

Param	Type	Description
userId	String	Unique identifier of the target user
score	Number	New score value.
[options]	Object	Additional Telegram query options

telegramBot.getGameHighScores(userId, [options]) ⇒ Promise

Use this method to get data for high score table.

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

Param	Type	Description
userId	String	Unique identifier of the target user
[options]	Object	Additional Telegram query options

---