Skip to content

Latest commit

 

History

History
289 lines (204 loc) · 10.2 KB

README.md

File metadata and controls

289 lines (204 loc) · 10.2 KB
Raw

teabot

license node npm bitHound Score

TeaBot allows you to create highly interactive Telegram bots for Node.js with some additional cool features.

Features

Difference between TeaBot 1.x.x and TeaBot 2.0.0 here.

Usage

$ npm install teabot --save

Simple echo bot:

const TeaBot = require('teabot')('TELEGRAM_BOT_TOKEN', 'TELEGRAM_BOT_NAME');

TeaBot.defineCommand(function (dialog, message) {
  dialog.sendMessage('Echo: ' + message.text);
});

TeaBot.startPolling();

Quick navigation

Methods

TeaBot based on tg-yarl (wrapper over Telegram Bot Api with additional features) package, it means TeaBot inherits all methods from tg-yarl.

Start methods

Depending on what type of connection with Telegram is used (webhook or long polling), there are 2 methods to start the bot.

TeaBot.receive(message)

To work with webhook.

Params

  • message (Object) - Message object received from Telegram using the webhook.

TeaBot.startPolling([options])

To work with long polling.

Params

  • [options] (Object) - Polling options:
    • offset (Integer) - Identifier of the first update to be returned (0 by default).
    • limit (Integer) - Limits the number of updates to be retrieved (100 by default).
    • timeout (Integer) - Timeout in seconds for long polling (60 by default).

Dialog object

Dialog object stores bot current dialogue with the user, as well as commands (full list here) for communication.
It can be obtained from the first parameter in defineCommand and defineAction callbacks, or directly from TeaBot object.

dialog.getAction()

Checks whether the user is in a state of action, and if so action name will be returned, otherwise false.

dialog.startAction(action)

Start the action. Then all processes occur in defineAction callbacks. Action callback will be called at the next incoming message.

Params

  • action (String) - Name of the action defined in defineAction.

dialog.performAction(action)

Perform the action. Then all processes occur in defineAction callbacks. Action callback will be called immediately.

Params

  • action (String) - Name of the action defined in defineAction.

dialog.endAction([saveTemp])

Ends the action and clears dialog.tempData.

Params

  • [saveTemp] (Boolean) - If true, then dialog.tempData will not be cleared.

More dialog object methods in docs.

Message object

Message object stores processed incoming message, as well as its original copy.
It can be obtained from dialog.message or from the second parameter in defineCommand and defineAction callbacks.

message.getCommand()

Returns command or empty string.

message.getArgument()

It returns the rest of the message, if it contains a command or the entire message.

More message object methods in docs.

Commands

Commands always starts with /.

TeaBot.defineCommand(command, callback)

Params

  • command (String|Array) - Command or an array of commands. Also supports wildcards (Use * to match zero or more characters. A pattern starting with ! will be negated).
  • callback (Function) - Callback which is invoked for this command/commands.

TeaBot.defineCommand(callback)

Params

  • callback (Function) - Callback which is invoked if the given command is not defined or is not available.
TeaBot
  .defineCommand(['/start', '/help'], function (dialog, message) {
    dialog.sendMessage('Hi there. This is a ' + message.getCommand() + ' command.');
  })
  .defineCommand('/hi*', function (dialog, message) { // wildcard
    dialog.sendMessage('This command ' + message.getCommand() + ', starts with /hi');
  })
  .defineCommand(function (dialog) {
    dialog.sendMessage('Send me /help for more information.');
  });

Actions

You can define some actions if you want to add interactivity to your bot. Or you want to split your code.

TeaBot.defineAction(action, callback)

Params

  • action (String|Array) - Action or an array of actions. Also supports wildcards (Use * to match zero or more characters. A pattern starting with ! will be negated).
  • callback (Function) - Callback which is invoked for this action/actions when it starts.
TeaBot
  .defineCommand('/help', function (dialog, message) {
    if (message.getArgument()) {
      dialog.performAction('/help:1'); // /help argument
    } else {
      dialog.startAction('/help:2').sendMessage('This is /help command.'); // /help
    }
  })
  .defineCommand(function (dialog) {
    dialog.sendMessage('Send me /help for more information.');
  });

TeaBot
  .defineAction('/help:*', function (dialog) { // wildcard
    dialog.endAction().sendMessage('This is ' + dialog.getAction() + ' action'); // if /help was with argument, then /help:1 action, otherwise /help:2
  });

Inline mode

TeaBot.inlineQuery(query, callback)

Params

  • query (String|Array) - Query or an array of queries. Also supports wildcards (Use * to match zero or more characters. A pattern starting with ! will be negated).
  • callback (Function) - Callback which is invoked for this query/queries.

TeaBot.inlineQuery(callback)

Params

  • callback (Function) - Callback which is invoked if the given query is not defined, is not available or is empty.
TeaBot
  .inlineQuery('tay*', function (query) { // wildcard
    query
      .addGif(
        { gif_url: 'https://33.media.tumblr.com/tumblr_m3xrtsmgs11rn435g.gif', thumb_url: 'https://33.media.tumblr.com/tumblr_m3xrtsmgs11rn435g.gif', gif_width: 500, gif_height: 247 }
      )
      .addGif(
        { gif_url: 'http://blog.admissions.illinois.edu/wp-content/uploads/2015/08/Screaming-Taylor-Swift.gif', thumb_url: 'http://blog.admissions.illinois.edu/wp-content/uploads/2015/08/Screaming-Taylor-Swift.gif', gif_width: 480, gif_height: 267 }
      )
      .answer();
  })
  .inlineQuery(function (query) {
    query
      .addArticles([
        { title: 'Test 1', message_text: 'test' },
        { title: 'Test 2', message_text: 'test' },
        { title: 'Test 3', message_text: 'test' }
      ])
      .answer();
  });

More info about inline mode in docs.

More info about query object in docs.

Plugins

At the moment TeaBot supports only db and analytics plugins, but in the future there will be more.

TeaBot.use(name, plugin)

Params

  • type (String) - Plugin type: db or analytics.
  • plugin (Object) - Object with plugin.
const TeaBot = require('teabot')('TELEGRAM_BOT_TOKEN', 'TELEGRAM_BOT_NAME');

TeaBot.use('analytics', require('teabot-botan')('BOTAN_TOKEN'));

TeaBot.defineCommand(function (dialog, message) {
  dialog.sendMessage('Echo: ' + message.text); // all message events will be sent directly to botan.io
});

TeaBot.startPolling();

Available plugins:

More info about plugins in docs.

Information about how to write your own plugin here.

Errors

By default, no errors are displayed, except for those that may interfere start the bot. But with these methods you be able to handle errors by yourself.

TeaBot.error(error)

Use this method in Promise, Callback functions and whenever you want.

Params

  • error (Object) - Error object.

TeaBot.onError(callback)

When error occurs or when TeaBot.error() is used, callback will be invoked.

Params

  • callback (Function) - Callback which is invoked when TeaBot.error() is called (including internal call).
TeaBot.onError(function (e) {
  console.error('TeaBot error:', e.stack);
});

TeaBot.defineCommand(function (dialog, message) {
  dialog.sendMessage('Echo: ' + message.text).then(function () {
    throw new Error('Test error 1');
  }).catch(TeaBot.error);
  throw new Error('Test error 2');
});

Documentation

Examples

Other examples here.

License

The MIT License (MIT)
Copyright (c) 2015-2016 Alexey Bystrov