
Security News
Deno 2.2 Improves Dependency Management and Expands Node.js Compatibility
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
@powerdot/telegram_bot_framework
Advanced tools
Node.js framework based on Telegraf to facilitate writing multi-level and multi-page bots.
✈️ Examples are availiable here
⚠️ To run TBF you need to have MongoDB installed and running.
npm install @powerdot/telegram_bot_framework
For JS project:
// index.js
let { TBF } = require("@powerdot/telegram_bot_framework")
For TS project:
// index.ts
import { TBF } from "@powerdot/telegram_bot_framework"
Create enter point for your bot:
// index.js / index.ts
TBF({
telegram: {
token: "xxx", // provide your token
},
mongo: {
dbName: "testbot" // provide your db name in MongoDB
}
}).then(({ openPage }) => {
// If bot is ready, you can define own middlewares
// here is one for /start command
bot.command("start", async (ctx) => {
// open page with ID "index"
await openPage({ ctx, page: "index" })
})
})
So next step is create index page (check Introduction to Pages section below).
Here we will get acquainted with the concept of pages in the telegram bot.
// pages/index.js
let { Component } = require("@powerdot/telegram_bot_framework")
module.exports = Component(() => { // (1)
return { // (2)
actions: {
async main() { // (3)
await this.clearChat(); // (4)
this.send({ // (5)
text: `Hey!`
});
},
}
}
})
Ok, now we have a page with ID index and one action named main.
*Page ID is file name without extension.
🤔 But how it works?
(1)
- We create component with Component function. And exported it to module.exports.(2)
- Component function must to return object of our component.(3)
- We define action named main in actions key. It's a default action for every component.(4)
- We call clearChat method to clear chat.(5)
- We send message with send method.That's all.
Checkout the scheme below:
Main idea of this scheme is to display that Express and Pages/Plugins are connected by MongoDB database.
And also you can send user's data with API as in this example. And of course your API can interact with TBF Engine (send messages to users, etc.). through connection with TBF entry point.
By the way, you can see there is two routings:
webserver/index.js
file.Run your bot (node index.js
) and send /start
command to it.
👀 Let's see what happens.
/start
command.// index.js
bot.command("start", async (ctx) => {
await openPage({ ctx, page: "index" })
})
/start
command, your bot will open page with ID index by openPage* function.
*openPage()
function provided by TBF Engine.openPage({})
arguments if you don't provide it:// from
await openPage({ ctx, page: "index" })
// to
await openPage({ ctx, page: "index", action: "main" })
So that's why we need to add main to our actions in component. It's just a default action.
4. TBF triggers main action in index page.
// pages/index.js
let { Component } = require("@powerdot/telegram_bot_framework")
module.exports = Component(() => {
return {
actions: {
async main() { ... // <-- triggered action
// pages/index.js
...
async main() {
await this.clearChat(); // TBF Engine's method to clear chat with user
this.send({ // TBF Engine's method to send message back to user
text: `Hey!`
});
}
...
🎉 Congratulations!
You have successfully created your bot with TBF.
👉 Check out examples here is code and demos!
Pages and plugins are components.
Component is a function that returns object with:
{
id?: string;
actions: {
"main"(){ ... },
...(){ ... }
},
call?: () => {}
onCallbackQuery?: () => {}
onMessage?: () => {}
open?: () => {}
}
The ?
mark after key name means that key is optional.
If you don't want to change core logic of your Page/Plugin, you can work only with actions
.
id
defines uniq ID of your component. It's automatically generated by component's file name if you don't provide it.actions
is a object with actions inside. main
action is default action for every component.call()
is a function that will be triggered when user calls your bot. It's route user's message/action to onCallbackQuery()
of onMessage()
. You can override it in your component, but it can destruct your bot.onCallbackQuery()
is a function that will be triggered when user sends callback query to your bot. You can override it in your component, but it can destruct your bot.onMessage()
is a function that will be triggered when user sends message (text, sticker, location...) to your bot. You can override it in your component, but it can destruct your bot.open()
is a function that can open current Component programmatically.Easiest way to create component is to use Component function.
let { Component } = require("@powerdot/telegram_bot_framework");
module.exports = Component(() => {
return {
actions: {
async main() {
// code here
},
}
}
})
db
TBF database objectconfig
App's configurationparseButtons
Function that parses TBF Buttons/Keyboard to Telegraf format.let { Component } = require("@powerdot/telegram_bot_framework");
module.exports = Component(({db, config, parseButtons}) => {
^ ^ ^
You can use them inside functions declared in Component or in actions.
Routing
this.goToAction({action, data?})
sends user to action inside your component.this.goToPage({page, action?, data?})
sends user to page inside your bot.this.goToPlugin({page, action?, data?})
it's like goToPage()
but it sends user to plugin.Messaging
this.send({text, buttons?, keyboard?})
sends message to user.this.update({text, buttons?, keyboard?})
updates bot's visible last message.this.sendMediaGroup()
sends media group to user.this.clearChat()
clears chat with user.Datastore
this.user({user_id?})
returns user database object..get()
returns all user data..list()
returns users list..setValue(key, value)
sets value under key under user..getValue(key)
gets value under key under user..removeValue(key)
removes value under key under user..destroy()
destroys user and all his data..collection
contains methods for user's collections.find(query)
find one row in user's collection.findAll(query)
find many rows in user's collection.insert(value)
insert data to user's collection.update(query, value)
update one row in user's collection.updateMany(query, value)
update many rows in user's collection.delete(query)
delete one row in user's collection.deleteMany(query)
delete many rows in user's collectionthis.id
component's idthis.ctx
TBF context with Telegraf context. There is available all Telegraf/Telegram methods and data keys.this.type
type of component: page
/plugin
Also TBF provides data to action.
actions: {
async main({data}) {
^
There are 2 types of handers for callback
and message
.
Callback handler can be defined in two ways.
1. As default
actions: {
async main() {
// there is callback handler
},
}
1.1. Strict described - as method of action
actions: {
main: {
async handler() {
// there is callback handler
},
}
}
Message handler can be defined only strictly - as method of action
actions: {
main: {
async messageHandler() {
// there is message handler
},
}
}
TBF provides to message handler:
text
, photo
, video
, animation
, document
, voice
, audio
, poll
, sticker
, location
, contact
, venue
, game
, invoice
, dice
actions: {
main: {
async messageHandler({text, location}) {
^ ^
For example, if you want catch only text message from user:
actions: {
main: {
async messageHandler({text}) {
if(!text) return false;
// do something with text...
Oh! What is false
in return?!
return false
says to TBF to remove user's message. Without false
in return his message stay in chat until next chat clearing.
We can imagine a little action that asks for user's name.
/start
command that triggers index
page that automatically triggers main
action handler.Hey, send me your name!
main: {
async handler(){
this.send({ text: "Hey, send me your name!" }); // (1)
},
async messageHandler({text}) {
if(!text) return false;
this.update({text: `Your name is ${text}`}); // 2
},
}
index
) and current action (main
) by messageHandler
.TBF wraps Express and runs it on own.
But TBF requires files in /webserver/
directory with your logic and also shares bot
, db
, database
, conponents
with your executive files.
bot
- is Telegraf bot
objectdb
- MongoDB instancedatabase
- TBF MongoDB database collectionscomponents
- list of loaded pages and pluginsThere is couple examples of your webserver in TS:
// webserver/index.ts
import type { WebServerArgs } from "@powerdot/telegram_bot_framework/types";
module.exports = ({ bot, db, database, components }: WebServerArgs) => {
let express = require("express");
let router = express.Router();
let path = require("path");
router.use('/api', require('./api')({ bot, db, database, components } as WebServerArgs));
return router;
}
As you can see:
app
but router
, because TBF creates own app
,WebServerArgs
to your api module and etc../api/index.ts
// webserver/api/index.ts
import type { WebServerArgs } from "@powerdot/telegram_bot_framework/types";
module.exports = ({ bot, database }: WebServerArgs) => {
let express = require("express");
let router = express.Router();
router.get("/posts", async (req, res) => {
// some code here
// for example do something with database or bot
});
return router;
}
You need always wrap your express routers to function to provide data from parent modules and TBF.
Maybe later this concept will be changed...
Here is templates to start your project as quick as possible.
🕺 Template with only Bot
💃 Template with Bot + Webserver
With them you can easily to touch TBF and write own bot.
Powered by @powerdot
FAQs
Unknown package
The npm package @powerdot/telegram_bot_framework receives a total of 1 weekly downloads. As such, @powerdot/telegram_bot_framework popularity was classified as not popular.
We found that @powerdot/telegram_bot_framework demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Deno 2.2 enhances Node.js compatibility, improves dependency management, adds OpenTelemetry support, and expands linting and task automation for developers.
Security News
React's CRA deprecation announcement sparked community criticism over framework recommendations, leading to quick updates acknowledging build tools like Vite as valid alternatives.
Security News
Ransomware payment rates hit an all-time low in 2024 as law enforcement crackdowns, stronger defenses, and shifting policies make attacks riskier and less profitable.