🤖 Zero-configuration Telegram bot runner
Clone or download
Latest commit 8a8218d Sep 22, 2018
Failed to load latest commit information.
bin 2.3.0 Aug 31, 2018
.editorconfig initial commit Oct 12, 2016
.eslintignore initial commit Oct 12, 2016
.eslintrc μ-bot 2.0 Oct 30, 2017
.gitignore update deps Aug 9, 2017
.travis.yml update deps & docs Dec 20, 2017
LICENSE initial commit Oct 12, 2016
index.js 2.3.0 Aug 31, 2018
package.json update deps Sep 22, 2018
readme.md update deps Sep 22, 2018


NPM Version node Build Status js-standard-style


🤖 Zero-configuration Telegram bot runner


micro-bot was built on top of Telegraf library.

Telegraf API documentation.


Install from NPM:

$ npm install micro-bot

Note: micro-bot requires Node 8.5.0 or later


If you have installed latest yarn or npm you can use create-bot scaffolding tool:

$ npm init bot smart-bot
$ cd smart-bot

Or using yarn:

$ yarn create bot smart-bot
$ cd smart-bot

Quick start

The following example will answer with important information about everything.

$ mkdir smart-bot
$ cd smart-bot
$ npm init
$ npm install micro-bot --save

Then write your index.js.

module.exports = ({ reply }) => reply('42')

Then in your package.json:

"main": "index.js",
"scripts": {
  "start": "micro-bot"

To run the bot, use the micro-bot command:

$ BOT_TOKEN='TOKEN' npm start


$ micro-bot -t TOKEN index.js

To run the bot with webhook support, provide webhook domain name:

$ micro-bot -t TOKEN -d yourdomain.tld echo.js

Supported environment variables:

  • process.env.BOT_TOKEN - Bot token
  • process.env.BOT_DOMAIN - Webhook domain

Telegraf context

micro-bot automatically fetch Bot info from telegram servers at start.

You can obtain it from update context:

module.exports = (ctx) => {
  return ctx.reply(`Hey, my name is ${ctx.botInfo.first_name} ${ctx.botInfo.last_name}`)

Deployment to now

Let's deploy your micro-bot with Realtime global deployments by Zeit.

First, install now

$ npm install now -g
$ now login

Then add now-start script in package.json as in following snippet:

"scripts": {
  "now-start": "micro-bot -d ${NOW_URL}"

Finally use now to deploy:


Congratulations, your bot is alive! 🎉

Deployment to Heroku

Okay, now we will deploy our micro-bot to Heroku. Why not?!

First, install heroku binaries and login via console.

Then, init new git repo:

$ git init
$ heroku create

Afterwards, update Heroku config:

$ heroku config:set --app YourAppId BOT_TOKEN='YOUR BOT TOKEN'
$ heroku config:set --app YourAppId BOT_DOMAIN='https://YourAppId.herokuapp.com'

Then add Procfile into the root of your project, with one line:

web: micro-bot -p $PORT

Finally use git to deploy:

$ git add index.js package.json
$ git commit -m 'initial commit'
$ git push heroku master

Congratulations, your bot is alive! Again.

Example μ-bots

Advanced Examples

const { mount, reply } = require('micro-bot')
module.exports = mount('sticker', reply('👍'))
const { readFileSync } = require('fs')
const { Composer } = require('micro-bot')
const app = new Composer()

app.start((ctx) => ctx.reply('Welcome'))
app.help((ctx) => ctx.reply('Help message'))
app.hears('hi', ({ reply }) => reply('Hello'))
app.on('sticker', ({ reply }) => reply('👍'))

// Export bot handler
module.exports = app

// Or you can export hash with handlers and options
module.exports = {
  initialize: (bot) => {...},
  botHandler: app,
  requestHandler:  (req, res, next) => {...},
  options: {
    telegram: {
      agent: new HttpsProxyAgent('proxy url')
  tlsOptions: {
    key:  readFileSync('server-key.pem'),
    cert: readFileSync('server-cert.pem'),
    ca: [
      // This is necessary only if the client uses the self-signed certificate.

Stages & Scenes

const { Composer, Stage, Scene, session } = require('micro-bot')

// Greeter scene
const greeter = new Scene('greeter')
greeter.enter((ctx) => ctx.reply('Hi'))
greeter.leave((ctx) => ctx.reply('Buy'))
greeter.hears(/hi/gi, (ctx) => ctx.scene.leave())
greeter.on('message', (ctx) => ctx.reply('Send `hi`'))

const stage = new Stage()

const bot = new Composer()
bot.command('greeter', (ctx) => ctx.scene.enter('greeter'))
bot.command('cancel', (ctx) => ctx.scene.leave())
module.exports = bot


micro-bot is highly inspired by Micro