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])
  • .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)

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