{"id":13461893,"url":"https://github.com/GochoMugo/tgfancy","last_synced_at":"2025-03-24T23:31:59.811Z","repository":{"id":49740399,"uuid":"72006242","full_name":"GochoMugo/tgfancy","owner":"GochoMugo","description":"A Fancy, Higher-Level Wrapper for Telegram Bot API","archived":false,"fork":false,"pushed_at":"2024-05-23T05:28:43.000Z","size":170,"stargazers_count":187,"open_issues_count":8,"forks_count":16,"subscribers_count":8,"default_branch":"master","last_synced_at":"2024-10-29T10:03:10.433Z","etag":null,"topics":["bot-api","telegram"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GochoMugo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-10-26T13:33:14.000Z","updated_at":"2024-10-26T08:32:38.000Z","dependencies_parsed_at":"2024-05-23T05:43:50.218Z","dependency_job_id":null,"html_url":"https://github.com/GochoMugo/tgfancy","commit_stats":{"total_commits":80,"total_committers":4,"mean_commits":20.0,"dds":0.03749999999999998,"last_synced_commit":"fd658e51dd19dc4751dfb551d9b83928ef36497e"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GochoMugo%2Ftgfancy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GochoMugo%2Ftgfancy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GochoMugo%2Ftgfancy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GochoMugo%2Ftgfancy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GochoMugo","download_url":"https://codeload.github.com/GochoMugo/tgfancy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244885533,"owners_count":20526293,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bot-api","telegram"],"created_at":"2024-07-31T12:00:26.675Z","updated_at":"2025-03-24T23:31:59.790Z","avatar_url":"https://github.com/GochoMugo.png","language":"JavaScript","readme":"# tgfancy\n\n\u003e A Fancy, Higher-Level Wrapper for Telegram Bot API\n\u003e\n\u003e Built on top of [node-telegram-bot-api][api].\n\n[![Version](https://img.shields.io/npm/v/tgfancy.svg)](https://www.npmjs.com/package/tgfancy)\n [![Supported Node.js Versions](https://img.shields.io/node/v/tgfancy.svg)](https://www.npmjs.com/package/tgfancy)\n\n\n## installation:\n\n```bash\n$ npm install tgfancy --save\n```\n\n\n## sample usage:\n\n```js\nconst Tgfancy = require(\"tgfancy\");\nconst bot = new Tgfancy(token, {\n    // all options to 'tgfancy' MUST be placed under the\n    // 'tgfancy' key, as shown below\n    tgfancy: {\n        option: \"value\",\n    },\n});\n\nbot.sendMessage(chatId, \"text message\");\n```\n\n\n## introduction:\n\n**tgfancy is basically [node-telegram-bot-api][api] on steroids.**\nTherefore, you **MUST** know how to work with [node-telegram-bot-api][api]\nbefore using this wrapper. **tgfancy** is a **drop-in replacement**!\n\n**tgfancy** provides **ALL** the methods exposed by [**TelegramBot**][api-bot]\nfrom [node-telegram-bot-api][api]. This means that all the methods from\n**TelegramBot** are available on **Tgfancy**. This also includes the\nconstructor.\n\n\n## fanciness:\n\n\u003e Here comes the fanciness\n\n**tgfancy** adds the following fanciness:\n\n* [Ordered Sending](#ordered-sending)\n* [Text Paging](#text-paging)\n* [Rate-Limiting](#ratelimiting)\n* [Emojification](#emojification)\n* [Fetching Updates via WebSocket](#websocket-updates)\n\nHave a look at the [API Reference][doc-api].\n\n[doc-api]:https://github.com/GochoMugo/tgfancy/tree/master/doc/api.md\n\n\n\u003ca name=\"feature-options\"\u003e\u003c/a\u003e\n### feature options:\n\nMost of the features are **enabled by default**. Such a feature (enabled by\ndefault) is similar to doing something like:\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        feature: true,  // 'true' to enable!\n    },\n});\n```\n\nSuch a feature can be **disabled** like so:\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        feature: false, // 'false' to disable!\n    },\n});\n```\n\nIf a feature allows more options, you may pass an object, instead of `true`,\nlike:\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        feature: {          // feature will be enabled!\n            key: \"value\",   // feature option\n        },\n    },\n});\n```\n\nSee example at `example/feature-toggled.js`.\n\n\n---\n\n\n\u003ca name=\"ordered-sending\"\u003e\u003c/a\u003e\n### Ordered sending:\n\nUsing an internal queue, we can ensure messages are sent, *to a specific\nchat*, in order without having to implement the\nwait-for-response-to-send-next-message logic.\n\n**Feature option:** `orderedSending` (see [above](#feature-options))\n\nFor example,\n\n```js\nbot.sendMessage(chatId, \"first message\");\nbot.sendMessage(chatId, \"second message\");\n```\n\nWith **tgfancy**, you are guaranteed that `\"first message\"` will be sent\n**before** `\"second message\"`.\n\nFancied functions: `[\n    \"sendAudio\",\n    \"sendDocument\",\n    \"sendGame\",\n    \"sendInvoice\",\n    \"sendLocation\",\n    \"sendMessage\",\n    \"sendPhoto\",\n    \"sendSticker\",\n    \"sendVenue\",\n    \"sendVideo\",\n    \"sendVideoNote\",\n    \"sendVoice\",\n]`\n\nAn earlier discussion on this feature can be found [here][docs-queue-1].\nSee example at `example/queued-up.js`.\n\n[docs-queue-1]:https://github.com/yagop/node-telegram-bot-api/issues/192\n\n\n---\n\n\n\u003ca name=\"text-paging\"\u003e\u003c/a\u003e\n### Text paging:\n\nThe `Tgfancy#sendMessage(chatId, message)` automatically pages messages,\nthat is, if `message` is longer than the maximum limit of 4096 characters,\nthe `message` is split into multiple parts. These parts are sent serially,\none after the other.\n\nThe page number, for example `[01/10]`, is prefixed to the text.\n\n**Feature option:** `textPaging` (see [above](#feature-options))\n\nFor example,\n\n```js\n// 'veryLongText' is a message that contains more than 4096 characters\n// Usually, trying to send this message would result in the API returning\n// an error.\nbot.sendMessage(chatId, veryLongText)\n    .then(function(messages) {\n        // 'messages' is an Array containing Message objects from\n        // the Telegram API, for each of the parts\n        console.log(\"message has been sent in multiple pages\");\n    }).catch(function(error) {\n        console.error(error);\n    });\n```\n\n**Note:** We do **not** support sending messages that'd result into more\nthan 99 parts.\n\nSee example at `example/paging-text.js`.\n\n---\n\n\n\u003ca name=\"ratelimiting\"\u003e\u003c/a\u003e\n### Rate-Limiting:\n\nAny request that encounters a `429` error i.e. rate-limiting error\nwill be retried after some time (as advised by the Telegram API or\n1 minute by default).\nThe request will be retried for a number of times, until it succeeds or\nthe maximum number of retries has been reached\n\n**Feature option:** `ratelimiting` (see [above](#feature-options))\n\nFor example,\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        // options for this fanciness\n        ratelimiting: {\n            // number of times to retry a request before giving up\n            maxRetries: 10,         // default: 10\n            // number of milliseconds to wait before retrying the\n            // request (if API does not advise us otherwise!)\n            timeout: 1000 * 60,     // default: 60000 (1 minute)\n            // (optional) function invoked whenever this fanciness handles\n            // any ratelimiting error.\n            // this is useful for debugging and analysing your bot\n            // behavior\n            notify(methodName, ...args) {   // default: undefined\n                // 'methodName' is the name of the invoked method\n                // 'args' is an array of the arguments passed to the method\n                // do something useful here\n                // ...snip...\n            },\n            // maximum number of milliseconds to allow for waiting\n            // in backoff-mode before retrying the request.\n            // This is important to avoid situations where the server\n            // can cause lengthy timeouts e.g. too long of a wait-time\n            // that is causes adverse effects on efficiency and performance.\n            maxBackoff: 1000 * 60 * 5,      // default: 5 minutes\n        },\n    },\n});\n```\n\nFancied functions: `[\n    \"addStickerToSet\",\n    \"answerCallbackQuery\",\n    \"answerInlineQuery\",\n    \"answerPreCheckoutQuery\",\n    \"answerShippingQuery\",\n    \"createNewStickerSet\",\n    \"deleteChatPhoto\",\n    \"deleteChatStickerSet\",\n    \"deleteMessage\",\n    \"deleteStickerFromSet\",\n    \"downloadFile\",\n    \"editMessageCaption\",\n    \"editMessageLiveLocation\",\n    \"editMessageReplyMarkup\",\n    \"editMessageText\",\n    \"exportChatInviteLink\",\n    \"forwardMessage\",\n    \"getChat\",\n    \"getChatAdministrators\",\n    \"getChatMember\",\n    \"getChatMembersCount\",\n    \"getFile\",\n    \"getFileLink\",\n    \"getGameHighScores\",\n    \"getStickerSet\",\n    \"getUpdates\",\n    \"getUserProfilePhotos\",\n    \"kickChatMember\",\n    \"leaveChat\",\n    \"pinChatMessage\",\n    \"promoteChatMember\",\n    \"restrictChatMember\",\n    \"sendAudio\",\n    \"sendChatAction\",\n    \"sendContact\",\n    \"sendDocument\",\n    \"sendGame\",\n    \"sendInvoice\",\n    \"sendLocation\",\n    \"sendMediaGroup\",\n    \"sendMessage\",\n    \"sendPhoto\",\n    \"sendSticker\",\n    \"sendVenue\",\n    \"sendVideo\",\n    \"sendVideoNote\",\n    \"sendVoice\",\n    \"setChatDescription\",\n    \"setChatPhoto\",\n    \"setChatStickerSet\",\n    \"setChatTitle\",\n    \"setGameScore\",\n    \"setStickerPositionInSet\",\n    \"setWebHook\",\n    \"stopMessageLiveLocation\",\n    \"unbanChatMember\",\n    \"unpinChatMessage\",\n    \"uploadStickerFile\",\n]`\n\nAn earlier discussion on this feature can be found [here][docs-ratelimiting-1].\nSee example at `example/ratelimited.js`.\n\n[docs-ratelimiting-1]:https://github.com/GochoMugo/tgfancy/issues/4\n\n\n---\n\n\n\u003ca name=\"emojification\"\u003e\u003c/a\u003e\n### Emojification:\n\nAny Github-flavoured Markdown emoji, such as `:heart:` can be replaced\nautomatically with their corresponding Unicode values. By default,\nuses the [node-emoji][emoji] library (Go give a star!).\n**Disabled by default**.\n\n**Feature option:** `emojification` (see [above](#feature-options))\n\nFor example,\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        emojification: true,\n    },\n});\nbot.sendMessage(chatId, \"Message text with :heart: emoji\")\n    .then(function(msg) {\n        // 'msg' is the Message sent to the chat\n        console.log(msg.text); // =\u003e \"Message text with ❤️ emoji\"\n    });\n```\n\nHowever, it is possible to define a custom function used to perform\nemojification. The function **must** have the signature,\n`emojify(text)` and return the emojified text.\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        emojification: {\n            emojify(text) {\n                // emojify here\n                // ... snip ...\n                return emojifiedText;\n            },\n        },\n    },\n});\n```\n\nFancied functions: `[\"sendMessage\", \"editMessageText\"]`\n\nSee example at `example/emojified.js`.\n\n[emoji]:https://github.com/omnidan/node-emoji#readme\n\n\n---\n\n\n\u003ca name=\"websocket-updates\"\u003e\u003c/a\u003e\n### Fetching Updates via WebSocket:\n\nIn addition to polling and web-hooks, this introduces another mechanism\nfor fetching your updates: **WebSocket**. While currently it is **not**\nofficially supported by Telegram, we have a *bridge* up and running\nthat you can connect to for this purpose. **Disabled by default**.\n\n**Feature option:** `webSocket` (see [above](#feature-options))\n\nFor example,\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        webSocket: true,\n    },\n});\n```\n\nThe current default bridge is at\n*wss://telegram-websocket-bridge-qalwkrjzzs.now.sh* and is being run by\n[@GingerPlusPlus][gingerplusplus].\n\nYou can specify more options as so:\n\n```js\nconst bot = new Tgfancy(token, {\n    tgfancy: {\n        webSocket: {\n            // specify a custom URL for a different bridge\n            url: \"wss://telegram-websocket-bridge-qalwkrjzzs.now.sh\",\n            // immediately open the websocket\n            autoOpen: true,\n        },\n    },\n});\n```\n\nSee example at `example/web-socket.js`.\n\n[gingerplusplus]:https://github.com/GingerPlusPlus\n\n\n---\n\n\n## license:\n\n**The MIT License (MIT)**\n\nCopyright (c) 2016 GochoMugo \u003cmugo@forfuture.co.ke\u003e\n\n\n[api]: https://github.com/yagop/node-telegram-bot-api\n[api-bot]: https://github.com/yagop/node-telegram-bot-api#telegrambot\n","funding_links":[],"categories":["Libraries"],"sub_categories":["Node.js"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGochoMugo%2Ftgfancy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGochoMugo%2Ftgfancy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGochoMugo%2Ftgfancy/lists"}