fparaggio / telebot Goto Github PK

The easy way to write Telegram bots.

Library features:

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

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

Import telebot module and create a new bot object:

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:[email protected]:8080' // Optional. An HTTP proxy to be used (supports Basic Auth).
    },
    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 build-in plugins from pluginFolder.
    pluginFolder: '../plugins/', // Optional. Plugin folder location relative to telebot package.
    pluginConfig: { // Optional. Plugin configuration.
        // myPluginName: {
        //   data: 'my custom value'
        // }
    }
});

Or just:

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

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

bot.start();

We just created echo bot!

Send text on /start or /hello command:

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

When sticker received, reply back:

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):

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

Command with arguments /say <your message>:

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

When message was edited:

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

See more examples!

Use bot.on(<event>, <function>) to handle all possible TeleBot events.

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

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

Also, you can catch multiple events:

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

• /* – any user command
• /<cmd> – 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
• inlineChoice - inline query chosen result
• callbackQuery - button callback data

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

• * - 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
• contact – contact data
• location – location data
• venue – venue data
• game - game data
• edit – edited message
• forward – forwarded message
• pinnedMessage – message was pinned
• userJoined – new member was added
• userLeft – member was removed
• newTitle – new chat title
• newPhoto – new chat photo
• deletePhoto – chat photo was deleted
• groupCreated – group has been created
• channelCreated – channel has been created
• supergroupCreated – supergroup has been created
• migrateTo – group has been migrated to a supergroup
• migrateFrom – supergroup has been migrated from a group

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

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

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

This code adds emoji to every text message.

• property - mod form properties
• updateList - list of updates in one tick
• update - every update
• message - process any type of message
• <type> - specific type of message (text, voice, document, photo, sticker, video, contact, location or venue)

Use usePlugins config option to load build-in plugins from pluginFolder:

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

Or use bot.use(require(<plugin_path>)) to plug an external plugin.

Check out build-in plugin folder!

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

Handles events.

Invokes the event handlers.

Add data modifier.

Run data modifiers.

Use module function.

Creates ReplyKeyboardMarkup keyboard markup object.

Creates KeyboardButton button.

Creates InlineKeyboardButton button object.

Creates inlineKeyboard object for normal bot messages.

Creates answerInlineQuery answer list object.

Creates inlineKeyboard object for answerList articles.

Start polling updates.

Stop polling updates.

TeleBot use standard Telegram Bot API method names.

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

Use this method to send answerList to an inline query.

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

Use this method to send text messages.

Use this method to forward messages of any kind.

Use this method to send photos.

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

Use this method to send general files.

Use this method to send .webp stickers.

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

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

Use this method to send point on the map.

Use this method to send information about a venue.

Use this method to send phone contacts.

Use this method when you need to tell the user that something is happening on the bot's side.

Use this method to send a game.

Use this method to set the score of the specified user in a game. On success, if the message was sent by the bot, returns the edited Message, otherwise returns True. Returns an error, if the new score is not greater than the user's current score in the chat and force is False.

Use this method to get data for high score tables. Will return the score of the specified user and several of his neighbours in a game. On success, returns an Array of GameHighScore objects.

Use this method to get a list of profile pictures for a user.

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

Use this method to get up to date information about the chat.

Use this method for your bot to leave a group, supergroup or channel.

Use this method to get a list of administrators in a chat.

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

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

Use this method to kick a user from a group or a supergroup.

Use this method to unban a previously kicked user in a supergroup.

Use this method to edit text messages sent by the bot or via the bot (for inline bots).

Use this method to edit captions of messages sent by the bot or via the bot (for inline bots).

Use this method to edit only the reply markup of messages sent by the bot or via the bot (for inline bots).

Use this method to send answers to callback queries sent from inline keyboards.

Use this method to specify a url and receive incoming updates via an outgoing webhook.

Use this method to get current webhook status.

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