Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »


    Framework for Bot APIs

    built for the Telegram Bot API

    npm npm npm GitHub stars



    For use with the Telegram Bot API, please use the extended package bot22api-telegram!

    const bot22api = require('bot22api');
    const { Bot, Handler, Requirement } = bot22api;
    const { parsers, requires } = bot22api;
    const bot = new Bot({
      apiUrl: '',
      parser: parsers.json
    bot.register(new Handler('dbHandler', (done, { data }) => {
    bot.register(new Handler({
      name: 'textHandler',
      callable: function textHandler(done) {
        this.send('message', {
          text: `Hello ${}!`
      requires: [
        new Requirement('helloChecker', (done, processor) => {
          if ( === 'hello') done(); // no error 
          else done(true); // error 
    bot.listen(3000, 'localhost');


    npm install bot22api

    getting started

    First of all require all needed dependencies.

    const bot22api = require('bot22api');
    const { Bot, Handler } = bot22api;

    Bot /docs/

    To create a new bot, call its constructor.

    const bot = new Bot({
      apiUrl: '',
      route: /.*/,
      parser: bot22api.parsers.json,
      server: undefined, // will be created automatically 
      log: null // will send no logs if null. npmlog by default 

    Now that you have a Bot object, you need to register so-called Handlers using the Bot's register method. Each Callable (Handler or Requirement) must have a unique name.

    Bot#register /docs/


    Handler /docs/

    Each time the bot receives a HTTP request, it'll try to execute all handlers that is has. A Handler can also have Requirements, that do almost the same as Handlers, but they check if the data can be used by the Handler. If one Requirement fails, the Handler won't execute.

    bot.register(new Handler({
      name: 'loggerHandler',
      callable: (done, { data }) => {

    Callable /docs/

    All Callable-extending classes (Handler and Requirement) can also be constructed by passing the Callable name, the Callable function and optional Requirements.

    This is what all Callables have in common. Mind that requires is optional!

    Callable {
      name: string,
      callable: function,
      [requires]: Requirement[]

    Callables themselves can not be used in any way. Do always construct either Handlers or Requirements.

    By using a named function, you do not need to pass the name as a string, as the name is already given. See the documentation for further information about the construction of Callables.


    You can't simply filter out the send method from the processor and call it! Since send accesses the bot through the processor, it needs to get properties of this, which does not exist after you extracted it from the processor.

    For workarounds, take a look at the documentation: Processor#send

    Requirement /docs/

    A Requirement constructs like any other Callable: Like a Handler. The only big difference to a Handler is when they are used.

    Requirements perform checks or modifications on the data that the handler relies on. Requirements can also depend on other Requirements.

    In any Callable, the requirements are represented in an Array named requires. For example, here's a Handler with some Requirements.

    const { Requirement, requires } = bot22api;
    new Handler({
      name: 'requirementShowcaseHandler',
      callable: (done) => {
        console.log('All Requirements have passed.'); done();
      requires: [
        // checks if user.type === 'admin''admin', 'user', 'type'),
        // using the (functionName, requires) constructor, see Callable doc 
        new Requirement(function textNotEmpty(done, { data }) {
          if (typeof data.text === 'string' && data.text.length === 0) done();
          else done(true); // error -> done(err) 
        }, [ requires.has('text') ])

    This results in a Requirements tree like:

    • requirementShowcaseHandler
      • isUserTypeAdmin
        • hasUserType
      • textNotEmpty
      • hasText

    Processor /docs/

    When a HTTP request invokes a bot, the bot creates a Processor for all Handlers. As the Handlers and Requirement so get embedded into an environment that contains all current states, properties like the passed API URL and route can be retrieved from that object.

    You can use the processor while inside a Callable function (Handler or Requirement)

    new Handler({
      callable: (done, processor) => {
        console.log('Cool?', processor.handler.options.beCool);
        processor.send('message', `I received ${} ` +
          `on route ${processor.route}`);
      options: { beCool: true }


    Once everything is set up, you need to tell the bot's server to start listening. To do that, simply call the Bot's listen method. If your server runs more than one Bot, call the Server's listen method instead.

    bot.listen(3000, 'localhost');

    Now to make HTTP requests, call your URL, which consists of your hostname, port, an optional route followed by ?url= and the set API URL. The data is submit in the POST request's body.

    So just give the full URL to your bot API.






    npm i bot22api

    Downloadslast 7 days







    last publish


    • avatar