telebot-plugins


The easy way to write Telegram bots.

  !Node.js Version

   

Library features:

- 🍎 Simple. Easy to use.
- 🏰 Full Telegram Bot API support.
- 💰 Supports payments.
- 🔌 Supports plugins!
- 📡 Build-in modification and event system.
- 🛠 Extendable and hackable.
- 🔮 No callbacks, Promises only.
- 🤓 Readable changelog.
- ☺️ Friendly TeleBot community group.

🔨 Installation

Download and install via npm package manager (stable):

``
npm install telebot --save
`

Or clone fresh code directly from git:

`
git clone https://github.com/mullwar/telebot.git
cd telebot
npm install
`

🕹 Usage

Import telebot module and create a new bot object:

`js
const TeleBot = require('telebot');

const bot = new TeleBot({
token: 'TELEGRAM_BOT_TOKEN', // Required. Telegram Bot API token.
polling: { // Optional. Use polling.
interval: 1000, // Optional. How often check updates (in ms).
timeout: 0, // Optional. Update polling timeout (0 - short polling).
limit: 100, // Optional. Limits the number of updates to be retrieved.
retryTimeout: 5000, // Optional. Reconnecting timeout (in ms).
proxy: 'http://username:password@yourproxy.com:8080' // Optional. An HTTP proxy to be used.
},
webhook: { // Optional. Use webhook instead of polling.
key: 'key.pem', // Optional. Private key for server.
cert: 'cert.pem', // Optional. Public key.
url: 'https://....', // HTTPS url to send updates to.
host: '0.0.0.0', // Webhook server host.
port: 443, // Server port.
maxConnections: 40 // Optional. Maximum allowed number of simultaneous HTTPS connections to the webhook for update delivery
},
allowedUpdates: [], // Optional. List the types of updates you want your bot to receive. Specify an empty list to receive all updates.
usePlugins: ['askUser'], // Optional. Use user plugins from pluginFolder.
pluginFolder: '../plugins/', // Optional. Plugin folder location.
pluginConfig: { // Optional. Plugin configuration.
// myPluginName: {
// data: 'my custom value'
// }
}
});
`

Or just:

`js
const TeleBot = require('telebot');
const bot = new TeleBot('TELEGRAM_BOT_TOKEN');
`

Don't forget to insert your Telegram Bot API token key.

To start polling updates, use `bot.start()`.

`js
bot.on('text', (msg) => msg.reply.text(msg.text));

bot.start();
`

We just created echo bot!

🌱 Quick examples

Send text on /start or /hello command:

`js
bot.on(['/start', '/hello'], (msg) => msg.reply.text('Welcome!'));
`

When sticker received, reply back:

`js
bot.on('sticker', (msg) => {
return msg.reply.sticker('http://i.imgur.com/VRYdhuD.png', { asReply: true });
});
`

Sends photo on "show kitty" or "kitty" text message (using RegExp):

`js
bot.on(/(show\s)?kitty*/, (msg) => {
return msg.reply.photo('http://thecatapi.com/api/images/get');
});
`

Command with arguments /say :

`js
bot.on(/^\/say (.+)$/, (msg, props) => {
const text = props.match[1];
return bot.sendMessage(msg.from.id, text, { replyToMessage: msg.message_id });
});
`

When message was edited:

`js
bot.on('edit', (msg) => {
return msg.reply.text('I saw it! You edited message!', { asReply: true });
});
`

Note: msg.reply is a bot method shortcut, part of shortReply build-in plugin.

See more examples!

⏰ Events

Use `bot.on(, )` to handle all possible TeleBot events.

For example, to catch a command, just add a slash:

`js
bot.on('/hello', (msg) => {
return bot.sendMessage(msg.from.id, Hello, ${ msg.from.first_name }!);
});
`

Also, you can catch multiple events:

`js
bot.on(['/start', 'audio', 'sticker'], msg => {
return bot.sendMessage(msg.from.id, 'Bam!');
});
`

$3

- /* – any user command
- /\ – on specific command
- start – bot started
- stop – bot stopped
- reconnecting – bot reconnecting
- reconnected – bot successfully reconnected
- update - on update
- tick – on bot tick
- error – an error occurred
- inlineQuery - inline query data
- chosenInlineResult - inline query chosen result
- callbackQuery - button callback data
- shippingQuery - incoming shipping query
- preShippingQuery - incoming pre-checkout query

#### Events:

keyboard, button, inlineKeyboard, inlineQueryKeyboard, inlineButton, answerList, getMe, sendMessage, deleteMessage, forwardMessage, sendPhoto, sendAudio, sendDocument, sendSticker, sendVideo, sendVideoNote, sendVoice, sendLocation, sendVenue, sendContact, sendChatAction, getUserProfilePhotos, getFile, kickChatMember, unbanChatMember, answerInlineQuery, answerCallbackQuery, answerShippingQuery, answerPreCheckoutQuery, editMessageText, editMessageCaption, editMessageReplyMarkup, setWebhook

$3

- * - any type of message
- text – text message
- audio – audio file
- voice – voice message
- document – document file (any kind)
- photo – photo
- sticker – sticker
- video – video file
- videoNote - video note
- contact – contact data
- location – location data
- venue – venue data
- game - game data
- invoice - invoice for a payment
- edit – edited message
- forward – forwarded message
- pinnedMessage – message was pinned
- newChatMembers - new members that were added to the group or supergroup
- leftChatMember – member was removed
- newChatTitle – new chat title
- newChatPhoto – new chat photo
- deleteChatPhoto – chat photo was deleted
- groupChatCreated – group has been created
- channelChatCreated – channel has been created
- supergroupChatCreated – supergroup has been created
- migrateToChat – group has been migrated to a supergroup
- migrateFromChat – supergroup has been migrated from a group

Read more about Telegram Bot API response types: https://core.telegram.org/bots/api#available-types

🚜 Modifiers

You can add modifier to process data before passing it to event.

`js
bot.mod('text', (data) => {
let msg = data.message;
msg.text = 📢 ${ msg.text };
return data;
});
`

This code adds emoji to every text message.

$3

- property - mod form properties
- updateList - list of updates in one tick
- update - every update
- message - process any type of message
- \ - specific type of message

🔌 Plugins

Use usePlugins config option to load plugins from pluginFolder directory:

`js
const bot = new TeleBot({
token: 'TELEGRAM_BOT_TOKEN',
usePlugins: ['askUser', 'commandButtons'],
pluginFolder: '../plugins/',
pluginConfig: {
// Plugin configs
}
});
`

Or use `plug(require())` to plug an external plugin.

Check out build-in plugin folder!

$3

`js
module.exports = {
id: 'myPlugin', // Unique plugin name
defaultConfig: {
// Default plugin config
key: 'value'
},
plugin(bot, pluginConfig) {
// Plugin code
}
};
`

⚙️ Methods

$3

##### on(, )

Handles events.

##### event(, )

Invokes the event handlers.

##### mod(, )

Add data modifier.

##### modRun(, )

Run data modifiers.

##### plug()

Use plugin function.

##### keyboard([array of arrays], {resize, once, remove, selective})

Creates ReplyKeyboardMarkup keyboard replyMarkup object.

##### button(, )

Creates KeyboardButton button.

##### inlineButton(, {url | callback | game | inline | inlineCurrent | pay})

Creates InlineKeyboardButton button object.

##### inlineKeyboard([array of arrays])

Creates inlineKeyboard object for normal bot messages.

##### answerList(, {nextOffset, cacheTime, personal, pmText, pmParameter})

Creates answerInlineQuery answer list object.

##### inlineQueryKeyboard([array of arrays])

Creates inlineKeyboard object for answerList articles.

##### start()

Start polling updates.

##### stop()

Stop polling updates.

$3

TeleBot use standard Telegram Bot API method names.

##### getMe()

A simple method for testing your bot's auth token.

##### answerQuery()

Use this method to send answerList to an inline query.

##### getFile()

Use this method to get basic info about a file and prepare it for downloading.

##### sendMessage(, , {parseMode, replyToMessage, replyMarkup, notification, webPreview})

Use this method to send text messages.

##### forwardMessage(, , , {notification})

Use this method to forward messages of any kind.

##### deleteMessage(, )

Use this method to delete a message. A message can only be deleted if it was sent less than 48 hours ago. Any such sent outgoing message may be deleted. Additionally, if the bot is an administrator in a group chat, it can delete any message. If the bot is an administrator of a supergroup or channel, it can delete ordinary messages from any other user, including service messages about people added or removed from the chat. Returns True on success.

##### sendPhoto(, , {caption, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send photos.

##### sendAudio(, , {title, performer, duration, caption, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message.

##### sendDocument(, , {caption, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send general files.

##### sendSticker(, , {fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send .webp stickers.

##### sendVideo(, , {duration, width, height, caption, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send video files, Telegram clients support mp4 videos (other formats may be sent as Document).

##### sendVideoNote(, , {duration, length, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send video messages.

##### sendVoice(, , {duration, caption, fileName, serverDownload, replyToMessage, replyMarkup, notification})

Use this method to send audio files, if you want Telegram clients to display the file as a playable voice message.

##### sendLocation(, [, ], {replyToMessage, replyMarkup, notification})

Use this method to send point on the map.

##### sendLocation(, [, ], {replyToMessage, replyMarkup, notification})

Use this method to send point on the map.

##### editMessageLiveLocation({chatId + messageId | inlineMessageId, latitude, longitude}, {replyMarkup})

Use this method to edit live location messages sent by the bot or via the bot (for inline bots). A location can be edited until its live_period expires or editing is explicitly disabled by a call to stopMessageLiveLocation.

##### stopMessageLiveLocation({chatId + messageId | inlineMessageId}, {replyMarkup})

Use this method to stop updating a live location message sent by the bot or via the bot (for inline bots) before live_period expires.

##### sendVenue(, [, ],