botact

botact.js

Botact enables developers to focus on writing reusable application logic instead of spending time building infrastructure.

Donate 💰

Thank you for donations.

• Bitcoin: 1C26xXoA42Ufz5cNNPhAJY8Ykqh2QB966L
• Ethereum: 0x331FeA1a0b0E9E66A647e964cF4eBE1D2E721579
• Qiwi: 79522232254

Install

$ npm i botact

Tests

$ npm test

Usage

const bodyParser = require('body-parser')
const express = require('express')
const { Botact } = require('botact')

const app = express()
const bot = new Botact({
  confirmation: process.env.CONFIRMATION,
  token: process.env.TOKEN
})

bot.command('start', ({ reply }) => reply('This is start!'))
bot.hears(/(car|tesla)/, ({ reply }) => reply('I love Tesla!'))
bot.event('group_join', ({ reply }) => reply('Thanks!'))
bot.on(({ reply }) => reply('What?'))

app.use(bodyParser.json())
app.post('/', bot.listen)
app.listen(process.env.PORT)

Methods

• constructor(options)
• [getter] options
• [setter] options
• .deleteOptions(settings)
• .before(callback)
• .use(callback)
• .execute(method, settings, token, callback)
• .command(command, callback)
• .hears(command, callback)
• .on(callback)
• .event(event, callback)
• .uploadDocument(file)
• .uploadPhoto(file)
• .uploadAndSaveCoverPhoto(file)
• .reply(userId, message, attachment, callback)
• .listen(req, res)

constructor(options)

Parameter	Type	Requried
options	object	yes

Create bot.

const { Botact } = require('botact')

const bot = new Botact({
  confirmation: process.env.CONFIRMATION,
  token: process.env.TOKEN
})

[getter] options

Get options.

bot.options
// {
//   confirmation: '12345',
//   token: 'abcde...'
// }

[setter] options

Set options.

bot.options = { foo: 'bar' }
// {
//   confirmation: '12345',
//   token: 'abcde...',
//   foo: 'bar'
// }

.deleteOptions(settings)

Parameter	Type	Requried
settings	array	yes

Delete keys settings.

bot.deleteOptions([ 'token', 'confirmation' ])
// {
//   foo: 'bar'
// }

.before(callback)

Parameter	Type	Requried
callback	function	yes

Add callback before bot will start.

bot.before(() => new Date())

bot.on(({ inital }) => {
  // Fri Nov 24 2017 16:00:21 GMT+0300 (MSK)
})

.use(callback)

Parameter	Type	Requried
callback	function	yes

Add middleware.

bot.use((ctx) => ctx.date = new Date())

bot.on(({ date }) => {
  // Fri Nov 24 2017 16:00:21 GMT+0300 (MSK)
})

.execute(method, settings, token, callback)

Parameter	Type	Requried
method	string	yes
settings	object	yes
token	string	yes
callback	function	no

Call API by execute.

bot.execute('users.get', {
  user_ids: 1
}, this.settings.token, (body) => {
  // {
  //   id: 1,
  //   first_name: 'Pavel',
  //   last_name: 'Durov'
  // }
})

.command(command, callback)

Parameter	Type	Requried
command	string	yes
callback	function	yes

Add command w/ strict match.

bot.command('start', ({ reply }) => {
  reply('This is start!')
})

.hears(command, callback)

Parameter	Type	Requried
command	string/regexp	yes
callback	function	yes

Add command w/ match like RegEx.

bot.hears(/(car|tesla)/, ({ reply }) => {
  reply('I love Tesla!')
})

.on(callback)

Parameter	Type	Requried
callback	function	yes

Add reserved callback.

bot.on(({ reply }) => {
  reply('What?')
})

.event(event, callback)

Parameter	Type	Requried
event	string	yes
callback	function	no

Add event.

bot.event('group_join', ({ reply }) => {
  reply('Thanks!')
})

.uploadDocument(file)

Parameter	Type	Requried
file	string	yes

Upload document.

await bot.uploadDocument(path.join(__dirname, 'files', 'book.pdf'))
// {
//   id: 445225557
//   owner_id: 145003487,
//   title: 'book.pdf',
//   ...
// }

.uploadPhoto(file)

Parameter	Type	Requried
file	string	yes

Upload photo.

await bot.uploadPhoto(path.join(__dirname, 'files', 'girl.png')) // { id: 456246067, ... }
// {
//   id: 456246067,
//   album_id: -14,
//   owner_id: 145003487,
//   ...
// }

.uploadAndSaveCoverPhoto(file)

Parameter	Type	Requried
file	string	yes

Upload and save cover.

await bot.uploadAndSaveCoverPhoto('./cover.jpg')
// {
//   response: {
//     images: [ [Object], [Object], [Object], [Object], [Object] ]
//   }
// }

.reply(userId, message, attachment, callback)

Parameter	Type	Requried
userId	number or array	yes
message	string	yes (no, if setten attachment)
attachment	string	yes (no, if setten message)
callback	function	no

bot.command('start', (ctx) => {
  // with shortcut from context
  ctx.reply('Hi, this is start!')
  // function from context
  ctx.sendMessage(ctx.user_id, 'Hi, this is start!')
  // simple usage
  bot.reply(ctx.user_id, 'Hi, this is start!')
  // to multiple users
  bot.reply([ ctx.user_id, 1 ], 'Hi, this is start!')
})

.listen(req, res)

Parameter	Type	Requried
req	object	yes
res	object	yes

Start listen.

bot.listen(req, res)

Scenes

Usage

$ redis-server

• .addScene(name, ...callbacks)
• .joinScene(ctx, scene, session, step, now)
• .leaveScene(ctx)
• .nextScene(ctx, body)

Example

const bodyParser = require('body-parser')
const express = require('express')
const { Botact } = require('botact')

const app = express()
const bot = new Botact({
  confirmation: process.env.CONFIRMATION,
  token: process.env.TOKEN,
  flowTimeout: 20, // document will be deleted after 20 secs
  redisConfig: {
    host: '127.0.0.1', // default host for redis
    port: 8080 // custom port for redis
  },
})

bot.addScene('wizard',
  ({ reply, scene: { next } }) => {
    next()
    reply('Write me something!')
   },
  ({ reply, body, scene: { leave } }) => {
    leave()
    reply(`You wrote: ${body}`)
  }
)

bot.command('join', ({ scene: { join } }) => join('wizard'))

app.use(bodyParser.json())
app.post('/', bot.listen)
app.listen(process.env.PORT)

.addScene(name, ...callbacks)

Parameter	Type	Requried
name	string	yes
callbacks	function	minumum one

Add scene.

bot.addScene('wizard',
  ({ reply, scene: { next } }) => {
    next()
    reply('Write me something!')
  },
  ({ reply, body, scene: { leave } }) => {
    leave()
    reply(`You wrote: ${body}`)
  }
)

.joinScene(ctx, scene, session, step, now)

Parameter	Type	Requried	Default
ctx	object	yes	none
scene	string	yes	none
session	object	no	{}
step	number	no	0
now	number	no	true

Enter scene.

bot.command('join', (ctx) => {
  // with shortcut without additional settings
  ctx.scene.join('wizard')
  // simple usage with additional settings
  bot.joinScene(ctx, 'wizard', { foo: 'bar' })
})

.leaveScene(ctx)

Parameter	Type	Requried
ctx	object	yes

Leave scene.

bot.addScene('wizard',
  (ctx) => {
    // with shortcut
    ctx.scene.leave()
    // simple usage
    bot.leaveScene(ctx)
  }
)

.nextScene(ctx, body)

Parameter	Type	Requried
ctx	object	yes
session	obect	no

Navigate scene.

bot.addScene('wizard',
  (ctx) => {
    // with shortcut without additional settings
    ctx.scene.next({ foo: 'bar' })
    // simple usage with additional settings
    bot.nextScene(ctx, { foo: 'bar' })
  }
)

License

MIT.