botact.js
Botact enables developers to focus on writing reusable application logic instead of spending time building infrastructure.
Table of content
Install
via npm:
$ npm i botact -S
via yarn:
$ yarn add botact
Examples
express:
const express = require('express')
const bodyParser = require('body-parser')
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)
koa:
const Koa = require('koa')
const Router = require('koa-router')
const bodyParser = require('koa-bodyparser')
const { Botact } = require('botact')
const app = new Koa()
const router = new Router()
const bot = new Botact({
confirmation: process.env.CONFIRMATION,
token: process.env.TOKEN,
framework: 'koa'
})
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?')
})
router.post('/', bot.listen)
app.use(bodyParser())
app.use(router.routes())
app.listen(3000)
Botact API
Methods
Core
Actions
Options
Upload helpers
Botact API: Core ↑
constructor(settings)
Create bot.
Definition:
constructor (settings: {
confirmation: string;
token: string;
group_id?: number;
framework?: string;
flowTimeout?: number;
redis?: boolean;
redisConfig?: object;
})
Usage:
const { Botact } = require('botact')
const bot = new Botact({
confirmation: process.env.CONFIRMATION,
token: process.env.TOKEN
})
.api(method, settings)
Call API method (https://vk.com/dev/methods).
Definition:
async api (
method: string,
options?: object,
): Promise<any>;
Usage:
const user_data = await bot.api('users.get', {
user_ids: 1
})
.execute(method, settings, callback)
Call API by execute.
Definition:
async execute (
method: string,
options?: object,
callback?: function
): Promise<any>;
Usage:
bot.execute('users.get', {
user_ids: 1
}, (body) => {
})
.reply(user_id, message, attachment, keyboard)
Sends message to user
Definition:
async reply (
user_id: number,
message: string,
attachment: string,
keyboard: Object
): Promise<any>
Usage:
bot.command('start', (ctx) => {
ctx.reply('Hi, this is start!')
ctx.reply('Yo, this is keyboard?', null, {
one_time: false,
buttons: [
[
{
action: {
type: 'text',
payload: {
button: 'Hello, world!'
},
label: 'Hello, world!'
},
color: 'primary'
}
]
]
})
ctx.sendMessage(ctx.user_id, 'Hi, this is start!')
bot.reply(ctx.user_id, 'Hi, this is start!')
bot.reply([ ctx.user_id, 1 ], 'Hi, this is start!')
})
.listen(...args)
Start listen.
Definition:
express:
listen (
req: any,
res: any
callback: function
)
koa:
listen (
ctx: object,
callback: function
)
Usage:
bot.listen(req, res, (error) => {
res.status(500).json({
error: 'Server error'
})
})
bot.listen(ctx, (error) => {
ctx.throw(500, 'Server error')
})
Botact API: Actions ↑
.command(command, callback)
Add command w/ strict match.
Definition:
command (
command: string | string[],
callback: function
): Botact
Usage:
bot.command('start', ({ reply }) => reply('This is start!'))
.event(event, callback)
Add event handler .
Definition:
event (
event: string | string[],
callback: function
): Botact;
Usage:
bot.event('group_join', ({ reply }) => reply('Thanks!'))
.hears(command, callback)
Add command w/ match like RegEx.
Definition:
hears (
hear: string | RegExp | (string | RegExp)[],
callback: function
): Botact;
Usage:
bot.hears(/(car|tesla)/, ({ reply }) => reply('I love Tesla!'))
.on(type, callback)
Add reserved callback.
Definition:
on (
type: string,
callback: function
): Botact;
OR
on (
callback: function
): Botact;
Usage:
bot.on(({ reply }) => reply('What?'))
bot.on('audio', ({ reply }) => reply('Great music!'))
.use(callback)
Add middleware.
Definition:
use (
callback: function
): Botact
Usage:
bot.use(ctx => ctx.date = new Date())
bot.on(({ date }) => {
})
Botact API: Options ↑
[getter] options
Get options.
bot.options
[setter] options
Set options.
bot.options = { foo: 'bar' }
.deleteOptions(settings)
Delete keys settings.
Definition:
deleteOptions (
keys: string[]
): Botact
Usage:
bot.deleteOptions([ 'token', 'confirmation' ])
Botact API: Upload helpers ↑
.uploadCover(file, settings)
Upload and save cover. See detailed settings here.
Definition:
async uploadCover (
filepath: string,
settings?: object
): Promise<any>
Usage:
await bot.uploadCover('./cover.jpg', { crop_x2: 1590 })
.uploadDocument(file, peer_id, type)
Uploads document to peer.
Definition:
async uploadDocument (
filepath: string,
peer_id: number,
type: 'doc' | 'audio_message'
): Promise<any>;
Usage:
await bot.uploadDocument('./book.pdf', 1234)
.uploadPhoto(file, peer_id)
Uploads photo to peer.
Definition:
async uploadPhoto (
filepath: string,
peer_id: number
): Promise<any>
Usage:
await bot.uploadPhoto('./picture.png', 1234)
Botact Flow API
Usage
const bot = new Botact({
...,
redis: true
flowTimeout: 20
redisConfig: {
port: 1234
}
})
$ redis-server
Methods
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,
redis: true,
flowTimeout: 20,
redisConfig: {
host: '127.0.0.1',
port: 8080
},
})
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)
Botact Flow API: Methods
.addScene(name, ...callbacks)
Add scene.
Definition:
addScene (
name: string,
...args: function[]
): Botact;
Usage:
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)
Enter scene.
Definition:
async joinScene (
ctx: object,
scene: string,
session?: object,
step?: number,
instantly?: boolean
): Promise<Botact>;
Usage:
bot.command('join', (ctx) => {
ctx.scene.join('wizard')
bot.joinScene(ctx, 'wizard', { foo: 'bar' })
})
.nextScene(ctx, body)
Navigate scene.
Definition:
async nextScene (
ctx: object,
session?: object,
): Promise<Botact>;
Usage:
bot.addScene('wizard',
(ctx) => {
ctx.scene.next({ foo: 'bar' })
bot.nextScene(ctx, { foo: 'bar' })
}
)
.leaveScene(ctx)
Leave scene.
Definition:
async leaveScene(
ctx: object
): Promise<Botact>;
Usage:
bot.addScene('wizard',
(ctx) => {
ctx.scene.leave()
bot.leaveScene(ctx)
}
)
TypeScript
Botact includes TypeScript definitions.
Tests
via npm:
$ npm test
via yarn:
$ yarn test
License
MIT.