Module telegram-bot-lua.methods.messages
messages API methods.
Functions
| api.copy_message(chat_id, from_chat_id, message_id, opts) | copy a message to another chat, without a link to the original message. |
| api.copy_messages(chat_id, from_chat_id, message_ids, opts) | copy multiple messages from one chat to another, without a link to the original messages. |
| api.forward_message(chat_id, from_chat_id, message_id, opts) | forward a message from one chat to another. |
| api.forward_messages(chat_id, from_chat_id, message_ids, opts) | forward multiple messages from one chat to another. |
| api.send_animation(chat_id, animation, opts) | send an animation file (gif or h.264/mpeg-4 avc video without sound) to a chat. |
| api.send_audio(chat_id, audio, opts) | send an audio file to a chat. |
| api.send_chat_action(chat_id, action, opts) | tell the user that something is happening on the bot's side. |
| api.send_contact(chat_id, phone_number, first_name, opts) | send a phone contact to a chat. |
| api.send_dice(chat_id, opts) | send an animated emoji that will display a random value. |
| api.send_document(chat_id, document, opts) | send a general file (document) to a chat. |
| api.send_location(chat_id, latitude, longitude, opts) | send a point on the map to a chat. |
| api.send_media_group(chat_id, media, opts) | send a group of photos, videos, documents or audios as an album. |
| api.send_message(chat_id, text, opts) | send a text message to a chat. |
| api.send_paid_media(chat_id, star_count, media, opts) | send paid media to a channel chat. |
| api.send_photo(chat_id, photo, opts) | send a photo to a chat. |
| api.send_poll(chat_id, question, options, opts) | send a native poll to a chat. |
| api.send_reply(message, text, opts) | send a text message as a reply to a received message. |
| api.send_venue(chat_id, latitude, longitude, title, address, opts) | send information about a venue to a chat. |
| api.send_video(chat_id, video, opts) | send a video file to a chat. |
| api.send_video_note(chat_id, video_note, opts) | send a video note (rounded square mp4 video message of up to 1 minute) to a chat. |
| api.send_voice(chat_id, voice, opts) | send a voice message to a chat. |
| api.set_message_reaction(chat_id, message_id, opts) | change the chosen reactions on a message. |
Functions
- api.copy_message(chat_id, from_chat_id, message_id, opts)
-
copy a message to another chat, without a link to the original message.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- from_chat_id number|string unique identifier for the chat where the original message was sent
- message_id number message identifier in the chat specified in fromchatid
- opts table optional parameters
- caption string new caption for the message
- parse_mode string mode for parsing entities in the new caption
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
- disable_notification boolean send the message silently
Returns:
-
table,number the response object and HTTP status
- api.copy_messages(chat_id, from_chat_id, message_ids, opts)
-
copy multiple messages from one chat to another, without a link to the original messages.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- from_chat_id number|string unique identifier for the chat where the original messages were sent
- message_ids table JSON-serialized list of message identifiers in the chat specified in fromchatid
- opts table optional parameters
- message_thread_id number unique identifier for the target message thread (topic) of the forum
- disable_notification boolean send the messages silently
- protect_content boolean protect the content of the copied messages from forwarding and saving
- remove_caption boolean pass true to remove captions from the copied messages
Returns:
-
table,number the response object and HTTP status
- api.forward_message(chat_id, from_chat_id, message_id, opts)
-
forward a message from one chat to another.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- from_chat_id number|string unique identifier for the chat where the original message was sent
- message_id number message identifier in the chat specified in fromchatid
- opts table optional parameters
- message_thread_id number unique identifier for the target message thread (topic) of the forum
- disable_notification boolean send the message silently
- protect_content boolean protect the content of the forwarded message from forwarding and saving
Returns:
-
table,number the response object and HTTP status
- api.forward_messages(chat_id, from_chat_id, message_ids, opts)
-
forward multiple messages from one chat to another.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- from_chat_id number|string unique identifier for the chat where the original messages were sent
- message_ids table JSON-serialized list of message identifiers in the chat specified in fromchatid
- opts table optional parameters
- message_thread_id number unique identifier for the target message thread (topic) of the forum
- disable_notification boolean send the messages silently
- protect_content boolean protect the content of the forwarded messages from forwarding and saving
Returns:
-
table,number the response object and HTTP status
- api.send_animation(chat_id, animation, opts)
-
send an animation file (gif or h.264/mpeg-4 avc video without sound) to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- animation string|file animation to send; pass a file_id string to send an existing file, or a file object for upload
- opts table optional parameters
- duration number duration of the animation in seconds
- width number animation width
- height number animation height
- caption string animation caption
- parse_mode string mode for parsing entities in the caption
- has_spoiler boolean pass true if the animation should be sent as a spoiler
- thumbnail string|file thumbnail of the file
- reply_markup table additional interface options
Returns:
-
table,number the response object and HTTP status
- api.send_audio(chat_id, audio, opts)
-
send an audio file to a chat.
the audio must be in .mp3 or .m4a format; the bots api sends audio files of up to 50 MB.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- audio string|file audio file to send; pass a file_id string to send an existing file, or a file object for upload
- opts table optional parameters
- caption string audio caption
- parse_mode string mode for parsing entities in the caption
- duration number duration of the audio in seconds
- performer string performer of the audio
- title string track name
- thumbnail string|file thumbnail of the file
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.send_chat_action(chat_id, action, opts)
-
tell the user that something is happening on the bot's side.
the status is set for 5 seconds or until the next message is sent.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- action string type of action to broadcast (e.g. "typing", "uploadphoto", "recordvideo")
- opts table optional parameters
- message_thread_id number unique identifier for the target message thread (topic) of the forum
- business_connection_id string unique identifier of the business connection
Returns:
-
table,number the response object and HTTP status
- api.send_contact(chat_id, phone_number, first_name, opts)
-
send a phone contact to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- phone_number string contact's phone number
- first_name string contact's first name
- opts table optional parameters
- last_name string contact's last name
- vcard string additional data about the contact in the form of a vcard (0-2048 bytes)
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.send_dice(chat_id, opts)
-
send an animated emoji that will display a random value.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- opts table optional parameters
- emoji string emoji on which the dice throw animation is based (default: dice)
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
- disable_notification boolean send the message silently
Returns:
-
table,number the response object and HTTP status
- api.send_document(chat_id, document, opts)
-
send a general file (document) to a chat.
the bots api sends files of up to 50 MB.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- document string|file file to send; pass a file_id string to send an existing file, or a file object for upload
- opts table optional parameters
- caption string document caption
- parse_mode string mode for parsing entities in the caption
- thumbnail string|file thumbnail of the file
- disable_content_type_detection boolean disables automatic server-side content type detection
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.send_location(chat_id, latitude, longitude, opts)
-
send a point on the map to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- latitude number latitude of the location
- longitude number longitude of the location
- opts table optional parameters
- horizontal_accuracy number the radius of uncertainty for the location, in metres (0-1500)
- live_period number period in seconds during which the location will be updated (60-86400)
- heading number direction in which the user is moving, in degrees (1-360)
- proximity_alert_radius number maximum distance in metres for proximity alerts about approaching another chat member
- reply_markup table additional interface options
Returns:
-
table,number the response object and HTTP status
- api.send_media_group(chat_id, media, opts)
-
send a group of photos, videos, documents or audios as an album.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- media table a JSON-serialized array of InputMediaAudio, InputMediaDocument, InputMediaPhoto and InputMediaVideo
- opts table optional parameters
- message_thread_id number unique identifier for the target message thread (topic) of the forum
- disable_notification boolean send the messages silently
- protect_content boolean protect the content from forwarding and saving
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.send_message(chat_id, text, opts)
-
send a text message to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- text string text of the message to be sent
- opts table optional parameters
- parse_mode string mode for parsing entities (HTML, MarkdownV2); pass true for MarkdownV2
- entities table list of special entities in the message text
- link_preview_options table options for link preview generation
- reply_markup table additional interface options (InlineKeyboardMarkup, ReplyKeyboardMarkup, etc.)
- reply_parameters table description of the message to reply to
- disable_notification boolean send the message silently
- business_connection_id string unique identifier of the business connection
Returns:
-
table,number the response object and HTTP status
- api.send_paid_media(chat_id, star_count, media, opts)
-
send paid media to a channel chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- star_count number the number of telegram stars that must be paid to buy access to the media
- media table a JSON-serialized array describing the media to be sent (must include 1-10 items)
- opts table optional parameters
- caption string media caption
- parse_mode string mode for parsing entities in the caption
- show_caption_above_media boolean pass true to show the caption above the media
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
- payload string bot-defined paid media payload (0-128 bytes)
Returns:
-
table,number the response object and HTTP status
- api.send_photo(chat_id, photo, opts)
-
send a photo to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- photo string|file photo to send; pass a file_id string to send an existing file, or a file object for upload
- opts table optional parameters
- caption string photo caption
- parse_mode string mode for parsing entities in the caption
- has_spoiler boolean pass true if the photo should be sent as a spoiler
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
- disable_notification boolean send the message silently
Returns:
-
table,number the response object and HTTP status
- api.send_poll(chat_id, question, options, opts)
-
send a native poll to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- question string poll question (1-300 characters)
- options table a JSON-serialized list of 2-10 answer options
- opts table optional parameters
- is_anonymous boolean true if the poll needs to be anonymous (defaults to true)
- poll_type string poll type: "quiz" or "regular" (defaults to "regular")
- allows_multiple_answers boolean true if the poll allows multiple answers (regular polls only)
- correct_option_id number 0-based identifier of the correct answer option (quiz mode only)
- explanation string text shown when a user chooses an incorrect answer in quiz mode
- open_period number amount of time in seconds the poll will be active (5-600)
- close_date number point in time (unix timestamp) when the poll will be automatically closed
- reply_markup table additional interface options
Returns:
-
table,number the response object and HTTP status
- api.send_reply(message, text, opts)
-
send a text message as a reply to a received message.
convenience wrapper around sendMessage that automatically sets reply_parameters
from the given message object.
Parameters:
- message table the message object to reply to (must contain chat.id and message_id)
- text string text of the message to be sent
- opts table optional parameters
- parse_mode string mode for parsing entities (HTML, MarkdownV2); pass true for MarkdownV2
- reply_markup table additional interface options
- reply_parameters table override the default reply parameters
- disable_notification boolean send the message silently
Returns:
-
table,number the response object and HTTP status
- api.send_venue(chat_id, latitude, longitude, title, address, opts)
-
send information about a venue to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- latitude number latitude of the venue
- longitude number longitude of the venue
- title string name of the venue
- address string address of the venue
- opts table optional parameters
- foursquare_id string foursquare identifier of the venue
- foursquare_type string foursquare type of the venue
- google_place_id string google places identifier of the venue
- google_place_type string google places type of the venue
- reply_markup table additional interface options
Returns:
-
table,number the response object and HTTP status
- api.send_video(chat_id, video, opts)
-
send a video file to a chat.
the bots api sends video files of up to 50 MB.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- video string|file video to send; pass a file_id string to send an existing file, or a file object for upload
- opts table optional parameters
- duration number duration of the video in seconds
- width number video width
- height number video height
- caption string video caption
- parse_mode string mode for parsing entities in the caption
- has_spoiler boolean pass true if the video should be sent as a spoiler
- supports_streaming boolean pass true if the uploaded video is suitable for streaming
- thumbnail string|file thumbnail of the file
- reply_markup table additional interface options
Returns:
-
table,number the response object and HTTP status
- api.send_video_note(chat_id, video_note, opts)
-
send a video note (rounded square mp4 video message of up to 1 minute) to a chat.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- video_note string|file video note to send; pass a file_id string or a file object for upload
- opts table optional parameters
- duration number duration of the video note in seconds
- length number video width and height (diameter of the video message)
- thumbnail string|file thumbnail of the file
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.send_voice(chat_id, voice, opts)
-
send a voice message to a chat.
the audio must be in an .ogg file encoded with opus. the bots api sends voice files of up to 50 MB.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- voice string|file audio file to send as a voice message; pass a file_id string or a file object for upload
- opts table optional parameters
- caption string voice message caption
- parse_mode string mode for parsing entities in the caption
- duration number duration of the voice message in seconds
- reply_markup table additional interface options
- reply_parameters table description of the message to reply to
Returns:
-
table,number the response object and HTTP status
- api.set_message_reaction(chat_id, message_id, opts)
-
change the chosen reactions on a message.
Parameters:
- chat_id number|string unique identifier for the target chat or username of the target channel
- message_id number identifier of the target message
- opts table optional parameters
- reaction table a JSON-serialized list of reaction types to set on the message
- is_big boolean pass true to set the reaction with a big animation
Returns:
-
table,number the response object and HTTP status