lua-telegram-bot

A simple LUA Library for the Telegram Bot API

Important

This library is not under active development anymore.

Changelog

May 26 2016 - v2.1beta

• 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

Apr 20 2016 - v2.1alpha

• Added changes of Telegram Bot API 2.0
• This update is still not ready, hence the alpha tag
• editMessageText, editMessageCaption, editMessageReplyMarkup are not yet fully ready.
• Important: Renamed onMessageReceive to onTextReceive
• Created a discussiongroup you can join to ask questions.

Mar 27 2016 - v2.0

• Added Library Extension which includes an internal update and callback handler and several callback functions which can be overridden.
• Added file bot-example.lua with examples on how to use the new Library Extension.
• Minor bug fixes

Feb 28 2016 - v1.1

• Added disable_notification argument to all sending methods to enable silent messages
• Added caption argument to sendDocument()

Jan 22 2016 - v1.0

• Initial release v1.0-alpha

Installing

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.

Using

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.

Return values

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).

Available Variables

id

username

first_name

Available Functions

getMe()

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)

Inline Mode functions

answerInlineQuery(inline_query_id, results [,cache_time] [,is_personal] [,next_offset])

answerCallbackQuery(callback_query_id, text [, show_alert])

Bot API 2.0 functions

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])

Bot API 2.1 functions

getChat(chat_id)

leaveChat(chat_id)

getChatAdministrators(chat_id)

getChatMembersCount(chat_id)

getChatMember(chat_id, user_id)

Helper functions:

downloadFile(file_id [,download_path])

• Downloads file from Telegram Servers.
• download_path is 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 ReplyKeyboardMarkup of type reply_markup which can be sent optionally in other functions such as sendMessage().
• Displays the custom keyboard on the receivers device.

generateReplyKeyboardHide([hide_keyboard] [,selective])

• Generates a ReplyKeyboardHide of type reply_markup which can be sent optionally in other functions such as sendMessage().
• Forces to hide the custom keyboard on the receivers device.
• hide_keyboard can be left out, as it is always true.

generateForceReply([force_reply] [,selective])

• Generates a ForceReply of type reply_markup which can be sent optionally in other functions such as sendMessage().
• Forces to reply to the corresponding message from the receivers device.
• force_reply can be left out, as it is always true.

Library Extension

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.

Available Functions

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.

onTextReceive(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.

Using extension functions

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.onTextReceive = 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.