Skip to content

Latest commit

 

History

History
374 lines (238 loc) · 11 KB

README.md

File metadata and controls

374 lines (238 loc) · 11 KB
Raw

Easy way to write Telegram bots.

Build Status Dependency Status Node.js Version

Library features:

  • Simple. Easy to use.
  • Full Telegram Bot API support.
  • Support modules.
  • No callbacks, Promises only.
  • Build-in modification and event system.
  • Extendable and hackable.
  • Readable changelog.

Installation

Download and install via npm package manager (stable):

npm install telebot

Or clone fresh code directly from git:

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

Usage

Import telebot module and create a new bot object:

const TeleBot = require('telebot');

const bot = new TeleBot({
  token: '-PASTEYOURTELEGRAMBOTAPITOKENHERE-', // 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).
    allowedUpdates: [] // Optional. List the types of updates you want your bot to receive. Specify an empty list to receive all updates regardless of type.
  },
  webhook: { // Optional. Use webhook instead of polling.
    key: '__YOUR_KEY__.pem', // Optional. Private key for server.
    cert: '__YOUR_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.
  },
  modules: {
    // Optional. Module configuration.
    //
    // Example:
    //
    // myModuleName: {
    //   data: 'my module data'
    // }
    }
  }
});

Or just:

const TeleBot = require('telebot');
const bot = new TeleBot('-PASTEYOURTELEGRAMBOTAPITOKENHERE-');

Replace token value to your Telegram Bot API token key.

To start getting updates, use bot.connect().

bot.on('text', msg => {
  let fromId = msg.from.id;
  let firstName = msg.from.first_name;
  let reply = msg.message_id;
  return bot.sendMessage(fromId, `Welcome, ${ firstName }!`, { reply });
});

bot.connect();

This code will send a "welcome" to every users text type message as a reply.

See more examples!

Events

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

To catch a command with arguments, just add a slash:

bot.on('/hello', msg => {
  let [cmdName, firstName, lastName] = msg.text.split(' ');
  return bot.sendMessage(msg.from.id, `Hello, ${ firstName } ${ lastName }!`);
});

Also, you can catch multiple events:

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

TeleBot events:

  • /* – any user command
  • /<cmd> – on specific command
  • connect – bot connected
  • disconnect – bot disconnected
  • 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

Action events:

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

Telegram message events:

  • * - 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
  • edited – edited 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

Modifiers

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

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

This code adds emoji to every text message.

TeleBot modifiers:

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

Modules

Use bot.use(require(<module_path>)) to add a module.

Check out module folder!

Methods

TeleBot methods:

on(<events>, <function>)

Handles events.

event(<event>, <data>)

Invokes the event handlers.

mod(<name>, <fn>)

Add data modifier.

runMod(<names>, <data>)

Run data modifiers.

use(<function>)

Use module function.

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

Creates ReplyKeyboardMarkup keyboard markup object.

button(<location | contact>, <text>)

Creates KeyboardButton button.

inlineButton(<text>, {url | callback | inline})

Creates InlineKeyboardButton button object.

inlineKeyboard([array of arrays])

Creates inlineKeyboard object for normal bot messages.

answerList(<inline_query_id>, {nextOffset, cacheTime, personal})

Creates answerInlineQuery answer list object.

inlineQueryKeyboard([array of arrays])

Creates inlineKeyboard object for answerList articles.

connect()

Start polling updates.

disconnect(<message>)

Stop polling updates.

Telegram methods:

TeleBot use standard Telegram Bot API method names.

getMe()

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

answerQuery(<answerList>)

Use this method to send answerList to an inline query.

getFile(<file_id>)

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

sendMessage(<chat_id>, <text>, {parse, reply, markup, notify, preview})

Use this method to send text messages.

forwardMessage(<chat_id>, <from_chat_id>, <message_id>, {notify})

Use this method to forward messages of any kind.

sendPhoto(<chat_id>, <file_id | path | url | buffer | stream>, {caption, fileName, reply, markup, notify})

Use this method to send photos.

sendAudio(<chat_id>, <file_id | path | url | buffer | stream>, {fileName, reply, markup, notify})

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

sendDocument(<chat_id>, <file_id | path | url | buffer | stream>, {caption, fileName, reply, markup, notify})

Use this method to send general files.

sendSticker(<chat_id>, <file_id | path | url | buffer | stream>, {fileName, reply, markup, notify})

Use this method to send .webp stickers.

sendVideo(<chat_id>, <file_id | path | url | buffer | stream>, {caption, fileName, reply, markup, notify})

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

sendVoice(<chat_id>, <file_id | path | url | buffer | stream>, {fileName, reply, markup, notify})

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

sendLocation(<chat_id>, [<latitude>, <longitude>], {reply, markup, notify})

Use this method to send point on the map.

sendVenue(<chat_id>, [<latitude>, <longitude>], <title>, <address>, {foursquare, reply, markup, notify})

Use this method to send information about a venue.

sendContact(<chat_id>, <number>, <firstName>, <lastName>, { reply, markup, notify})

Use this method to send phone contacts.

sendAction(<chat_id>, <action>)

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

getUserProfilePhotos as getUserPhoto(<chat_id>, {offset, limit})

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

getFile(<file_id>)

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

getChat(<chat_id>)

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

leaveChat(<chat_id>)

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

getChatAdministrators as getAdmins(<chat_id>)

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

getChatMembersCount as countMembers(<chat_id>)

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

getChatMember as getMember(<chat_id>, <user_id>)

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

kickChatMember as kick(<chat_id>, <user_id>)

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

unbanChatMember as unban(<chat_id>, <user_id>)

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

editMessageText as editText({chatId & messageId | inlineMsgId}, <text>)

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

editMessageCaption as editCaption({chat & message | inline}, <caption>)

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

editMessageReplyMarkup as editMarkup({chat & message | inline}, <markup>)

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

answerCallbackQuery as answerCallback(<callback_query_id>, <text>, <show_alert>)

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

setWebhook(<url>, <certificate>)

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

getWebhookInfo()

Use this method to get current webhook status.

Documentation

Read wiki on GitHub.