API Methods

All methods follow the pattern: required args positional, optional args in an opts table.

Methods return two values: result, error_info. On success, result contains the API response. On failure, result is false.

Messages

api.send_message(chat_id, text, opts)
api.send_reply(message, text, opts)
api.forward_message(chat_id, from_chat_id, message_id, opts)
api.forward_messages(chat_id, from_chat_id, message_ids, opts)
api.copy_message(chat_id, from_chat_id, message_id, opts)
api.copy_messages(chat_id, from_chat_id, message_ids, opts)
api.send_photo(chat_id, photo, opts)
api.send_audio(chat_id, audio, opts)
api.send_document(chat_id, document, opts)
api.send_video(chat_id, video, opts)
api.send_animation(chat_id, animation, opts)
api.send_voice(chat_id, voice, opts)
api.send_video_note(chat_id, video_note, opts)
api.send_live_photo(chat_id, live_photo, photo, opts)
api.send_media_group(chat_id, media, opts)
api.send_location(chat_id, latitude, longitude, opts)
api.send_venue(chat_id, latitude, longitude, title, address, opts)
api.send_contact(chat_id, phone_number, first_name, opts)
api.send_poll(chat_id, question, options, opts)
api.send_dice(chat_id, opts)
api.send_chat_action(chat_id, action, opts)
api.set_message_reaction(chat_id, message_id, opts)
api.delete_message_reaction(chat_id, message_id, opts)
api.delete_all_message_reactions(chat_id, opts)
api.send_paid_media(chat_id, star_count, media, opts)

Common opts for send methods

Key	Type	Description
parse_mode	string/boolean	'HTML', 'MarkdownV2', 'Markdown', or true (MarkdownV2)
reply_markup	table	Keyboard markup (inline_keyboard, keyboard, remove_keyboard)
reply_parameters	table	Reply configuration (use api.reply_parameters())
disable_notification	boolean	Send silently
protect_content	boolean	Prevent forwarding/saving
message_thread_id	number	Forum topic ID
business_connection_id	string	Business connection ID
message_effect_id	string	Message effect ID
direct_messages_topic_id	number	Direct-messages topic to send into
suggested_post_parameters	table	Suggested-post parameters (api.suggested_post_parameters())

The send_*, forward_*, and copy_* methods accept direct_messages_topic_id and suggested_post_parameters in their opts table.

send_message example

api.send_message(chat_id, 'Hello <b>world</b>', {
    parse_mode = 'HTML',
    disable_notification = true,
    reply_markup = api.inline_keyboard()
        :row(api.row():callback_data_button('Click', 'action'))
})

send_reply

Shorthand for sending a reply to an existing message:

-- message must have .chat.id and .message_id
api.send_reply(message, 'Reply text', { parse_mode = 'HTML' })

Poll additions (Bot API 10.x)

send_poll accepts media and channel-poll opts: media and explanation_media (build with the api.input_media_* builders), members_only, and country_codes. The minimum number of options is now 1.

Edit Methods

api.edit_message_text(chat_id, message_id, text, opts)
api.edit_message_caption(chat_id, message_id, opts)
api.edit_message_media(chat_id, message_id, media, opts)
api.edit_message_reply_markup(chat_id, message_id, opts)
api.edit_message_live_location(chat_id, message_id, latitude, longitude, opts)
api.stop_message_live_location(chat_id, message_id, opts)
api.stop_poll(chat_id, message_id, opts)
api.edit_message_checklist(business_connection_id, chat_id, message_id, checklist, opts)
api.delete_message(chat_id, message_id)
api.delete_messages(chat_id, message_ids)

Build the checklist (an InputChecklist) with api.input_checklist / api.input_checklist_task — see Builders.

edit_message_text also accepts a rich_message opt (Bot API 10.1) — see Rich Messages.

Rich Messages

Rich messages (Bot API 10.1) carry structured, streamable formatted content described with HTML or Markdown.

api.send_rich_message(chat_id, rich_message, opts)
api.send_rich_message_draft(chat_id, draft_id, rich_message, opts)

Build the rich_message (an InputRichMessage) with api.input_rich_message:

api.send_rich_message(chat_id, api.input_rich_message({ html = '<b>Hello</b>' }))

-- stream a draft (e.g. an AI reply) by repeating with the same draft_id
api.send_rich_message_draft(chat_id, 1, api.input_rich_message({ markdown = '*thinking...*' }))

-- edit a message's rich content
api.edit_message_text(chat_id, message_id, nil, {
    rich_message = api.input_rich_message({ html = '<i>updated</i>' })
})

See Builders for the rich text/block constructors.

Updates

api.get_updates(opts)
api.set_webhook(url, opts)
api.delete_webhook(opts)
api.get_webhook_info()

Chat Management

api.get_chat(chat_id)
api.get_chat_administrators(chat_id, opts)   -- opts.return_bots to include bot admins
api.get_chat_member_count(chat_id)
api.get_chat_member(chat_id, user_id)
api.leave_chat(chat_id)
api.set_chat_title(chat_id, title)
api.set_chat_description(chat_id, description)
api.set_chat_photo(chat_id, photo)
api.delete_chat_photo(chat_id)
api.set_chat_permissions(chat_id, permissions, opts)
api.set_chat_sticker_set(chat_id, sticker_set_name)
api.delete_chat_sticker_set(chat_id)
api.pin_chat_message(chat_id, message_id, opts)
api.unpin_chat_message(chat_id, opts)
api.unpin_all_chat_messages(chat_id)
api.export_chat_invite_link(chat_id)
api.create_chat_invite_link(chat_id, opts)
api.edit_chat_invite_link(chat_id, invite_link, opts)
api.create_chat_subscription_invite_link(chat_id, subscription_period, subscription_price, opts)
api.edit_chat_subscription_invite_link(chat_id, invite_link, opts)
api.revoke_chat_invite_link(chat_id, invite_link)
api.approve_chat_join_request(chat_id, user_id)
api.decline_chat_join_request(chat_id, user_id)
api.answer_chat_join_request_query(chat_join_request_query_id, result)   -- result: 'approve' | 'decline' | 'queue'
api.send_chat_join_request_web_app(chat_join_request_query_id, web_app_url)
api.get_user_chat_boosts(chat_id, user_id)

Member Management

api.ban_chat_member(chat_id, user_id, opts)
api.unban_chat_member(chat_id, user_id, opts)
api.restrict_chat_member(chat_id, user_id, permissions, opts)
api.promote_chat_member(chat_id, user_id, opts)
api.set_chat_administrator_custom_title(chat_id, user_id, custom_title)
api.ban_chat_sender_chat(chat_id, sender_chat_id)
api.unban_chat_sender_chat(chat_id, sender_chat_id)
api.get_user_profile_photos(user_id, opts)

Forum Topics

api.get_forum_topic_icon_stickers()
api.create_forum_topic(chat_id, name, opts)
api.edit_forum_topic(chat_id, message_thread_id, opts)
api.close_forum_topic(chat_id, message_thread_id)
api.reopen_forum_topic(chat_id, message_thread_id)
api.delete_forum_topic(chat_id, message_thread_id)
api.unpin_all_forum_topic_messages(chat_id, message_thread_id)
api.edit_general_forum_topic(chat_id, name)
api.close_general_forum_topic(chat_id)
api.reopen_general_forum_topic(chat_id)
api.hide_general_forum_topic(chat_id)
api.unhide_general_forum_topic(chat_id)
api.unpin_all_general_forum_topic_messages(chat_id)

Stickers

api.send_sticker(chat_id, sticker, opts)
api.get_sticker_set(name)
api.get_custom_emoji_stickers(custom_emoji_ids)
api.upload_sticker_file(user_id, sticker, sticker_format)
api.create_new_sticker_set(user_id, name, title, stickers, opts)
api.add_sticker_to_set(user_id, name, sticker)
api.set_sticker_position_in_set(sticker, position)
api.delete_sticker_from_set(sticker)
api.replace_sticker_in_set(user_id, name, old_sticker, sticker)
api.set_sticker_emoji_list(sticker, emoji_list)
api.set_sticker_keywords(sticker, keywords)
api.set_sticker_mask_position(sticker, mask_position)
api.set_sticker_set_title(name, title)
api.set_sticker_set_thumbnail(name, user_id, opts)
api.set_custom_emoji_sticker_set_thumbnail(name, opts)
api.delete_sticker_set(name)

Inline

api.answer_inline_query(inline_query_id, results, opts)
api.save_prepared_inline_message(user_id, result, opts)
api.answer_web_app_query(web_app_query_id, result)
api.answer_guest_query(guest_query_id, result)
api.answer_callback_query(callback_query_id, opts)
api.send_inline_article(inline_query_id, title, description, message_text, parse_mode, reply_markup)
api.send_inline_article_url(inline_query_id, title, url, hide_url, input_message_content, reply_markup, id)
api.send_inline_photo(inline_query_id, photo_url, caption, reply_markup)
api.send_inline_cached_photo(inline_query_id, photo_file_id, caption, reply_markup)

Payments

api.send_invoice(chat_id, title, description, payload, currency, prices, opts)
api.create_invoice_link(title, description, payload, currency, prices, opts)
api.answer_shipping_query(shipping_query_id, ok, opts)
api.answer_pre_checkout_query(pre_checkout_query_id, ok, opts)
api.get_star_transactions(opts)
api.get_my_star_balance()
api.refund_star_payment(user_id, telegram_payment_charge_id)
api.edit_user_star_subscription(user_id, telegram_payment_charge_id, is_canceled)

Games

api.send_game(chat_id, game_short_name, opts)
api.set_game_score(user_id, score, opts)
api.get_game_high_scores(user_id, opts)

Bot Settings

api.get_me()
api.log_out()
api.close()
api.get_file(file_id)
api.set_my_commands(commands, opts)
api.delete_my_commands(opts)
api.get_my_commands(opts)
api.set_my_name(name, opts)
api.get_my_name(opts)
api.set_my_description(description, opts)
api.get_my_description(opts)
api.set_my_short_description(short_description, opts)
api.get_my_short_description(opts)
api.set_chat_menu_button(opts)
api.get_chat_menu_button(opts)
api.set_my_default_administrator_rights(opts)
api.get_my_default_administrator_rights(opts)
api.set_my_profile_photo(opts)
api.remove_my_profile_photo(opts)
api.get_managed_bot_access_settings(user_id)
api.set_managed_bot_access_settings(user_id, is_access_restricted, opts)
api.get_user_personal_chat_messages(user_id, limit)
api.verify_user(user_id, opts)
api.verify_chat(chat_id, opts)
api.remove_user_verification(user_id)
api.remove_chat_verification(chat_id)
api.set_user_emoji_status(user_id, opts)

Passport

api.set_passport_data_errors(user_id, errors)

Gifts

api.get_user_gifts(user_id)
api.get_available_gifts()
api.send_gift(user_id, gift_id, opts)
api.transfer_gift(business_connection_id, owned_gift_id, new_owner_chat_id, opts)
api.upgrade_gift(business_connection_id, owned_gift_id, opts)
api.convert_gift_to_stars(business_connection_id, owned_gift_id)
api.gift_premium_subscription(user_id, month_count, star_count, opts)

Stories

api.post_story(business_connection_id, content, active_period, opts)
api.edit_story(business_connection_id, story_id, content, opts)
api.delete_story(business_connection_id, story_id)
api.repost_story(chat_id, story_id)

Build the content (an InputStoryContent) with api.input_story_content_photo / api.input_story_content_video — see Builders.

Business Accounts

Methods that act on a connected business account; all take the business_connection_id.

api.get_business_connection(business_connection_id)
api.read_business_message(business_connection_id, chat_id, message_id)
api.delete_business_messages(business_connection_id, message_ids)
api.set_business_account_name(business_connection_id, first_name, opts)
api.set_business_account_username(business_connection_id, opts)
api.set_business_account_bio(business_connection_id, opts)
api.set_business_account_profile_photo(business_connection_id, photo, opts)
api.remove_business_account_profile_photo(business_connection_id, opts)
api.set_business_account_gift_settings(business_connection_id, show_gift_button, accepted_gift_types)
api.get_business_account_star_balance(business_connection_id)
api.transfer_business_account_stars(business_connection_id, star_count)
api.get_business_account_gifts(business_connection_id, opts)

Build accepted_gift_types with api.accepted_gift_types() — see Builders.

Helper Methods

api.is_user_kicked(chat_id, user_id)       -- Returns: is_kicked, status
api.is_user_group_admin(chat_id, user_id)   -- Returns: is_admin, status
api.is_user_group_creator(chat_id, user_id) -- Returns: is_creator, status
api.is_user_restricted(chat_id, user_id)    -- Returns: is_restricted, status
api.has_user_left(chat_id, user_id)         -- Returns: has_left, status
api.get_chat_member_permissions(chat_id, user_id)  -- Returns permissions table