Yata (Yet another Telegram API)
A lightweight library for communication with the Telegram Bot Api.
To create a bot and get an api token, call the @BotFather.
TL;DR
npm install --save yata
const yata = // Polling is NOT supported at the momentconst bot = token: BOT_API_TOKEN webhook: url: YOUR_DOMAIN // send a message// for available methods see here: https://core.telegram.org/bots/api#available-methodsbot // listen to messagesbot // pattern also work// imagine someone writes "@MyBot is so much cooler than yours"bot // multiple choicebot // every messagebot // in case you dont use arrow functions you can also use `this` which equals `bot`bot
Modify messages before they hit your regular code
// modify the messagebot // load stuff async// if you dont like how hacky this is, scroll down to "Sessions"bot // cancel the requestbot
Events
Beside the text there are many update and message events you can bind to. Message events get passed a message and update events the content of its update update.
To bind to an update event use bot.onUpdate(updateType, handler)
or bot.on(updateType, handler, 'update')
.
Same goes for a message event: bot.onMessage(messageType, handler)
or bot.on(updateType, handler, 'message')
.
Update-Events
- message
- edited_message
- channel_post
- edited_channel_post
- inline_query
- chosen_inline_result
- callback_query
- shipping_query
- pre_checkout_query
Message-Events
Literally anything you can send via telegram
- 'text', 'audio', 'document', 'game', 'photo', 'sticker', 'video', 'voice', 'video_note',
- 'contact', 'location', 'venue', 'new_chat_members', 'left_chat_member', 'new_chat_title',
- 'new_chat_photo', 'delete_chat_photo', 'group_chat_created', 'supergroup_chat_created',
- 'channel_chat_created', 'migrate_to_chat_id', 'migrate_from_chat_id', 'pinned_message',
- 'invoice', 'successful_payment'
Options
You can pass other options to the yata constructor
log: false
or a function which has the same signatur asconsole.log(...args)
(default)token:
Your API tokenwebhook {
url
: Your domainhost: 0.0.0.0
port: 443
key
: Needed for https servercert
: Needed for https serverallowed_updates: []
, Specifies which updates are pushed to your endpoint (see Update-Events for possible values)max_connections: 40
open: true
, autoopens the websocket*server
: See below**
}
* In case you disable the autoopen feature you need to start it manually with bot.setupWebhook()
** When you pass true
, its assumed that you setup the endpoint yourself (which is yourdomain.example/API_TOKEN
).
To pass an update into the library call bot.updateState(jsonbody)
This is only useful when you use the server for other things as well (e.g. a website made with express)
API
const bot = ...
bot.call(apiMethod, params, pluginoptions)
Calls the specified method of the api with the given params. Returns a promise which resolves to the result or rejects with an error.
You can see all methods at the telegram api doc: https://core.telegram.org/bots/api#available-methods
bot.setErrorHandler(fn)
Whenever a bot.call()
failes you can of course catch the rejected promise. However sometimes its useful to have a global handler which is called when a call
is not successful.
setErrorHandler
allows that. The function passed needs the signature (method, params, response)
bot.setupWebhook()
Only needed when you disable the open
option of the webhook. Call it, when your server is ready for incoming messages.
Example:
const router = router router
bot.mod(handler)
Add a method which is called on every update. Note it is first-come first-serve. So the mods are executed in the order in which you added them. You can do asyncronous operations in the mod method by returning a Promise. However always resolve to the update variable which was passed:
bot
bot.plugin(handler)
Plugins let you alter requests before they are send out. A plugin function is called with options = { method, params, plugin }
(every argument passed to call
) and needs to return an object of the same format.
This way you can easily add functionality e.g. asking the user for something:
const asks = {} bot bot bot bot
bot.on(event, handler, type = 'text')
You can bind events to update
, message
and text
. Update-Events have the names specified above, Message-Events are listed here.
A text event can be anything the user writes to the bot (thats why this is all seperated because a user could just write channel_post
which would otherwise trigger the message event channel_post
).
bot.onUpdate, bot.onMessage, bot.onText
Shortcuts for on(event, handler, update||message||text)