https://github.com/wrxck/telegram-bot-lua
A simple yet extensive Lua library for the Telegram bot API.
https://github.com/wrxck/telegram-bot-lua
api bot library lua telegram
Last synced: 4 months ago
JSON representation
A simple yet extensive Lua library for the Telegram bot API.
- Host: GitHub
- URL: https://github.com/wrxck/telegram-bot-lua
- Owner: wrxck
- License: gpl-3.0
- Created: 2017-03-03T18:47:35.000Z (over 9 years ago)
- Default Branch: main
- Last Pushed: 2024-01-10T14:01:26.000Z (over 2 years ago)
- Last Synced: 2025-03-29T07:34:30.920Z (over 1 year ago)
- Topics: api, bot, library, lua, telegram
- Language: Lua
- Homepage:
- Size: 140 KB
- Stars: 186
- Watchers: 11
- Forks: 32
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# telegram-bot-lua
A feature-filled Telegram bot API library written in Lua, created by [Matt](https://t.me/wrxck). 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](https://github.com/wrxck/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](https://t.me/mattatabot) and this library).
| Contents |
|-----------------------------------------------------------------------|
| [Installation](#installation) |
| [Update Handling](#update-handling) |
| [API Methods](#api-methods) |
| [Building Inline Results](#building-inline-results) |
| [Building Reply Markup](#building-reply-markup) |
| [Building Mask Positioning Arrays](#building-mask-positioning-arrays) |
## 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](https://t.me/BotFather)), like this:
```Lua
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`:
```Lua
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](https://core.telegram.org/bots/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`:
```Lua
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`:
```Lua
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`:
```Lua
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:
```Lua
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:
```Lua
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:
```Lua
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:
```Lua
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:
```Lua
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:
```Lua
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:
```Lua
api.run()
```
This is what will run your bot!
## API Methods
| Contents |
|---------------------------------------------------|
| [getMe](#getme) |
| [getUpdates](#getupdates) |
| [sendMessage](#sendmessage) |
| [forwardMessage](#forwardmessage) |
| [forwardMessages](#forwardmessages) |
| [copyMessage](#copymessage) |
| [copyMessages](#copymessages) |
| [sendPhoto](#sendphoto) |
| [sendAudio](#sendaudio) |
| [sendDocument](#senddocument) |
| [sendSticker](#sendsticker) |
| [sendVideo](#sendvideo) |
| [sendVoice](#sendvoice) |
| [sendLocation](#sendlocation) |
| [sendVenue](#sendvenue) |
| [sendContact](#sendcontact) |
| [sendChatAction](#sendchataction) |
| [getUserProfilePhotos](#getuserprofilephotos) |
| [getFile](#getfile) |
| [kickChatMember](#kickchatmember) |
| [unbanChatMember](#unbanchatmember) |
| [restrictChatMember](#restrictchatmember) |
| [promoteChatMember](#promotechatmember) |
| [exportChatInviteLink](#exportchatinvitelink) |
| [leaveChat](#leavechat) |
| [getChat](#getchat) |
| [getChatAdministrators](#getchatadministrators) |
| [getChatMembersCount](#getchatmemberscount) |
| [getChatMember](#getchatmember) |
| [answerCallbackQuery](#answercallbackquery) |
| [editMessageText](#editmessagetext) |
| [editMessageCaption](#editmessagecaption) |
| [editMessageReplyMarkup](#editmessagereplymarkup) |
| [answerInlineQuery](#answerinlinequery) |
| [sendInvoice](#sendInvoice) |
| [answerShippingQuery](#answerShippingQuery) |
| [sendGame](#sendgame) |
| [setGameScore](#setgamescore) |
| [getGameHighScores](#getgamehighscores) |
#### getMe
A simple function for testing your bot's auth token, using Telegram's `getMe` method. Requires no parameters.
```Lua
api.get_me()
```
#### getUpdates
Use this function to receive incoming updates via long polling, using Telegram's `getUpdates` method.
```Lua
api.get_updates(
offset,
limit,
timeout,
allowed_updates
)
```
| Parameters | Type | Required | Description |
|------------------|-----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| offset | Integer | Optional | Identifier of the first update to be returned. Must be greater by one than the highest among the identifiers of previously received updates. By default, updates starting with the earliest unconfirmed update are returned. An update is considered confirmed as soon as getUpdates is called with an offset higher than its update\_id. The negative offset can be specified to retrieve updates starting from -offset update from the end of the updates queue. All previous updates will forgotten. |
| limit | Integer | Optional | Limits the number of updates to be retrieved. Values between 1—100 are accepted. Defaults to 100. |
| timeout | Integer | Optional | Timeout in seconds for long polling. Defaults to 0, i.e. usual short polling. Should be positive, short polling should be used for testing purposes only. |
| allowed\_updates | Array of String | Optional | List the types of updates you want your bot to receive. For example, specify [“message”, “edited\_channel\_post”, “callback\_query”] to only receive updates of these types. Specify an empty list to receive all updates regardless of type (default). If not specified the previous setting will be used. Please note that this parameter doesn't affect updates created before the call to the getUpdates, so unwanted updates may be received for a short period of time. |
#### sendMessage
Use this function to send text messages, using Telegram's `sendMessage` method.
```Lua
api.send_message(
chat_id [or message object],
text,
message_thread_id,
parse_mode,
entities,
link_preview_options,
disable_notification,
protect_content,
reply_parameters,
reply_markup
)
```
| Parameter | Type | Required | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| text | String | Yes | Text of the message to be sent, 1-4096 characters after entities parsing |
| parse_mode | String | Optional | Mode for parsing entities in the message text. See [formatting options](https://core.telegram.org/bots/api#formatting-options) for more details. |
| entities | Array of [MessageEntity](https://core.telegram.org/bots/api#messageentity) | Optional | A JSON-serialized list of special entities that appear in message text, which can be specified instead of _parse\_mode_ |
| link\_preview\_options | [LinkPreviewOptions](https://core.telegram.org/bots/api#linkpreviewoptions) | Optional | Link preview generation options for the message |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving |
| reply\_parameters | [ReplyParameters](https://core.telegram.org/bots/api#replyparameters) | Optional | Description of the message to reply to |
| reply\_markup | [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) or [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) or [ReplyKeyboardRemove](https://core.telegram.org/bots/api#replykeyboardremove) or [ForceReply](https://core.telegram.org/bots/api#forcereply) | Optional | Additional interface options. A JSON-serialized object for an [inline keyboard](https://core.telegram.org/bots/features#inline-keyboards), [custom reply keyboard](https://core.telegram.org/bots/features#keyboards), instructions to remove reply keyboard or to force a reply from the user. |
#### forwardMessage
Use this function to forward a single message of any kind, using Telegram's `forwardMessage` method.
```Lua
api.forward_message(
chat_id,
from_chat_id,
message_id,
message_thread_id,
disable_notification,
protect_content
)
```
| Parameter | Type | Required | Description |
| -------------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| from\_chat\_id | Integer or String | Yes | Unique identifier for the chat where the original message was sent (or channel username in the format `@channelusername`) |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the forwarded message from forwarding and saving |
| message\_id | Integer | Yes | Message identifier in the chat specified in _from\_chat_id_ |
#### forwardMessages
Use this function to forward multiple messages of any kind, using Telegram's `forwardMessages` method.
```Lua
api.forward_messages(
chat_id,
from_chat_id,
message_ids,
message_thread_id,
disable_notification,
protect_content
)
```
| Parameter | Type | Required | Description |
| -------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| from\_chat\_id | Integer or String | Yes | Unique identifier for the chat where the original messages were sent (or channel username in the format `@channelusername`) |
| message\_ids | Array of Integer | Yes | Identifiers of 1-100 messages in the chat _from\_chat\_id_ to forward. The identifiers must be specified in a strictly increasing order. |
| disable\_notification | Boolean | Optional | Sends the messages [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the forwarded messages from forwarding and saving |
#### copyMessage
Use this function to copy a message of any kind (except service messages, giveaway messages, giveaway winners messages, and invoice messages), using Telegram's `copyMessage` method.
```Lua
api.copy_message(
chat_id,
from_chat_id,
message_id,
message_thread_id,
caption,
parse_mode,
caption_entities,
disable_notification,
protect_content,
reply_parameters,
reply_markup
)
```
| Parameter | Type | Required | Description |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| from\_chat\_id | Integer or String | Yes | Unique identifier for the chat where the original message was sent (or channel username in the format `@channelusername`) |
| message\_id | Integer | Yes | Message identifier in the chat specified in _from\_chat\_id_ |
| caption | String | Optional | New caption for media, 0-1024 characters after entities parsing. If not specified, the original caption is kept |
| parse\_mode | String | Optional | Mode for parsing entities in the new caption. See [formatting options](https://core.telegram.org/bots/api#formatting-options) for more details. |
| caption\_entities | Array of [MessageEntity](https://core.telegram.org/bots/api#messageentity) | Optional | A JSON-serialized list of special entities that appear in the new caption, which can be specified instead of _parse\_mode_ |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving |
| reply\_parameters | [ReplyParameters](https://core.telegram.org/bots/api#replyparameters) | Optional | Description of the message to reply to |
| reply\_markup | [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) or [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) or [ReplyKeyboardRemove](https://core.telegram.org/bots/api#replykeyboardremove) or [ForceReply](https://core.telegram.org/bots/api#forcereply) | Optional | Additional interface options. A JSON-serialized object for an [inline keyboard](https://core.telegram.org/bots/features#inline-keyboards), [custom reply keyboard](https://core.telegram.org/bots/features#keyboards), instructions to remove reply keyboard or to force a reply from the user. |
#### copyMessages
Use this function to copy messages of any kind (except service messages, giveaway messages, giveaway winners messages, and invoice messages), using Telegram's `copyMessages` method.
```Lua
api.copy_messages(
chat_id,
from_chat_id,
message_ids,
message_thread_id,
disable_notification,
protect_content,
remove_caption
)
```
| Parameter | Type | Required | Description |
| -------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| chat_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message_thread_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| from_chat_id | Integer or String | Yes | Unique identifier for the chat where the original messages were sent (or channel username in the format `@channelusername`) |
| message_ids | Array of Integer | Yes | Identifiers of 1-100 messages in the chat _from_chat_id_ to copy. The identifiers must be specified in a strictly increasing order. |
| disable_notification | Boolean | Optional | Sends the messages [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect_content | Boolean | Optional | Protects the contents of the sent messages from forwarding and saving |
| remove_caption | Boolean | Optional | Pass _True_ to copy the messages without their captions |
#### sendPhoto
Use this function to send photos, using Telegram's `sendPhoto` method.
```Lua
api.send_photo(
chat_id,
photo,
message_thread_id,
caption,
parse_mode,
caption_entities,
has_spoiler,
disable_notification,
protect_content,
reply_parameters,
reply_markup
)
```
| Parameter | Type | Required | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| photo | [InputFile](https://core.telegram.org/bots/api#inputfile) or String | Yes | Photo to send. Pass a file\_id as String to send a photo that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a photo from the Internet, or upload a new photo using multipart/form-data. The photo must be at most 10 MB in size. The photo's width and height must not exceed 10000 in total. Width and height ratio must be at most 20. [More information on Sending Files »](https://core.telegram.org/bots/api#sending-files) |
| caption | String | Optional | Photo caption (may also be used when resending photos by _file\_id_), 0-1024 characters after entities parsing |
| parse\_mode | String | Optional | Mode for parsing entities in the photo caption. See [formatting options](https://core.telegram.org/bots/api#formatting-options) for more details. |
| caption\_entities | Array of [MessageEntity](https://core.telegram.org/bots/api#messageentity) | Optional | A JSON-serialized list of special entities that appear in the caption, which can be specified instead of _parse\_mode_ |
| has\_spoiler | Boolean | Optional | Pass _True_ if the photo needs to be covered with a spoiler animation |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving |
| reply\_parameters | [ReplyParameters](https://core.telegram.org/bots/api#replyparameters) | Optional | Description of the message to reply to |
| reply\_markup | [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) or [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) or [ReplyKeyboardRemove](https://core.telegram.org/bots/api#replykeyboardremove) or [ForceReply](https://core.telegram.org/bots/api#forcereply) | Optional | Additional interface options. A JSON-serialized object for an [inline keyboard](https://core.telegram.org/bots/features#inline-keyboards), [custom reply keyboard](https://core.telegram.org/bots/features#keyboards), instructions to remove reply keyboard or to force a reply from the user. |
#### 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 `.mp3` or `.m4a` format. Bots can currently send audio files of up to 50 MB in size, this limit may be changed in the future.
```Lua
api.send_audio(
chat_id,
audio,
message_thread_id,
caption,
parse_mode,
caption_entities,
duration,
performer,
title,
thumbnail,
disable_notification,
protect_content,
reply_parameters,
reply_markup
)
```
| Parameter | Type | Required | Description |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| audio | [InputFile](https://core.telegram.org/bots/api#inputfile) or String | Yes | Audio file to send. Pass a file_id as String to send an audio file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get an audio file from the Internet, or upload a new one using multipart/form-data. [More information on Sending Files »](https://core.telegram.org/bots/api#sending-files) |
| caption | String | Optional | Audio caption, 0-1024 characters after entities parsing |
| parse\_mode | String | Optional | Mode for parsing entities in the audio caption. See [formatting options](https://core.telegram.org/bots/api#formatting-options) for more details. |
| caption\_entities | Array of [MessageEntity](https://core.telegram.org/bots/api#messageentity) | Optional | A JSON-serialized list of special entities that appear in the caption, which can be specified instead of _parse\_mode_ |
| duration | Integer | Optional | Duration of the audio in seconds |
| performer | String | Optional | Performer |
| title | String | Optional | Track name |
| thumbnail | [InputFile](https://core.telegram.org/bots/api#inputfile) or String | Optional | Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://\” if the thumbnail was uploaded using multipart/form-data under \. [More information on Sending Files »](https://core.telegram.org/bots/api#sending-files) |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving |
| reply\_parameters | [ReplyParameters](https://core.telegram.org/bots/api#replyparameters) | Optional | Description of the message to reply to |
| reply\_markup | [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) or [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) or [ReplyKeyboardRemove](https://core.telegram.org/bots/api#replykeyboardremove) or [ForceReply](https://core.telegram.org/bots/api#forcereply) | Optional | Additional interface options. A JSON-serialized object for an [inline keyboard](https://core.telegram.org/bots/features#inline-keyboards), [custom reply keyboard](https://core.telegram.org/bots/features#keyboards), instructions to remove reply keyboard or to force a reply from the user. |
#### 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.
```Lua
api.send_document(
chat_id,
document,
message_thread_id,
thumbnail,
caption,
parse_mode,
caption_entities,
disable_content_type_detection,
disable_notification,
protect_content,
reply_parameters,
reply_markup
)
```
| Parameter | Type | Required | Description |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format `@channelusername`) |
| message\_thread\_id | Integer | Optional | Unique identifier for the target message thread (topic) of the forum; for forum supergroups only |
| document | [InputFile](https://core.telegram.org/bots/api#inputfile) or String | Yes | File to send. Pass a file\_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. [More information on Sending Files »](https://core.telegram.org/bots/api#sending-files) |
| thumbnail | [InputFile](https://core.telegram.org/bots/api#inputfile) or String | Optional | Thumbnail of the file sent; can be ignored if thumbnail generation for the file is supported server-side. The thumbnail should be in JPEG format and less than 200 kB in size. A thumbnail's width and height should not exceed 320. Ignored if the file is not uploaded using multipart/form-data. Thumbnails can't be reused and can be only uploaded as a new file, so you can pass “attach://\” if the thumbnail was uploaded using multipart/form-data under \. [More information on Sending Files »](https://core.telegram.org/bots/api#sending-files) |
| caption | String | Optional | Document caption (may also be used when resending documents by _file\_id_), 0-1024 characters after entities parsing |
| parse\_mode | String | Optional | Mode for parsing entities in the document caption. See [formatting options](https://core.telegram.org/bots/api#formatting-options) for more details. |
| caption\_entities | Array of [MessageEntity](https://core.telegram.org/bots/api#messageentity) | Optional | A JSON-serialized list of special entities that appear in the caption, which can be specified instead of _parse\_mode_ |
| disable\_content\_type\_detection | Boolean | Optional | Disables automatic server-side content type detection for files uploaded using multipart/form-data |
| disable\_notification | Boolean | Optional | Sends the message [silently](https://telegram.org/blog/channels-2-0#silent-messages). Users will receive a notification with no sound. |
| protect\_content | Boolean | Optional | Protects the contents of the sent message from forwarding and saving |
| reply\_parameters | [ReplyParameters](https://core.telegram.org/bots/api#replyparameters) | Optional | Description of the message to reply to |
| reply\_markup | [InlineKeyboardMarkup](https://core.telegram.org/bots/api#inlinekeyboardmarkup) or [ReplyKeyboardMarkup](https://core.telegram.org/bots/api#replykeyboardmarkup) or [ReplyKeyboardRemove](https://core.telegram.org/bots/api#replykeyboardremove) or [ForceReply](https://core.telegram.org/bots/api#forcereply) | Optional | Additional interface options. A JSON-serialized object for an [inline keyboard](https://core.telegram.org/bots/features#inline-keyboards), [custom reply keyboard](https://core.telegram.org/bots/features#keyboards), instructions to remove reply keyboard or to force a reply from the user. |
#### sendSticker
Use this function to send `.webp` stickers, using Telegram's `sendSticker` method.
```Lua
api.send_sticker(
chat_id,
sticker,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|------------------------|----------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| sticker | InputFile or String | Yes | Sticker to send. Pass a file\_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a `.webp` file from the Internet, or upload a new one using multipart/form-data. |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. |
#### 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.
```Lua
api.send_video(
chat_id,
video,
duration,
width,
height,
caption,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|------------------------|----------------------------------------------------------------------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| video | InputFile or String | Yes | Video to send. Pass a file\_id as String to send a video that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a video from the Internet, or upload a new video using multipart/form-data. |
| duration | Integer | Optional | Duration of sent video in seconds |
| width | Integer | Optional | Video width |
| height | Integer | Optional | Video height |
| caption | String | Optional | Video caption (may also be used when resending videos by file\_id), 0-200 characters |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. |
#### 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.
```Lua
api.send_voice(
chat_id,
voice,
caption,
duration,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|------------------------|----------------------------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| voice | InputFile or String | Yes | Audio file to send. Pass a file\_id as String to send a file that exists on the Telegram servers (recommended), pass an HTTP URL as a String for Telegram to get a file from the Internet, or upload a new one using multipart/form-data. |
| caption | String | Optional | Voice message caption, 0-200 characters |
| duration | Integer | Optional | Duration of the voice message in seconds |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. |
#### sendLocation
Use this function to send a location on a map, using Telegram's `sendLocation` method.
```Lua
api.send_location(
chat_id,
latitude,
longitude,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|------------------------|----------------------------------------------------------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| latitude | Float number | Yes | Latitude of location |
| longitude | Float number | Yes | Longitude of location |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. |
#### sendVenue
Use this function to send information about a venue, using Telegram's `sendVenue` method.
```Lua
api.send_venue(
chat_id,
latitude,
longitude,
title,
address,
foursquare_id,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|-------------------------|----------------------------------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| latitude | Float number | Yes | Latitude of the venue |
| longitude | Float number | Yes | Longitude of the venue |
| title | String | Yes | Name of the venue |
| address | String | Yes | Address of the venue |
| foursquare\_id | String | Optional | Foursquare identifier of the venue |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove reply keyboard or to force a reply from the user. |
#### sendContact
Use this function to send phone contacts, using Telegram's `sendContact` method.
```Lua
api.send_contact(
chat_id,
phone_number,
first_name,
last_name,
disable_notification,
reply_to_message_id,
reply_markup
)
```
| Parameters | Type | Required | Description |
|-------------------------|----------------------------------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| phone\_number | String | Yes | Contact's phone number |
| first\_name | String | Yes | Contact's first name |
| last\_name | String | Optional | Contact's last name |
| disable\_notification | Boolean | Optional | Sends the message silently. iOS users will not receive a notification, Android users will receive a notification with no sound. |
| reply\_to\_message\_id | Integer | Optional | If the message is a reply, ID of the original message |
| reply\_markup | InlineKeyboardMarkup or ReplyKeyboardMarkup or ReplyKeyboardRemove or ForceReply | Optional | Additional interface options. A JSON-serialized object for an inline keyboard, custom reply keyboard, instructions to remove keyboard or to force a reply from the user. |
#### 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).
```Lua
api.send_chat_action(
chat_id,
action
)
```
| Parameters | Type | Required | Description |
|---------------|-------------------|------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| chat\_id | Integer or String | Yes | Unique identifier for the target chat or username of the target channel (in the format @channelusername) |
| action | String | Yes | Type of action to broadcast. Choose one, depending on what the user is about to receive: typing for text messages, upload\_photo for photos, record\_video or upload\_video for videos, record\_audio or upload\_audio for audio files, upload\_document for general files, find\_location for location data. |
#### getUserProfilePhotos
Use this function to get a list of profile pictures for a user, using Telegram's `getUserProfilePhotos` method.
```Lua
api.get_user_profile_photos(
user_id,
offset,
limit
)
```
| Parameters | Type | Required | Description |
|---------------|---------|------------|--------------------------------------------------------------------------------------------------|
| user\_id | Integer | Yes | Unique identifier of the target user |
| offset | Integer | Optional | Sequential number of the first photo to be returned. By default, all photos are returned. |
| limit | Integer | Optional | Limits the number of photos to be retrieved. Values between 1—100 are accepted. Defaults to 100. |
#### 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/`, where `` 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.
```Lua
api.get_file(file_id)
```
| Parameters | Type | Required | Description |
|---------------|--------|------------|-----------------------------------|
| file