Module telegram-bot-lua.utils
utility functions for formatting, command parsing, and convenience helpers.
Functions
| api.decode_callback(str) | decode a callback data string back to action and key-value pairs. |
| api.deep_link(bot_username, payload) | generate a deep link URL for the bot. |
| api.deep_link_group(bot_username, payload) | generate a deep link URL for adding the bot to a group. |
| api.encode_callback(action, data) | encode callback data as "action:key1=val1;key2=val2". |
| api.extract_command(message) | extract command, arguments, and bot username from a message. |
| api.fmt.blockquote(text, parse_mode) | format text as a block quote. |
| api.fmt.bold(text, parse_mode) | format text as bold. |
| api.fmt.code(text, parse_mode) | format text as inline code. |
| api.fmt.italic(text, parse_mode) | format text as italic. |
| api.fmt.link(text, url, parse_mode) | format text as a hyperlink. |
| api.fmt.mention(user_id, name, parse_mode) | format a user mention link. |
| api.fmt.pre(text, language, parse_mode) | format text as a pre-formatted code block. |
| api.fmt.spoiler(text, parse_mode) | format text as a spoiler. |
| api.fmt.strikethrough(text, parse_mode) | format text with strikethrough. |
| api.fmt.underline(text, parse_mode) | format text with underline. |
| api.get_chat_id(obj) | get the chat ID from any update type. |
| api.get_name(user) | get the display name for a user object. |
| api.get_text(message) | get the text content of a message (text or caption). |
| api.get_user_id(obj) | get the sender's user ID from any update type. |
| api.is_command(message) | check if a message is a bot command. |
| api.is_group(message) | check if a message is from a group or supergroup. |
| api.is_private(message) | check if a message is from a private chat. |
| api.is_reply(message) | check if a message is a reply to another message. |
| api.paginate(items, page, items_per_page, callback_prefix) | build a paginated inline keyboard with navigation buttons. |
| api.parse_deep_link(message) | parse a deep link payload from a /start message. |
| api.parse_page_callback(data, callback_prefix) | parse a pagination callback data string to extract the page number. |
| api.safe_call(fn, ...) | safely call a function with error handling via pcall. |
| api.send_typing(chat_id) | send a typing indicator to a chat. |
Functions
- api.decode_callback(str)
-
decode a callback data string back to action and key-value pairs.
Parameters:
- str string the callback data string
Returns:
-
table|nil table with action and data fields, or nil
- api.deep_link(bot_username, payload)
-
generate a deep link URL for the bot.
Parameters:
- bot_username string the bot's username
- payload string the start parameter value
Returns:
-
string the deep link URL
- api.deep_link_group(bot_username, payload)
-
generate a deep link URL for adding the bot to a group.
Parameters:
- bot_username string the bot's username
- payload string the startgroup parameter value
Returns:
-
string the deep link URL
- api.encode_callback(action, data)
-
encode callback data as "action:key1=val1;key2=val2".
Parameters:
- action string the action identifier
- data table key-value pairs to encode
Returns:
-
string the encoded callback data string
- api.extract_command(message)
-
extract command, arguments, and bot username from a message.
Parameters:
- message table the message object
Returns:
-
table|false parsed command table with command, bot, args, args_str fields, or false
- api.fmt.blockquote(text, parse_mode)
-
format text as a block quote.
Parameters:
- text string the text to quote
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted block quote
- api.fmt.bold(text, parse_mode)
-
format text as bold.
Parameters:
- text string the text to format
- parse_mode string 'HTML', 'MarkdownV2', or 'Markdown' (default 'HTML')
Returns:
-
string formatted text
- api.fmt.code(text, parse_mode)
-
format text as inline code.
Parameters:
- text string the text to format
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted text
- api.fmt.italic(text, parse_mode)
-
format text as italic.
Parameters:
- text string the text to format
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted text
- api.fmt.link(text, url, parse_mode)
-
format text as a hyperlink.
Parameters:
- text string the link text
- url string the URL
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted link
- api.fmt.mention(user_id, name, parse_mode)
-
format a user mention link.
Parameters:
- user_id number the user ID
- name string the display name
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted mention
- api.fmt.pre(text, language, parse_mode)
-
format text as a pre-formatted code block.
Parameters:
- text string the text to format
- language string optional programming language for syntax highlighting
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted text
- api.fmt.spoiler(text, parse_mode)
-
format text as a spoiler.
Parameters:
- text string the text to hide
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted spoiler
- api.fmt.strikethrough(text, parse_mode)
-
format text with strikethrough.
Parameters:
- text string the text to strike through
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted text
- api.fmt.underline(text, parse_mode)
-
format text with underline.
Parameters:
- text string the text to underline
- parse_mode string parse mode (default 'HTML')
Returns:
-
string formatted text
- api.get_chat_id(obj)
-
get the chat ID from any update type.
Parameters:
- obj table the update or message object
Returns:
-
number|nil the chat ID
- api.get_name(user)
-
get the display name for a user object.
Parameters:
- user table the user object
Returns:
-
string the user's full name, or 'Unknown'
- api.get_text(message)
-
get the text content of a message (text or caption).
Parameters:
- message table the message object
Returns:
-
string|nil the message text or caption
- api.get_user_id(obj)
-
get the sender's user ID from any update type.
Parameters:
- obj table the update or message object
Returns:
-
number|nil the user ID
- api.is_command(message)
-
check if a message is a bot command.
Parameters:
- message table the message object
Returns:
-
boolean true if the message starts with /, !, or #
- api.is_group(message)
-
check if a message is from a group or supergroup.
Parameters:
- message table the message object
Returns:
-
boolean true if the chat type is 'group' or 'supergroup'
- api.is_private(message)
-
check if a message is from a private chat.
Parameters:
- message table the message object
Returns:
-
boolean true if the chat type is 'private'
- api.is_reply(message)
-
check if a message is a reply to another message.
Parameters:
- message table the message object
Returns:
-
boolean true if the message is a reply
- api.paginate(items, page, items_per_page, callback_prefix)
-
build a paginated inline keyboard with navigation buttons.
Parameters:
- items table array of items to paginate
- page number current page number (default 1)
- items_per_page number items per page (default 5)
- callback_prefix string callback data prefix (default 'page')
Returns:
-
table pagination result with items, page, totalpages, navrow
- api.parse_deep_link(message)
-
parse a deep link payload from a /start message.
Parameters:
- message table the message object
Returns:
-
string|nil the deep link payload
- api.parse_page_callback(data, callback_prefix)
-
parse a pagination callback data string to extract the page number.
Parameters:
- data string the callback data string
- callback_prefix string the prefix used in paginate (default 'page')
Returns:
-
number|nil the page number
- api.safe_call(fn, ...)
-
safely call a function with error handling via pcall.
Parameters:
- fn function the function to call
- ... any arguments to pass to fn
Returns:
-
any result from the function, or false and error on failure
- api.send_typing(chat_id)
-
send a typing indicator to a chat.
Parameters:
- chat_id number|string the target chat ID
Returns:
-
table API response