A simple LUA Library for the Telegram Bot API
Made with ❤️ by @cosmonawt
If you have questions, want to show off your bots or just chat about bot development, feel free to join the group I created.
- Finally finished changes of Telegram Bot API 2.0
- Implemented changes of Bot API 2.1 (also why I stayed with 2.1 version tag)
- Code is still completely untested, but proper tests should be coming soon
- Added changes of Telegram Bot API 2.0
- This update is still not ready, hence the alpha tag
editMessageText,editMessageCaption,editMessageReplyMarkupare not yet fully ready.- Important: Renamed
onMessageReceivetoonTextReceive - Created a discussiongroup you can join to ask questions.
- Added Library Extension which includes an internal update and callback handler and several callback functions which can be overridden.
- Added file
bot-example.luawith examples on how to use the new Library Extension. - Minor bug fixes
- Added
disable_notificationargument to all sending methods to enable silent messages - Added
captionargument tosendDocument()
- Initial release v1.0-alpha
To install this module, place it inside the same folder your bot is located.
This modules requires luasec to work.
You can easily install it with luarocks using luarocks install luasec.
You will also need a Module for JSON en- and decoding, which can be found here.
Simply place it in the lua-telegram-bot Folder.
To use this module, import it into your bot like this:
local bot, extension = (require "lua-bot-api").configure(token)Include your bot token as parameter for configure().
At the moment, only getUpdates method (aka polling) is supported, no webhooks.
The bot Table exports variables and functions which return the following return values.
The extension Table exports several callback functions as well as an update handler. Check Library Extension for more information.
All functions return a table as received from the server if called successfully as their first return value.
This does not mean the request was successful, for example in case of a bad offset in getUpdates().
A function returns nil and an error description if it was wrongly called (missing parameters).
idusernamefirst_namegetMe()getUpdates([offset] [,limit] [,timeout])sendMessage(chat_id, text [,parse_mode] [,disable_web_page_preview] [,disable_notification] [,reply_to_message_id] [,reply_markup])forwardMessage(chat_id, from_chat_id [,disable_notification], message_id)sendPhoto(chat_id, photo [,caption] [,disable_notification] [,reply_to_message_id] [,reply_markup])sendAudio(chat_id, audio, duration [,performer] [,title] [,disable_notification] [,reply_to_message_id] [,reply_markup])sendDocument(chat_id, document [,caption] [,disable_notification] [,reply_to_message_id] [,reply_markup])sendSticker(chat_id, sticker [,disable_notification] [,reply_to_message_id] [,reply_markup])sendVideo(chat_id, video [,duration] [,caption] [,disable_notification] [,reply_to_message_id] [,reply_markup])sendVoice(chat_id, voice [,duration] [,disable_notification] [,reply_to_message_id] [,reply_markup])sendLocation(chat_id, latitude, longitude [,disable_notification] [,reply_to_message_id] [,reply_markup])sendChatAction(chat_id, action)getUserProfilePhotos(user_id [,offset] [,limit])getFile(file_id)answerInlineQuery(inline_query_id, results [,cache_time] [,is_personal] [,next_offset])answerCallbackQuery(callback_query_id, text [, show_alert])kickChatMember(chat_id, user_id)unbanChatMember(chat_id, user_id)editMessageText(chat_id, message_id, inline_message_id, text [, parse_mode] [, disable_web_page_preview] [, reply_markup])editMessageCaption(chat_id, message_id, inline_message_id, caption [, reply_markup])editMessageReplyMarkup(chat_id, message_id, inline_message_id [, reply_markup])getChat(chat_id)leaveChat(chat_id)getChatAdministrators(chat_id)getChatMembersCount(chat_id)getChatMember(chat_id, user_id)downloadFile(file_id [,download_path])- Downloads file from Telegram Servers.
download_pathis an optional path where the file can be saved. If not specified, it will be saved in/downloads/<filenameByTelegram>. In both cases make sure the path already exists, since LUA can not create folders without additional modules.
generateReplyKeyboardMarkup(keyboard [,resize_keyboard] [,one_time_keyboard] [,selective])- Generates a
ReplyKeyboardMarkupof typereply_markupwhich can be sent optionally in other functions such assendMessage(). - Displays the custom
keyboardon the receivers device.
generateReplyKeyboardHide([hide_keyboard] [,selective])- Generates a
ReplyKeyboardHideof typereply_markupwhich can be sent optionally in other functions such assendMessage(). - Forces to hide the custom
keyboardon the receivers device. hide_keyboardcan be left out, as it is alwaystrue.
generateForceReply([force_reply] [,selective])- Generates a
ForceReplyof typereply_markupwhich can be sent optionally in other functions such assendMessage(). - Forces to reply to the corresponding message from the receivers device.
force_replycan be left out, as it is alwaystrue.
The Library extension was added to help developers focus on the things that actually matter in a bot: It's logic. It offers serveral callback functions which can be overridden to provide the wanted logic.
To use the extension, simply add another table variable to the initial require call like so:
local bot, extension = require("lua-bot-api").configure(token)The extension Table now stores the following functions:
run()- Provides an update handler which automatically fetches new updates from the server and calls the respective callback functions.
onUpdateReceive(update)- Is called every time an update, no matter of what type, is received.
onMessageReceive(message)- Is called every time a text message is received.
onPhotoReceive(message)- Is called every time a photo is received.
onAudioReceive(message)- Is called every time audio is received.
onDocumentReceive(message)- Is called every time a document is received.
onStickerReceive(message)- Is called every time a sticker is received.
onVideoReceive(message)- Is called every time a video is received.
onVoiceReceive(message)- Is called every time a voice message is received.
onContactReceive(message)- Is called every time a contact is received.
onLocationReceive(message)- Is called every time a location is received.
onLeftChatParticipant(message)- Is called every time a member or the bot itself leaves the chat.
onNewChatParticipant(message)- Is called when a member joins a chat or the bot itself is added.
onNewChatTitle(message)- Is called every time the chat title is changed.
onNewChatPhoto(message)- Is called every time the chat photo is changed.
onDeleteChatPhoto(message)- Is called every time the chat photo is deleted.
onGroupChatCreated(message)- Is called every time a group chat is created directly with the bot.
onSupergroupChatCreated(message)onChannelChatCreated(message)onMigrateToChatId(message)- Is called every time a group is upgraded to a supergroup.
onMigrateFromChatId(message)onInlineQueryReceive(inlineQuery)- Is called every time an inline query is received.
onChosenInlineQueryReceive(chosenInlineQuery)- Is called every time a chosen inline query result is received.
onUnknownTypeReceive(unknownType)- Is called every time when an unknown type is received.
In order to provide your own desired behaviour to these callback functions, you need to override them, like so, for example:
local bot, extension = require("lua-bot-api").configure(token)
extension.onMessageReceive = function (message)
-- Your own desired behaviour here
end
extension.run(limit, timeout)
You can now use extension.run() to use the internal update handler to fetch new updates from the server and call the representive functions.
It lets you pass the same limit and timeout parameters as in getUpdates() to control the handlers behaviour without rewriting it.
You can even override extension.run() with your own update handler.
See bot-example.lua for some examples on how to use extension functions.