Module telegram-bot-lua.handlers
update handler stubs and dispatch logic.
| api._dispatch_update(update) | raw dispatch: routes an update directly to the appropriate handler. |
| api._run_sync(opts) | single-threaded synchronous polling loop (opt-in via sync = true). |
| api.on_business_connection(business_connection) | called when a business connection is updated. |
| api.on_business_message(business_message) | called for new messages from a connected business account. |
| api.on_callback_query(callback_query) | called when a callback query is received from an inline keyboard button. |
| api.on_channel_post(channel_post) | called for new posts in channels. |
| api.on_chat_boost(chat_boost) | called when a chat boost is added. |
| api.on_chat_join_request(chat_join_request) | called when a user sends a join request to a chat. |
| api.on_chat_member(chat_member) | called when a chat member's status is updated. |
| api.on_chosen_inline_result(chosen_inline_result) | called when a chosen inline result is received. |
| api.on_deleted_business_messages(deleted_business_messages) | called when business messages are deleted. |
| api.on_edited_business_message(edited_business_message) | called when a business message is edited. |
| api.on_edited_channel_post(edited_channel_post) | called when a channel post is edited. |
| api.on_edited_group_message(edited_message) | called when a message is edited in a group chat. |
| api.on_edited_message(edited_message) | called when a message is edited. |
| api.on_edited_private_message(edited_message) | called when a message is edited in a private chat. |
| api.on_edited_supergroup_message(edited_message) | called when a message is edited in a supergroup chat. |
| api.on_group_message(message) | called for new messages in group chats. |
| api.on_inline_query(inline_query) | called when an inline query is received. |
| api.on_managed_bot(managed_bot) | called when a managed bot update is received. |
| api.on_message(message) | called for any new message (after chat-type-specific handlers). |
| api.on_message_reaction(message_reaction) | called when a message reaction is changed by a user. |
| api.on_message_reaction_count(message_reaction_count) | called when anonymous reactions on a message are changed. |
| api.on_my_chat_member(my_chat_member) | called when the bot's own chat member status is updated. |
| api.on_poll(poll) | called when a poll state changes. |
| api.on_poll_answer(poll_answer) | called when a user changes their vote in a non-anonymous poll. |
| api.on_pre_checkout_query(pre_checkout_query) | called when a pre-checkout query is received (payments). |
| api.on_private_message(message) | called for new messages in private chats. |
| api.on_purchased_paid_media(purchased_paid_media) | called when paid media is purchased. |
| api.on_removed_chat_boost(removed_chat_boost) | called when a chat boost is removed. |
| api.on_shipping_query(shipping_query) | called when a shipping query is received (payments). |
| api.on_supergroup_message(message) | called for new messages in supergroup chats. |
| api.on_update(update) | called for every update received, before type-specific routing. |
| api.process_update(update) | process an update through the middleware chain (if any) then dispatch. |
| api.run(opts) | start the bot's polling loop. |
handler stubs
override these functions to handle specific update types.
each receives the relevant update object as its only argument.
- api._dispatch_update(update)
-
raw dispatch: routes an update directly to the appropriate handler.
called by the middleware chain as the final step, or directly when
no middleware is registered.
Parameters:
- update table the update object to dispatch
Returns:
-
any the return value of the matched handler
- api._run_sync(opts)
-
single-threaded synchronous polling loop (opt-in via sync = true).
Parameters:
- opts table same options as api.run
- api.on_business_connection(business_connection)
-
called when a business connection is updated.
Parameters:
- business_connection table the business connection object
- api.on_business_message(business_message)
-
called for new messages from a connected business account.
Parameters:
- business_message table the business message object
- api.on_callback_query(callback_query)
-
called when a callback query is received from an inline keyboard button.
Parameters:
- callback_query table the callback query object
- api.on_channel_post(channel_post)
-
called for new posts in channels.
Parameters:
- channel_post table the channel post message object
- api.on_chat_boost(chat_boost)
-
called when a chat boost is added.
Parameters:
- chat_boost table the chat boost updated object
- api.on_chat_join_request(chat_join_request)
-
called when a user sends a join request to a chat.
Parameters:
- chat_join_request table the chat join request object
- api.on_chat_member(chat_member)
-
called when a chat member's status is updated.
Parameters:
- chat_member table the chat member updated object
- api.on_chosen_inline_result(chosen_inline_result)
-
called when a chosen inline result is received.
Parameters:
- chosen_inline_result table the chosen inline result object
- api.on_deleted_business_messages(deleted_business_messages)
-
called when business messages are deleted.
Parameters:
- deleted_business_messages table the deleted messages object
- api.on_edited_business_message(edited_business_message)
-
called when a business message is edited.
Parameters:
- edited_business_message table the edited business message object
- api.on_edited_channel_post(edited_channel_post)
-
called when a channel post is edited.
Parameters:
- edited_channel_post table the edited channel post object
- api.on_edited_group_message(edited_message)
-
called when a message is edited in a group chat.
Parameters:
- edited_message table the edited message object
- api.on_edited_message(edited_message)
-
called when a message is edited.
Parameters:
- edited_message table the edited message object
- api.on_edited_private_message(edited_message)
-
called when a message is edited in a private chat.
Parameters:
- edited_message table the edited message object
- api.on_edited_supergroup_message(edited_message)
-
called when a message is edited in a supergroup chat.
Parameters:
- edited_message table the edited message object
- api.on_group_message(message)
-
called for new messages in group chats.
Parameters:
- message table the message object
- api.on_inline_query(inline_query)
-
called when an inline query is received.
Parameters:
- inline_query table the inline query object
- api.on_managed_bot(managed_bot)
-
called when a managed bot update is received.
Parameters:
- managed_bot table the managed bot updated object
- api.on_message(message)
-
called for any new message (after chat-type-specific handlers).
Parameters:
- message table the message object
- api.on_message_reaction(message_reaction)
-
called when a message reaction is changed by a user.
Parameters:
- message_reaction table the message reaction updated object
- api.on_message_reaction_count(message_reaction_count)
-
called when anonymous reactions on a message are changed.
Parameters:
- message_reaction_count table the reaction count updated object
- api.on_my_chat_member(my_chat_member)
-
called when the bot's own chat member status is updated.
Parameters:
- my_chat_member table the chat member updated object
- api.on_poll(poll)
-
called when a poll state changes.
Parameters:
- poll table the poll object with current state
- api.on_poll_answer(poll_answer)
-
called when a user changes their vote in a non-anonymous poll.
Parameters:
- poll_answer table the poll answer object
- api.on_pre_checkout_query(pre_checkout_query)
-
called when a pre-checkout query is received (payments).
Parameters:
- pre_checkout_query table the pre-checkout query object
- api.on_private_message(message)
-
called for new messages in private chats.
Parameters:
- message table the message object
- api.on_purchased_paid_media(purchased_paid_media)
-
called when paid media is purchased.
Parameters:
- purchased_paid_media table the purchased paid media object
- api.on_removed_chat_boost(removed_chat_boost)
-
called when a chat boost is removed.
Parameters:
- removed_chat_boost table the chat boost removed object
- api.on_shipping_query(shipping_query)
-
called when a shipping query is received (payments).
Parameters:
- shipping_query table the shipping query object
- api.on_supergroup_message(message)
-
called for new messages in supergroup chats.
Parameters:
- message table the message object
- api.on_update(update)
-
called for every update received, before type-specific routing.
Parameters:
- update table the raw update object
- api.process_update(update)
-
process an update through the middleware chain (if any) then dispatch.
Parameters:
- update table the update object to process
Returns:
-
any the return value of the matched handler, or false
- api.run(opts)
-
start the bot's polling loop.
by default uses copas for concurrent update processing.
pass { sync = true } for single-threaded sequential processing.
Parameters:
- opts table optional parameters
- sync boolean use synchronous polling instead of async
- limit number max number of updates per poll (default 1)
- timeout number long-polling timeout in seconds (default 0)
- offset number identifier of the first update to be returned
- allowed_updates table list of update types to receive
- opts table optional parameters