List of content

About:

• Basic features
• Instalation
• Basic usage
• Ant anatomy
• Inline buttons, callback data handling
• Config
• Webhook and Polling
• Examples

Basic features

• Status-based user dialog stage managment.
• Easy-to-use.
• Webhook & polling support.
• All in one: all API methods, flexible dialog flow control.
• w/o functional overkill, nothing extra.

Instalation

• Using NPM:
  npm install ant-telegram
• Using Yarn:
  yarn add ant-telegram

Basic usage

Ant:Telegram require to provide 2 basic status managment async methods: for getting status to user by telegram chat_id, and for setting it.
Feel free to chose storing way (architecture, database etc.). We require next interfaces only:

getStatus(chat_id: number): Promise<string>;
setStatus(chat_id: number, status: string): Promise<any>;

Just put in on Ant:Telegram initialization with telegram bot token:

const { AntTelegram } = require('ant-telegram');

const token = '...'; // Your telegram bot token

const Ant = new AntTelegram(token, { 
    getStatus: (chat_id) => { ... }, 
    setStatus: (chat_id, status) => { ... },
});

Explore quick start example using MongoDB + mongoose.

Now you ready to use Ant:Telegram.
Let's add start dialog handler (/start command):

Ant.command('/start', async chat_id => {
    await Ant.bot.sendMessage(chat_id, 'Hi!');
})

Your bot ready to start. Run script and make sure it works:

Ant anatomy

Telegram API

See Ant.api

All api methods like

Ant.api.sendMessage(chat_id: number, text: string, options? TelegramOptions): Promise;
Ant.api.deleteChatStickerSet(chat_id: number, form: TelegramForm): Promise;

... and so on. See full list in node-telegram-bot-api dependency.

Events

// Telegram API response errors
Ant.on('error', err => { ... })
// Telegram polling errors
Ant.on('polling_error', err => { ... })
// Telegram webhook errors
Ant.on('webhook_error', err => { ... })
// Errors caused during user's scenario (status errors, access restrictions, ivalid inputs etc.)
Ant.on('chat_error', (chat_id, err) => { ... })

Also Ant:Telegram has Error generalization:

Ant.on('Error', err => { ... })

Error will fire on any error. If error caused during user's scenario (chat_error), error will have chat_id extra field.

Statuses

Set status for user:

await Ant.status(id, 'my_status');

And add listener for this status:

Ant.add('photo', 'my_status', (chat_id, photo) => { ... })

First argument is user interaction type, second - our status, third - callback.
Callback will invoke every time when user with this status send photo to bot.
Full list of available types and callbacks you can check here.

Commands

Add command handlers using Ant.command:

Ant.command(command, (chat_id, params, message) => { ... })

Command may contain / if needed (example: /start). Callback will invoke every time when user send this command to chat. Status will be ignored (works with any user's status).

Ant.command support url params for commant that will returns as params in callback. Empty object will returns if params not provided.
For example:

| User input | params value | |------------|----------------| | /cmd | {} | | /cmd?item=apple&amount=2 | { item: 'apple', amount: '2' } |

Notice: all param values are strings. You need to parse params by youself if you need to support other types in command params.

message is native API response (see Telegram.Message).

Masks

You can use multi-leveled statuses using level separator (: by default). It can be changed using maskSeparator field in initial config.
For example:

await Ant.status(chat_id, 'buy:fruit:apple')

Provided status has 3 levels: action (buy), category (fruit), item (apple) and can be used during user interaction with shopping cart.
You not need to set listeners using Ant.add for each item on third level. You can use mask (*):

// Mask value (item, in our case) will be provided as third callback parameter.
Ant.add('message', 'buy:fruit:*', (chat_id, text, item) => {
    console.log(item) // apple
})

Callback will invoke for any text message send by user with any item in status.

Builders

See Ant.Types

Ant:Telegram simplifies api methods usage with builders.
Let's check an example:

await Ant.api.sendMessage(chat_id, 'Am I cool?', new Ant.Types.InlineKeyboard([
    [ new Ant.Types.InlineButton('Yes, sure!', 'yes') ],
    [ new Ant.Types.InlineButton('No-no-no', 'no') ]
]))

Here we are using builders instead of define options object.
This code will send text message with two inline buttons:

Inline buttons, callback data handling

Using builders you can define callback_data type and data directly (second and third parameter in Ant.Types.InlineButton).
Example:

await Ant.api.sendMessage(chat_id, 'Click button below for getting gift', Ant.Types.InlineKeyboard([
    [ Ant.Types.InlineButton('Click!', 'gift', { id: 3 }) ],
]))

It will send test message with inline button that have gift type and data.
How to handle it? Use known Ant.add handler!

Ant.add('callback_query', 'gift', async (chat_id, data, message_id) => {
    console.log(data) // { id: 3 }
    await Ant.api.sendMessage(chat_id, `🎁 Here your gift with id=${data.id}`)
})

Callback will get data from inline buttons with pointed type:

Notice: Ant:Telegram Ant.Types.InlineKeyboard builder add callback_data to message.
callback_data is stringified JSON-string that looks like {t: type, d: data} and have 64 character length limit (see Telegram API docs).
Knowing it, your both type string and data must be at total less then 55 characters. API error (error event) will return otherwise.

Config

Ant:Telegram init config contain next fields:

| field | type | description | |-------|------|-------------| | setStatus | | See basic usage | getStatus | | See basic usage | maskSeparator | string | See masks | useWebhook | boolean | See webhook and polling

Webhook and Polling

Ant:Telegram use long-polling for communicate with Telegram API by default.
If you need use webhook instead of long-polling, follow next steps:

1. Pass useWebhook to Ant:Telegram options

const Ant = new AntTelegram(token, { useWebhook: true, ... })

2. Set webhook url using API setWebHook method:

await Ant.api.setWebHook(url, options)

Now your webhook is ready to receive incoming messages.

Examples

• Todo List Bot - simple todos manager.