A Fancy, Higher-Level Wrapper for Telegram Bot API
Built on top of node-telegram-bot-api.
$ npm install tgfancy --saveconst Tgfancy = require("tgfancy");
const bot = new Tgfancy(token, {
// all options to 'tgfancy' MUST be placed under the
// 'tgfancy' key, as shown below
tgfancy: {
option: "value",
},
});
bot.sendMessage(chatId, "text message");tgfancy is basically node-telegram-bot-api on steroids. Therefore, you MUST know how to work with node-telegram-bot-api before using this wrapper. tgfancy is a drop-in replacement!
tgfancy provides ALL the methods exposed by TelegramBot from node-telegram-bot-api. This means that all the methods from TelegramBot are available on Tgfancy. This also includes the constructor.
Here comes the fanciness
tgfancy adds the following fanciness:
Have a look at the API Reference.
Most of the features are enabled by default. Such a feature (enabled by default) is similar to doing something like:
const bot = new Tgfancy(token, {
tgfancy: {
feature: true, // 'true' to enable!
},
});Such a feature can be disabled like so:
const bot = new Tgfancy(token, {
tgfancy: {
feature: false, // 'false' to disable!
},
});If a feature allows more options, you may pass an object, instead of true,
like:
const bot = new Tgfancy(token, {
tgfancy: {
feature: { // feature will be enabled!
key: "value", // feature option
},
},
});See example at example/feature-toggled.js.
Using an internal queue, we can ensure messages are sent, to a specific chat, in order without having to implement the wait-for-response-to-send-next-message logic.
Feature option: orderedSending (see above)
For example,
bot.sendMessage(chatId, "first message");
bot.sendMessage(chatId, "second message");With tgfancy, you are guaranteed that "first message" will be sent
before "second message".
Fancied functions: [ "sendAudio", "sendDocument", "sendGame", "sendInvoice", "sendLocation", "sendMessage", "sendPhoto", "sendSticker", "sendVenue", "sendVideo", "sendVideoNote", "sendVoice", ]
An earlier discussion on this feature can be found here.
See example at example/queued-up.js.
The Tgfancy#sendMessage(chatId, message) automatically pages messages,
that is, if message is longer than the maximum limit of 4096 characters,
the message is split into multiple parts. These parts are sent serially,
one after the other.
The page number, for example [01/10], is prefixed to the text.
Feature option: textPaging (see above)
For example,
// 'veryLongText' is a message that contains more than 4096 characters
// Usually, trying to send this message would result in the API returning
// an error.
bot.sendMessage(chatId, veryLongText)
.then(function(messages) {
// 'messages' is an Array containing Message objects from
// the Telegram API, for each of the parts
console.log("message has been sent in multiple pages");
}).catch(function(error) {
console.error(error);
});Note: We do not support sending messages that'd result into more than 99 parts.
See example at example/paging-text.js.
Any request that encounters a 429 error i.e. rate-limiting error
will be retried after some time (as advised by the Telegram API or
1 minute by default).
The request will be retried for a number of times, until it succeeds or
the maximum number of retries has been reached
Feature option: ratelimiting (see above)
For example,
const bot = new Tgfancy(token, {
tgfancy: {
// options for this fanciness
ratelimiting: {
// number of times to retry a request before giving up
maxRetries: 10, // default: 10
// number of milliseconds to wait before retrying the
// request (if API does not advise us otherwise!)
timeout: 1000 * 60, // default: 60000 (1 minute)
// (optional) function invoked whenever this fanciness handles
// any ratelimiting error.
// this is useful for debugging and analysing your bot
// behavior
notify(methodName, ...args) { // default: undefined
// 'methodName' is the name of the invoked method
// 'args' is an array of the arguments passed to the method
// do something useful here
// ...snip...
},
// maximum number of milliseconds to allow for waiting
// in backoff-mode before retrying the request.
// This is important to avoid situations where the server
// can cause lengthy timeouts e.g. too long of a wait-time
// that is causes adverse effects on efficiency and performance.
maxBackoff: 1000 * 60 * 5, // default: 5 minutes
},
},
});Fancied functions: [ "addStickerToSet", "answerCallbackQuery", "answerInlineQuery", "answerPreCheckoutQuery", "answerShippingQuery", "createNewStickerSet", "deleteChatPhoto", "deleteChatStickerSet", "deleteMessage", "deleteStickerFromSet", "downloadFile", "editMessageCaption", "editMessageLiveLocation", "editMessageReplyMarkup", "editMessageText", "exportChatInviteLink", "forwardMessage", "getChat", "getChatAdministrators", "getChatMember", "getChatMembersCount", "getFile", "getFileLink", "getGameHighScores", "getStickerSet", "getUpdates", "getUserProfilePhotos", "kickChatMember", "leaveChat", "pinChatMessage", "promoteChatMember", "restrictChatMember", "sendAudio", "sendChatAction", "sendContact", "sendDocument", "sendGame", "sendInvoice", "sendLocation", "sendMediaGroup", "sendMessage", "sendPhoto", "sendSticker", "sendVenue", "sendVideo", "sendVideoNote", "sendVoice", "setChatDescription", "setChatPhoto", "setChatStickerSet", "setChatTitle", "setGameScore", "setStickerPositionInSet", "setWebHook", "stopMessageLiveLocation", "unbanChatMember", "unpinChatMessage", "uploadStickerFile", ]
An earlier discussion on this feature can be found here.
See example at example/ratelimited.js.
Any Github-flavoured Markdown emoji, such as :heart: can be replaced
automatically with their corresponding Unicode values. By default,
uses the node-emoji library (Go give a star!).
Disabled by default.
Feature option: emojification (see above)
For example,
const bot = new Tgfancy(token, {
tgfancy: {
emojification: true,
},
});
bot.sendMessage(chatId, "Message text with :heart: emoji")
.then(function(msg) {
// 'msg' is the Message sent to the chat
console.log(msg.text); // => "Message text with ❤️ emoji"
});However, it is possible to define a custom function used to perform
emojification. The function must have the signature,
emojify(text) and return the emojified text.
const bot = new Tgfancy(token, {
tgfancy: {
emojification: {
emojify(text) {
// emojify here
// ... snip ...
return emojifiedText;
},
},
},
});Fancied functions: ["sendMessage", "editMessageText"]
See example at example/emojified.js.
In addition to polling and web-hooks, this introduces another mechanism for fetching your updates: WebSocket. While currently it is not officially supported by Telegram, we have a bridge up and running that you can connect to for this purpose. Disabled by default.
Feature option: webSocket (see above)
For example,
const bot = new Tgfancy(token, {
tgfancy: {
webSocket: true,
},
});The current default bridge is at wss://telegram-websocket-bridge-qalwkrjzzs.now.sh and is being run by @GingerPlusPlus.
You can specify more options as so:
const bot = new Tgfancy(token, {
tgfancy: {
webSocket: {
// specify a custom URL for a different bridge
url: "wss://telegram-websocket-bridge-qalwkrjzzs.now.sh",
// immediately open the websocket
autoOpen: true,
},
},
});See example at example/web-socket.js.
The MIT License (MIT)
Copyright (c) 2016 GochoMugo mugo@forfuture.co.ke