Telegram Bot API

Class: Bot

Bot

new Bot(token, opts)

A JavaScript interface for using the Telegram Bot API

This module also exports a paramTypes variable. See global.html#paramTypes

Parameters:
Name Type Description
token String

Your bot's token. More information: (https://core.telegram.org/bots/api#authorizing-your-bot)[https://core.telegram.org/bots/api#authorizing-your-bot]
opts Object

(Optional) Extra options to pass to this bot instance. Available options include:

  • url The base URL for API requests, including {token} for where the token should go (default: "https://api.telegram.org/bot{token}")
  • fileUrl The base URL for file downloads, including {token} (default: "https://api.telegram.org/file/bot{token}")
  • longPollTimeout Request timeout in seconds when long-polling; set to 0 for short-polling (default: 60)
  • listenerTimeout Timeout in seconds when the next listener will automatically be called if the previous one has not called next() or done() (default: 10)
  • ignorePrestartUpdates If set, updates dated earlier than when the bot started will be ignored (default: true)

Methods

answerInlineQuery(inlineQueryId, results, params)

Sends a reply to an inline query

More info: https://core.telegram.org/bots/api#inline-mode

Parameters:
Name Type Description
inlineQueryId Number

ID of the inline query to reply to
results Array

Array of InlineQueryResult (see link above)
params Object

Optional extra parameters
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

apiPostRequest(method, formData)

Sends a POST API request to the specified method

Parameters:
Name Type Description
method String

Method to call
formData Object

Form data to send along with the request
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

apiRequest(method, params)

Sends a GET API request to the specified method

Parameters:
Name Type Description
method String

Method to call
params Object

Query parameters of the request
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

forwardMessage(chatId, fromChatId, messageId)

Forwards the specified message ID

More info: https://core.telegram.org/bots/api#forwardmessage

Parameters:
Name Type Description
chatId Number

ID of the target chat
fromChatId Number

ID of the original chat
messageId Number

ID of the message to forward
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

getFile(fileId)

Returns information about the specified file ID

More info: https://core.telegram.org/bots/api#getfile

Parameters:
Name Type Description
fileId Number

ID of the file
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

getFileURL(filePath)

Returns the URL to the specified file. This URL is valid for at least 1 hour.

More info: https://core.telegram.org/bots/api#getfile

Parameters:
Name Type Description
filePath String

The file path, as returned by getFile
Returns:

The file's URL

Type
String

getMe()

Returns information about the bot user

Note: this is already available via the info class property

More info: https://core.telegram.org/bots/api#getme

Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

getUserProfilePhotos(userId)

Returns a list of profile photos for the specified user

More info: https://core.telegram.org/bots/api#getuserprofilephotos

Parameters:
Name Type Description
userId Number

ID of the user
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

on(event, cb)

Attaches an event listener for the specified event type

Parameters:
Name Type Description
event String

Type of event
cb function

Callback to call when the event fires
Returns:
Type
void

onCommand(triggerSymbol, cmd, params, cb)

Attach an event listener to when a text message with a matching command is received

This function accepts a variable number of arguments: (cmd, cb) (cmd, params, cb) (triggerSymbol, cmd, params, cb)

Parameters:
Name Type Description
triggerSymbol String

String to prefix the command with; defaults to '/'
cmd String

Command to match, WITHOUT the leading triggerSymbol (e.g. '/'); can use regex
params Array

Parameters the command accepts. Parameters can either be regex strings or the following array construct:

[name, regexString, options]

Where name and regexString are strings and options is an optional object. Available options:

  • optional Whether the parameter is optional or not; defaults to false
  • stripQuotes Whether to strip wrapping quotes from parameters; defaults to true

Parameters are matched as both triggerSymbol+cmd and triggerSymbol+cmd@botUsername. For example, both of these will match: /getLocation London or /getLocation@myBot London

The matched command can always be accessed via params._cmd (especially useful with dynamic commands)
cb function

Listener to call when the command matches
Returns:
Type
void

sendAction(chatId, action)

Sends a chat action to the specified chat

More info: https://core.telegram.org/bots/api#sendchataction

Parameters:
Name Type Description
chatId Number

ID of the target chat
action String

Type of action to send
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendAudio(chatId, audio)

Sends audio to the specified chat

For uploading an audio file, see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#sendaudio

Parameters:
Name Type Description
chatId Number

ID of the target chat
audio mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendDocument(chatId, document)

Sends a document to the specified chat

For uploading a document file, see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#senddocument

Parameters:
Name Type Description
chatId Number

ID of the target chat
document mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendLocation(chatId, latitude, longitude)

Sends a location to the specified chat

More info: https://core.telegram.org/bots/api#sendlocation

Parameters:
Name Type Description
chatId Number

ID of the target chat
latitude String | Number

Latitude of the location
longitude String | Number

Longitude of the location
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendMessage(chatId, str, params)

Sends a message to the specified chat

More info: https://core.telegram.org/bots/api#sendmessage

Parameters:
Name Type Description
chatId Number

ID of the target chat
str String

Message text
params Array

(Optional) Additional params to supply to the request
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendPhoto(chatId, photo)

Sends a photo to the specified chat

For uploading a photo, see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#sendphoto

Parameters:
Name Type Description
chatId Number

ID of the target chat
photo mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendSticker(chatId, sticker)

Sends a sticker to the specified chat

For uploading a sticker (image file), see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#sendsticker

Parameters:
Name Type Description
chatId Number

ID of the target chat
sticker mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendVideo(chatId, video)

Sends a video to the specified chat

For uploading a video file, see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#sendvideo

Parameters:
Name Type Description
chatId Number

ID of the target chat
video mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

sendVoice(chatId, voice)

Sends a voice recording to the specified chat

For uploading a voice recording (an audio file), see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#sendvoice

Parameters:
Name Type Description
chatId Number

ID of the target chat
voice mixed

File ID to resend or a file to upload
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise

setWebhook(url, certificate)

Sets an HTTPS URL where Telegram will send updates

Note: this WILL disable all updates/messages from the API

For uploading the certificate, see allowed parameters here: https://github.com/request/request#multipartform-data-multipart-form-uploads

More info: https://core.telegram.org/bots/api#setwebhook

Parameters:
Name Type Description
url String

HTTPS url to send updates to
certificate mixed

Your publickey certificate
Returns:

A promise that resolves with the result once the API request has finished

Type
Promise