telegram-bot-lua

A feature-filled Telegram bot API library written in Lua, created by Matt. This library includes functions that allow you to use any Telegram bot API method. It is frequently updated and also includes extensive tools to reduce the amount of code needed to perform more elaborate and complex actions.

This library was written to complement the "mattata" project, allowing anybody to create their own Telegram bot with little coding knowledge needed (that is, except a basic knowledge of Lua and the inspiration provided by @mattatabot and this library).

The licensing situation is currently under investigation, but don't panic, it'll get resolved cleanly.

Installation

To install this library, make sure you have Lua 5.3 and LuaRocks installed, then run luarocks install telegram-bot-lua. That's it! Now you just need to include it in your bot's source code, with the configure function passing your bot auth token (the one you received from the BotFather), like this:

local api = require('telegram-bot-lua.core').configure('bot123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11')

Now you're ready to create your own bot!

Update Handling

The Telegram bot API returns updates in the form of a JSON-encoded object. This object has several different types of updates, and there is a function for each one - they are all optional, but if you didn't use any of them then your bot wouldn't do anything.

To handle messages (a.k.a. the update.message object), you need to use the api.on_message(message) function. The example shown below would iterate over every update.message object, and reply to messages that contain the text ping with the word pong:

function api.on_message(message)
    if message.text
    and message.text:match('ping')
    then
        api.send_message(
            message.chat.id,
            'pong'
        )
    end
end

You'll notice I've used another function from the telegram-bot-lua library we included as api. There is a function for every method in the Telegram bot API. Scroll down to see examples of method-binded functions.

To handle channel posts (a.k.a. the update.channel_post object), you need to use the api.on_channel_post(channel_post) function. The example shown below would iterate over every update.channel_post object, and reply to channel posts that contain the text ping with the word pong:

function api.on_channel_post(channel_post)
    if channel_post.text
    and channel_post.text:match('ping')
    then
        api.send_message(
            channel_post.chat.id,
            'pong'
        )
    end
end

The reason channel posts are handled in a different function to messages is because messages always contain an object containing information about the sender (a.k.a. update.message.from), whereas channel posts only hold this information if the Sign Messages option is enabled in the channel settings.

To handle edited messages (a.k.a. the update.edited_message object), you need to use the api.on_edited_message(edited_message) function. The example shown below would iterate over every update.edited_message object and reply to messages that have been edited to contain the text ping with the word pong:

function api.on_edited_message(edited_message)
    if edited_message.text
    and edited_message.text:match('ping')
    then
        api.send_message(
            edited_message.chat.id,
            'pong'
        )
    end
end

To handle edited channel posts (a.k.a. the update.edited_channel_post object), you need to use the api.on_edited_channel_post(edited_channel_post) function. The example shown below would iterate over every update.edited_channel_post object and reply to channel posts that have been edited to contain the text ping with the word pong:

function api.on_edited_channel_post(edited_channel_post)
    if edited_channel_post.text
    and edited_channel_post.text:match('ping')
    then
        api.send_message(
            edited_channel_post.chat.id,
            'pong'
        )
    end
end

To handle inline queries (a.k.a. the update.inline_query object), you need to use the api.on_inline_query(inline_query) function. The example shown below would iterate over every update.inline_query object, and respond with an inline article:

function api.on_inline_query(inline_query)
    api.answer_inline_query(
        inline_query.id,
        api.inline_result()
        :type('article')
        :id(1)
        :title('Title')
        :description('Description')
        :input_message_content(
            api.input_text_message_content('Message')
        )
    )
end

The api.inline_result() function is one of the many extensive tools this API offers - this particular one allows you to build inline results using Lua methods through metatables.

To handle chosen inline results (a.k.a. the update.chosen_inline_result object), you need to use the api.on_chosen_inline_result(chosen_inline_result) function. The example shown below would iterate over every update.chosen_inline_result object, and print the JSON-encoded object to the terminal, using the dkjson library:

function api.on_chosen_inline_result(chosen_inline_result)
    local json = require('dkjson')
    print(
        json.encode(chosen_inline_result)
    )
end

To handle callback queries (a.k.a. the update.callback_query object), you need to use the api.on_callback_query(callback_query) function. The example shown below would iterate over every update.callback_query object, and send an alert to the person who pressed the inline keyboard button, containing their numerical ID:

function api.on_callback_query(callback_query)
    api.answer_callback_query(
        callback_query.id,
        callback_query.from.id
    )
end

To handle shipping queries (a.k.a. the update.shipping_query object), you need to use the api.on_shipping_query(shipping_query) function. The example shown below would iterate over every update.shipping_query object, and print its JSON-encoded version to the terminal:

function api.on_shipping_query(shipping_query)
    local json = require('dkjson')
    print(
        json.encode(shipping_query)
    )
end

To handle pre checkout queries (a.k.a. the update.pre_checkout_query object), you need to use the api.on_pre_checkout_query(pre_checkout_query) function. The example shown below would iterate over every update.pre_checkout_query object, and print its JSON-encoded version to the terminal:

function api.on_pre_checkout_query(pre_checkout_query)
    local json = require('dkjson')
    print(
        json.encode(pre_checkout_query)
    )
end

Although it's recommended to do so, you're not limited to handling specific update types through these functions – to do something with the original update object, use the function api.on_update(update). The example shown below would iterate over every update object, and print the update type to the terminal:

function api.on_update(update)
    if update.message
    then
        print('message')
    elseif update.edited_message
    then
        print('edited message')
    elseif update.channel_post
    then
        print('channel post')
    elseif update.edited_channel_post
    then
        print('edited channel post')
    elseif update.inline_query
    then
        print('inline query')
    elseif update.callback_query
    then
        print('callback query')
    elseif update.chosen_inline_result
    then
        print('chosen inline result')
    elseif update.shipping_query
    then
        print('shipping query')
    elseif update.pre_checkout_query
    then
        print('pre checkout query')
    else
        print('unknown update type')
    end
end

After these functions, you must use:

api.run()

This is what will run your bot!

API Methods

getMe

A simple function for testing your bot's auth token, using Telegram's getMe method. Requires no parameters.

api.get_me()

getUpdates

Use this function to receive incoming updates via long polling, using Telegram's getUpdates method.

api.get_updates(
    offset,
    limit,
    timeout,
    allowed_updates
)

sendMessage

Use this function to send text messages, using Telegram's sendMessage method.

api.send_message(
    chat_id,
    text,
    parse_mode,
    disable_web_page_preview,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

forwardMessage

Use this function to forward messages of any kind, using Telegram's forwardMessage method.

api.forward_message(
    chat_id,
    from_chat_id,
    disable_notification,
    message_id
)

sendPhoto

Use this function to send photos, using Telegram's sendPhoto method.

api.send_photo(
    chat_id,
    photo,
    caption,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendAudio

Use this function to send audio files, using Telegram's sendAudio method, if you want Telegram clients to display them in the music player. Your audio must be in the .mp3 format. Bots can currently send audio files of up to 50 MB in size, this limit may be changed in the future.

api.send_audio(
    chat_id,
    audio,
    caption,
    duration,
    performer,
    title,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendDocument

Use this function to send general files, using Telegram's sendDocument method. Bots can currently send files of any type of up to 50 MB in size, this limit may be changed in the future.

api.send_document(
    chat_id,
    document,
    caption,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendSticker

Use this function to send .webp stickers, using Telegram's sendSticker method.

api.send_sticker(
    chat_id,
    sticker,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendVideo

Use this function to send video files, using Telegram's sendVideo method. Telegram clients support .mp4 videos (other formats may be sent using sendDocument). Bots can currently send video files of up to 50 MB in size, this limit may be changed in the future.

api.send_video(
    chat_id,
    video,
    duration,
    width,
    height,
    caption,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendVoice

Use this function to send audio files, using Telegram's sendVoice method, if you want Telegram clients to display the file as a playable voice message. For this to work, your audio must be in an .ogg file encoded with OPUS (other formats may be sent as Audio or Document). Bots can currently send voice messages of up to 50 MB in size, this limit may be changed in the future.

api.send_voice(
    chat_id,
    voice,
    caption,
    duration,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendLocation

Use this function to send a location on a map, using Telegram's sendLocation method.

api.send_location(
    chat_id,
    latitude,
    longitude,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendVenue

Use this function to send information about a venue, using Telegram's sendVenue method.

api.send_venue(
    chat_id,
    latitude,
    longitude,
    title,
    address,
    foursquare_id,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendContact

Use this function to send phone contacts, using Telegram's sendContact method.

api.send_contact(
    chat_id,
    phone_number,
    first_name,
    last_name,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

sendChatAction

Use this function when you need to tell the user that something is happening on the bot's side, using Telegram's sendChatAction method. The status is set for 5 seconds or less (when a message arrives from your bot, Telegram clients clear its typing status).

api.send_chat_action(
    chat_id,
    action
)

getUserProfilePhotos

Use this function to get a list of profile pictures for a user, using Telegram's getUserProfilePhotos method.

api.get_user_profile_photos(
    user_id,
    offset,
    limit
)

getFile

Use this function to get basic info about a file and prepare it for downloading, using Telegram's getFile method. For the moment, bots can download files of up to 20MB in size. The file can then be downloaded via the link https://api.telegram.org/file/bot<token>/<file_path>, where <file_path> is taken from the response. It is guaranteed that the link will be valid for at least 1 hour. When the link expires, a new one can be requested by calling this method again, also using this function.

api.get_file(file_id)

kickChatMember

There are two functions that use this method. One of them kicks the user, and one of them bans the user. By kick, we mean a "soft-ban" - where the user is removed, and then instantly unbanned. A ban means the user cannot return to the group unless unbanned.

To kick a user, use:

api.kick_chat_member(
    chat_id,
    user_id
)

To ban a user, use:

api.ban_chat_member(
    chat_id,
    user_id
)

unbanChatMember

Use this function to unban a previously kicked user in a supergroup, using Telegram's unbanChatMember method. The user will not return to the group automatically, but will be able to join via link, etc. The bot must be an administrator in the group for this to work.

api.unban_chat_member(
    chat_id,
    user_id
)

restrictChatMember

Use this function to restrict a user in a supergroup, using Telegram's restrictChatMember method. The bot must be an administrator in the supergroup for this to work and must have the appropriate admin rights. Pass True for all boolean parameters to lift restrictions from a user.

api.restrict_chat_member(
    chat_id,
    user_id,
    until_date,
    can_send_messages,
    can_send_media_messages,
    can_send_other_messages,
    can_add_web_page_previews
)

promoteChatMember

Use this function to promote or demote a user in a supergroup or a channel, using Telegram's promoteChatMember method. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights. Pass False for all boolean parameters to demote a user.

api.promote_chat_member(
    chat_id,
    user_id,
    can_change_info,
    can_post_messages,
    can_edit_messages,
    can_delete_messages,
    can_invite_users,
    can_restrict_members,
    can_pin_messages,
    can_promote_members
)

exportChatInviteLink

Use this function to export an invite link to a supergroup or a channel, using Telegram's exportChatInviteLink method. The bot must be an administrator in the chat for this to work and must have the appropriate admin rights.

api.export_chat_invite_link(chat_id)

leaveChat

Use this function for your bot to leave a group, supergroup or channel, using Telegram's leaveChat method.

api.leave_chat(chat_id)

getChat

Use this function to get up to date information about the chat (current name of the user for one-on-one conversations, current username of a user, group or channel, etc.), using Telegram's getChat method.

api.get_chat(chat_id)

getChatAdministrators

Use this function to get a list of administrators in a chat, using Telegram's getChatAdministrators method. If the chat is a group or a supergroup and no administrators were appointed, only the creator will be returned.

api.get_chat_administrators(chat_id)

getChatMembersCount

Use this function to get the number of members in a chat, using Telegram's getChatMembersCount method.

api.get_chat_members_count(chat_id)

getChatMember

Use this function to get information about a member of a chat, using Telegram's getChatMember method.

api.get_chat_member(
    chat_id,
    user_id
)

answerCallbackQuery

Use this function to send answers to callback queries sent from inline keyboards, using Telegram's answerCallbackQuery method. The answer will be displayed to the user as a notification at the top of the chat screen or as an alert.

Alternatively, the user can be redirected to the specified Game URL. For this option to work, you must first create a game for your bot via the BotFather and accept the terms. Otherwise, you may use links like telegram.me/your_bot?start=XXXX that open your bot with a parameter.

api.answer_callback_query(
    callback_query_id,
    text,
    show_alert,
    url,
    cache_time
)

editMessageText

Use this function to edit text and game messages sent by the bot or via the bot (for inline bots), using Telegram's editMessageText method.

api.edit_message_text(
    chat_id,
    message_id,
    text,
    parse_mode,
    disable_web_page_preview,
    reply_markup,
    inline_message_id
)

editMessageCaption

Use this function to edit captions of messages sent by the bot or via the bot (for inline bots), using Telegram's editMessageCaption method.

api.edit_message_caption(
    chat_id,
    message_id,
    caption,
    reply_markup,
    inline_message_id
)

editMessageReplyMarkup

Use this function to edit only the reply markup of messages sent by the bot or via the bot (for inline bots), using Telegram's editMessageReplyMarkup method.

api.edit_message_reply_markup(
    chat_id,
    message_id,
    inline_message_id,
    reply_markup
)

answerInlineQuery

Use this function to send answers to an inline query, using Telegram's answerInlineQuery method. No more than 50 results per query are allowed.

api.answer_inline_query(
    inline_query_id,
    results,
    switch_pm_text,
    switch_pm_parameter,
    cache_time,
    is_personal,
    next_offset
)

sendInvoice

Use this function to send invoices, using Telegram's sendInvoice method.

api.send_invoice(
    chat_id,
    title,
    description,
    payload,
    provider_token,
    start_parameter,
    currency,
    prices,
    photo_url,
    photo_size,
    photo_width,
    photo_height,
    need_name,
    need_phone_number,
    need_email,
    need_shipping_address,
    is_flexible,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

answerShippingQuery

Use this function to reply to shipping queries using Telegram's answerShippingQuery method. If you sent an invoice requesting a shipping address and the parameter is_flexible was specified, the Bot API will send an Update with a shipping_query field to the bot.

api.answer_shipping_query(
    shipping_query_id,
    ok,
    shipping_options,
    error_message
)

sendGame

Use this function to send a game, using Telegram's sendGame method.

api.send_game(
    chat_id,
    game_short_name,
    disable_notification,
    reply_to_message_id,
    reply_markup
)

setGameScore

Use this function to set the score of the specified user in a game, using Telegram's setGameScore method.

api.set_game_score(
    chat_id,
    user_id,
    message_id,
    score,
    force,
    disable_edit_message,
    inline_message_id
)

getGameHighScores

Use this function to get data for high score tables, using Telegram's getGameHighScores method. Will return the score of the specified user and several of his neighbors in a game.

The method this function uses will currently return scores for the target user, plus two of his closest neighbors on each side. Will also return the top three users if the user and his neighbors are not among them. Please note that this behavior is subject to change.

api.get_game_high_scores(
    chat_id,
    user_id,
    message_id,
    inline_message_id
)

Building Inline Results

There are quite a few types of inline results:

• InlineQueryResultCachedAudio
• InlineQueryResultCachedDocument
• InlineQueryResultCachedGif
• InlineQueryResultCachedMpeg4Gif
• InlineQueryResultCachedPhoto
• InlineQueryResultCachedSticker
• InlineQueryResultCachedVideo
• InlineQueryResultCachedVoice
• InlineQueryResultArticle
• InlineQueryResultAudio
• InlineQueryResultContact
• InlineQueryResultGame
• InlineQueryResultDocument
• InlineQueryResultGif
• InlineQueryResultLocation
• InlineQueryResultMpeg4Gif
• InlineQueryResultPhoto
• InlineQueryResultVenue
• InlineQueryResultVideo
• InlineQueryResultVoice

There is one global function for building an inline result:

api.inline_result()

You then build the inline result using Lua methods. Each inline query result has a table of fields - some which are required, and some which are optional. The api.inline_result() function has a method for every single parameter, where the method name is the parameter name. To build an inline articule result, you'd use:

api.inline_result():type('article'):id(1):title('Title'):description('Description'):input_message_content(
    api.input_text_message_content('Text')
)

You'll notice a new function inside the input_message_content method - this is one of four functions for building the input_message_content parameter. This is optional, but it saves you from manually encoding it in JSON.

This object represents the content of a message to be sent as a result of an inline query. Telegram clients currently support the following 4 types:

• InputTextMessageContent
• InputLocationMessageContent
• InputVenueMessageContent
• InputContactMessageContent

To build the InputTextMessageContent object, use the function:

api.input_text_message_content(
    text,
    parse_mode,
    disable_web_page_preview
)

To build the InputLocationMessageContent object, use the function:

api.input_location_message_content(
    latitude,
    longitude
)

To build the InputVenueMessageContent object, use the function:

api.input_venue_message_content(
    latitude,
    longitude,
    title,
    address,
    foursquare_id
)

And to build the InputContactMessageContent object, use the function:

api.input_contact_message_content(
    phone_number,
    first_name,
    last_name
)

Building Reply Markup

There are functions to build keyboards and inline keyboards in this API. To build an inline keyboard, use the following function:

api.inline_keyboard()

For each row of buttons, you need to use the row() method on the above function, with the api.row() function inside it, like this:

api.inline_keyboard():row(
    api.row()
)

But wait, this keyboard doesn't have any buttons yet! To add buttons, you need to decide which type of button you are going to use - there are currently 5:

• url
• callback_data
• switch_inline_query
• switch_inline_query_current_chat
• pay

To build a URL button, you need to use the following method with the api.inline_keyboard() and the api.row() functions:

api.inline_keyboard():row(
    api.row():url_button(
        text,
        url
    )
)

To build a callback data button, you need to use the following method in the same way as previously shown with the URL button:

api.inline_keyboard():row(
    api.row():callback_data_button(
        text,
        callback_data
    )
)

To build a switch inline query button, you need to use the following method:

api.inline_keyboard():row(
    api.row():switch_inline_query_button(
        text,
        switch_inline_query
    )
)

To build a switch inline query current chat button, you need to use the following method:

api.inline_keyboard():row(
    api.row():switch_inline_query_current_chat_button(
        text,
        switch_inline_query_current_chat
    )
)

To build a pay button, you need to use the following method:

api.inline_keyboard():row(
    api.row():pay_button(
        text,
        pay
    )
)

To add more buttons to the same row, you need to use the button method again on the api.row() function. If I wanted to have an inline keyboard with 2 buttons on the first row and 1 button on the second row, where all of the buttons are URL buttons that display the text "Google" and have the URL "https://www.google.com/", it would look like this:

api.inline_keyboard():row(
    api.row():url_button(
        'Google',
        'https://www.google.com/'
    ):url_button(
        'Google',
        'https://www.google.com/'
    )
):row(
    api.row():url_button(
        'Google',
        'https://www.google.com/'
    )
)

Building Mask Positioning Arrays

There are functions to build mask positioning arrays in this API. These are used to specify the position of various facial elements using sticker-related Telegram bot API methods. To build a mask positioning array, use the following function:

api.mask_position()

For each position, you need to use the position() method on the above function, like this:

api.mask_position():position(
    point,
    x_shift,
    y_shift,
    scale
)

Each position method requires 4 parameters.