/node-telegram-bot-api

Telegram Bot API for NodeJS

Primary LanguageJavaScriptMIT LicenseMIT

This is an almost up-to-date fork of the source repo. The open PRs at yagop/node-telegram-bot-api are drafted periodically against this repo, with the intention of merging them in, as fast as possible. This allows us to try out most of the fixes and features, before they are published in the official releases.

Do not draft any pull-request against this repo. It is NOT a replacement of the source/original repo.

This is intended to be used for development purposes (in production, you are on your own), as we wait for @yagop to get some time and merge the open PRs. Before using this fork, please ensure you understand that I am NOT assuring you that all the PRs will be merged in the source repo. This is for advanced users, who just can not wait for some of the cool PRs to be merged to start using them asap.

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.

From Github:

$ npm install GochoMugo/node-telegram-bot-api

From npm:

$ npm install node-telegram-bot-api-latest    # note the '-latest' suffix

Note: If you use npm, you'll have to require("node-telegram-bot-api-latest") (note the -latest suffix) instead, since it is a different package. Otherwise, keep using require("node-telegram-bot-api") as if it is the original package.

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. It's much better to listen a specific event rather than a message in order to stay safe from the content. TelegramBot also 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. If inline mode is enabled, it will emit inline_query when it receives an Inline Query and chosen_inline_result when it receives a ChosenInlineResult.

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

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.
[options.request] Object Options which will be added for all requests to telegram api.

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

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], [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, [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.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, phone_number, first_name, [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
phone_number String Contact's phone number
first_name 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

Returns information about the chat in form of a Chat object.

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

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

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

Returns the number of members in a chat in form of an Int object.

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

Returns information about a member of a chat in form of a ChatMember object.

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)