README
Ant:Telegram
Tiny but powerful framework for Telegram chat bots.
Also check out ants for other messengers: AntViber, AntMessenger.
List of content
About:
- Basic features
- Instalation
- Basic usage
- Ant anatomy
- Inline buttons, callback data handling
- Wildcards
- 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
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>;
Notice: getStatus
must returns null
or undefined
when called for user for a first time (when user not exist and status not found).
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):
... using command handlers:
Ant.command('/start', async chat_id => {
await Ant.bot.sendMessage(chat_id, 'Hi!');
})
... or onStart
method:
Ant.onStart((chat_id, value, message) => {
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.
Or add native listener:
Ant.native('my_status', message => { ... })
Native listener pass to callback parsed Telegram API response for any type of message.
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).
Notice: /start
command using deep linking with params will send message not in url format, so you need to use Ant.onStart
method to handle it.
For example:
/**
* @description
* Link t.me/yourbot?start=reflink
* will send message "/start reflink"
* which isn't in url format. So you need to use method below.
*/
Ant.onStart((chat_id, value, message) => {
console.log(value); // -> reflink
});
Link | value |
---|---|
t.me/yourbot | "" |
t.me/yourbot?start=reflink | "reflink" |
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 Ant.add callback parameter or second Ant.native parameter
Ant.add('message', 'buy:fruit:*', (chat_id, text, item) => {
console.log(item) // apple
})
// Or
Ant.native('buy:fruit:*', (message, 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.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:
Notice: if you are working in Typescript environment you need to use Ant.sendMessage
method (outside api
). In javascript project feel free to use either Ant.sendMessage
or Ant.api.sendMessage
.
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:
Ant:Telegram automatically answer on callback queries via Ant.api.answerInlineQuery
method (API reference) to hide loading spinner from inline button. You should disable it via callbackQueryAutoAnswer
config value if you need to answer it on your own (for displaing toast notification as option). Also you can add notification text to auto-answer (no notifications by default).
Ant.add('callback_query', ...)
listner will handle only queries created with Builders. For handling native queries (sent witout Builders) you need to use API events via Ant.api.on('callback_query')
.
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 called otherwise.
Wildcards
Ant:Telegram support next wildcards:
Type wildcard
You can set wildcard listener for provided status using *
that will be called after each user's message (type doesn't matter).
Native API message (Telegram.Message
) will be passed as parameter.
Let's check an example:
Ant.add('*', 'your_status', message => {
console.log(message) // Telegram.Message here!
})
Notice: from v0.1.9
Ant:Telegram contains Ant.native
method which do the same (allow to get message of any type for passed status) but with wildcards support.
Config
Ant:Telegram init config contain next params:
field | type | default | description |
---|---|---|---|
setStatus |
Promise<any> |
Required param | See basic usage |
getStatus |
Promise<string> |
Required param | See basic usage |
maskSeparator |
string |
: |
See masks |
useWebhook |
boolean |
false |
See webhook and polling |
callbackQueryAutoAnswer.enable |
boolean |
true |
See Inline buttons |
callbackQueryAutoAnswer.text |
string |
null |
See Inline buttons |
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:
- Pass
useWebhook
to Ant:Telegram options
const Ant = new AntTelegram(token, { useWebhook: true, ... })
- 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.