# Functions for sending attachments in messages

## How to send documents

<details>

<summary>Send document  tg_send_document() </summary>

<mark style="color:red;">**!**</mark> These functions allow you to send files of any type. Recommended formats: **GIF, PDF, ZIP** up to **2GB**.

<mark style="background-color:green;">**! Work with Telegram business account**</mark>&#x20;

**tg\_send\_document(platform\_id, document, caption, reply\_markup, parse\_mode,reply\_to\_message\_id, protect\_content, disable\_notification**, **message\_thread\_id, entities)**&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — client identifier in Telegram to which the message must be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii) &#x20;

<mark style="color:red;">**!**</mark>**&#x20;document** - link to the document on Telegram’s server. Getting the link via tg\_request is explained [here](/chatbot/messengers/telegram/webhook.md).&#x20;

**caption** - description, up to 1024 characters

**reply\_markup** — button settings [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)&#x20;

**parse\_mode** — text formatting in the caption (bold or italic)  [ **\*\*\***](/chatbot/builder/telegram_messages.md)**.** Possible values: html, markdown, markdownV2. ссылка

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''.

**disable\_notification** —  flag to control sound notifications (default: 0).\
1 - send without notification, 0 - send with notification

**message\_thread\_id** —  thread identifier (available in supergroups with forum functionality)\
\
**entities** — lets you reuse pre-formatted text with styles. Simply define the character offset and range for formatting. Example available in tg\_request under the corresponding field. Need to be a dictionary.\
\
Example of passing the parameter: \
`entities = [{"offset":0,"length":5,"type":"bold"},{"offset":6,"length":4,"type":"text_link","url":"https://salebot.zmservice.ru"},{"offset":11,"length":9,"type":"strikethrough"},{"offset":21,"length":6,"type":"spoiler"},{"offset":29,"length":12,"type":"code"}]`  \
\
In this example, only the dictionary is shown, while the actual message text is defined in a separate variable.

To simplify the description of a button set, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button).&#x20;

</details>

<details>

<summary>Send several documents or other files tg_send_some_document()</summary>

<mark style="color:red;">**!**</mark> These functions allow you to send files of any type. Recommended formats: **GIF, PDF, ZIP** up to **2GB**.

**tg\_send\_some\_document(platform\_id, document\_list, disable\_notification, protect\_content, reply\_to\_message\_id, message\_thread\_id)**

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — client identifier in Telegram to which the message must be sent  [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)&#x20;

<mark style="color:red;">**!**</mark>**&#x20;document\_list** - an array of documents. Example of building such an array is provided below

**disable\_notification** —   flag to control sound notifications (default: 0).\
1 - send without notification, 0 - send with notification

**protect\_content** — flag for protecting content from copying. To enable, pass any value other than 0, False, or empty quotes ''.

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**message\_thread\_id** —  thread identifier (available in supergroups with forum functionality)

**Example of building a document\_list array:**\
'\[\["Document link", "caption", "parse\_mode"], \["Document link 2"], \["Document link 3", "caption"]]'&#x20;

**Data formatting example for a single document** \
\["Document link", "caption", "parse\_mode"]&#x20;

<mark style="color:red;">**The order of parameters is important!**</mark> When creating an array of documents, quotation marks " " can be omitted.

**Description of parameters for the document\_list array:**\ <mark style="color:red;">**!**</mark>**&#x20;Document link** - document link from the Telegram server. Getting the link via з tg\_request is explained [here](/chatbot/messengers/telegram/webhook.md)   \
**caption** — description up to 1024 characters\
**parse\_mode** — formatting of the description, i.e., highlighting text in bold or italic  [**\*\*\***](/chatbot/builder/telegram_messages.md)

</details>

<details>

<summary>Example</summary>

Let’s go through an example of sending a single document, adding inline buttons and a description to the document:

1. First, get the link to your document. A detailed explanation of how to do this can [be found here.](/chatbot/messengers/telegram/webhook.md#how-to-get-a-media-link-using-a-variable)
2. Сreate a block and set the variables as shown in the screenshot:<br>

   <div data-with-frame="true"><figure><img src="/files/miFW0JnmtHCPvc9Sgx38" alt="" width="563"><figcaption></figcaption></figure></div>
3. Send the block to ourselves and see the result of our work:

<div data-with-frame="true"><figure><img src="/files/1dYoGu7bGPkahpe2PRkR" alt="" width="563"><figcaption></figcaption></figure></div>

Now let’s look at sending multiple documents.

1. Here as well, you need to obtain an internal Telegram link for each document and form an array.\
   lnkdoc='\[\["BQACAgIAAxkBAAIQA2O8oEMNYPTgjLvglZ63HIYYOBwFAALvHwACtjXoSXFhhNvRN6MGLQQ", "Document1"],\["BQACAgIAAxkBAAIQA2O8oEMNYPTgjLvglZ63HIYYOBwFAALvHwACtjXoSXFhhNvRN6MGLQQ", "Document2"]]'
2. Finally, put together the function for sending documents:

<div data-with-frame="true"><figure><img src="/files/hekc6sK3L5Ch0yLYMWMw" alt="" width="563"><figcaption></figcaption></figure></div>

3\. And check out the result of work:

<div data-with-frame="true"><figure><img src="/files/ae56RwEwAZoOeTeQMOBB" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

Code example for sending a single document:

```
lnkdoc= "BQACAgIAAxkBAAIQA2O8oEMNYPTgjLvglZ63HIYYOBwFAALvHwACtjXoSXFhhNvRN6MGLQQ"
opts = {"inline_keyboard": [[{"text": "Excellent","callback_data":"Answer1"}, {"text": "Not accepted","callback_data":"Answer2"}]]}
soob=tg_send_document(platform_id, lnkdoc, "Document sending", opts) 
```

Code example for sending several documents:

```
lnkdoc='[["BQACAgIAAxkBAAIQA2O8oEMNYPTgjLvglZ63HIYYOBwFAALvHwACtjXoSXFhhNvRN6MGLQQ", "Document1"],["BQACAgIAAxkBAAIQA2O8oEMNYPTgjLvglZ63HIYYOBwFAALvHwACtjXoSXFhhNvRN6MGLQQ", "Document2"]]'
soob=tg_send_some_document(platform_id, lnkdoc)
```

</details>

## How to send an audio / audio voice

<details>

<summary>Send audio message <strong>tg_send_voice(</strong>)</summary>

<mark style="color:red;">!</mark> This function allows sending voice files of type .OGG encoded with OPUS, up to 2 GB in size.

<mark style="background-color:green;">**! Work only with Telegram business-account**</mark>

**tg\_send\_voice(platform\_id, voice, caption, reply\_markup, parse\_mode, reply\_to\_message\_id, protect\_content, disable\_notification, message\_thread\_id, entities)**&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — client identifier in Telegram to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;voice** - link to the voice message in .OGG format

**caption** - оdescription up to 1024 characters

**reply\_markup** — button settings [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**parse\_mode** — text formatting in the description bold or italic [ **\*\*\***](/chatbot/builder/telegram_messages.md)**.** Possible values:  html, markdown, markdownV2.

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**protect\_content** — flag for protecting content from being copied. To enable it, pass any value except 0, False, or empty quotes ''.

**disable\_notification** —  flag for sending a message with a sound notification (default is 0)   1 - disable notification when received, 0 - send with notification

**message\_thread\_id** —  topic identifier (available in supergroups if the forum feature is enabled).\
\
**entities** —with this parameter you can simply copy formatted text with all its features and specify from which character to which one it will be displayed with a particular style. You can check an example in tg\_request in the corresponding field. The parameter must be a dictionary. \
\
Example of parameter passing: \
`entities = [{"offset":0,"length":5,"type":"bold"},{"offset":6,"length":4,"type":"text_link","url":"https://salebot.zmservice.ru"},{"offset":11,"length":9,"type":"strikethrough"},{"offset":21,"length":6,"type":"spoiler"},{"offset":29,"length":12,"type":"code"}]`  \
\
The example shows only a dictionary, while the message text itself is defined in a variable.

To simplify the button set description, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Send several audio messages <strong>tg_send_some_audio()</strong></summary>

<mark style="color:red;">**!**</mark> This function allows sending audio files of type .MP3 or .M4A рwith a maximum size of 2GB.

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>&#x20;

**tg\_send\_some\_audio(platform\_id, audio\_list, disable\_notification, protect\_content, reply\_to\_message\_id, message\_thread\_id)**&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — client identifier in Telegram to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;audio\_list** - an array of audio files (details below)

**disable\_notification** —  flag for sending the message with or without a sound notification (default: 0).                                                                                                                   1 — send without notification, 0 — send with notification

**protect\_content** — flag to protect content from copying. To enable, pass any value except 0, False, or empty quotes ''.

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**message\_thread\_id** —  topic ID (available in supergroups with forum functionality)

**Example of building audio\_list array:** \
'\[\["Audio link 1", "caption", "parse\_mode"], \["Audio link 2"], \["Audio link 3", "caption"]]'&#x20;

**Example of a single audio:** \
\["Audio link", "caption", "parse\_mode"]&#x20;

<mark style="color:red;">**The order of parameters is important!**</mark> When building the audio files array, quotes "" can be omitted

**Parameters description:** \ <mark style="color:red;">**!**</mark>**&#x20;Audio link** - link to an audio file in .OGG format\
**caption** — description (up to 1024 characters) \
**parse\_mode** —text formatting in the caption bold or italic   [**\*\*\***](/chatbot/builder/telegram_messages.md)

</details>

<details>

<summary>Example</summary>

As stated in above, the function works with .OGG files. Therefore, the first task is to obtain an audio recording in this format. \
If you have an **.**&#x4D;P3 file, you can convert it to **.**&#x4F;GG using the <https://t.me/mp3toolsbot> bot.&#x20;

Next, send the resulting file to yourself in the bot to get the file\_id following the algorithm [described here. ](#documents-an-example-of-how-to-send-using-the-telegram-api)

Now put the function together:

<div data-with-frame="true"><figure><img src="/files/EMyvoSLXUlT28F8EgWme" alt="" width="563"><figcaption></figcaption></figure></div>

Great! Well done!

</details>

<details>

<summary>Example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

```
tg_send_voice(platform_id, "CQACAgIAAxkBAAER70Bi8VkgNhegB-msqDWXm2qHi3n9-AAC-iAAAk6giUvIXkW-XzBN0ikE")
```

</details>

<details>

<summary>Error when sending voice messages</summary>

If a message fails to send due to privacy settings, the following error is returned:

<mark style="color:red;">{"ok":false,"error\_code":400,"description":"Bad Request: user restricted receiving of voice messages"}</mark>

Cause of the error: the user’s privacy settings contain the option “Do not receive voice messages” (either from everyone, or only allowing from certain users):

<div data-with-frame="true"><figure><img src="/files/nDoa1u9YX4doPTJaMlvX" alt="" width="563"><figcaption></figcaption></figure></div>

Even if the user disables this privacy restriction, the error will still continue to appear.

In fact, only completely removing the client from the Mavibot database helps to overcome this error, even though the user has already enabled permissions.

<mark style="color:green;">**Solution:**</mark>&#x20;

After the user changes their privacy settings, you need to wait for a pause of 30–60 seconds (until the messenger servers process the changes), and only then send an API request to Telegram via the bot:\ <mark style="color:green;">**<https://api.telegram.org/bot\\><TOKEN>/getChat?chat\_id=#{platform\_id}**</mark>

After this, the user data will be refreshed and voice messages will be sent correctly.

</details>

## How to send animations

<details>

<summary>Send animation <strong>tg_send_animation()</strong></summary>

<mark style="color:red;">**!**</mark> This function allows sending GIF or H.264/MPEG-4 AVC video without sound with a maximum size of 2GB.

<mark style="background-color:green;">**! Work with Telegram bussiness-account**</mark>

**tg\_send\_animation(platform\_id, animation, caption, reply\_markup, parse\_mode, reply\_to\_message\_id, protect\_content, has\_spoiler, disable\_notification, message\_thread\_id, entities, show\_caption\_above\_media)**

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent. [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;animation**- link to the animation. How to obtain a link via tg\_request is explained [here](/chatbot/messengers/telegram/webhook.md)&#x20;

**caption** - description up to 1024 characters

**reply\_markup** — buttons configuration [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**parse\_mode** —text formatting in the caption bold or italic  [**\*\*\***](/chatbot/builder/telegram_messages.md)**.** Possible values: html, markdown, markdownV2

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''.

**has\_spoiler** — enables spoiler. To enable, set True.

**disable\_notification** —  flag for sending the message with or without a sound notification (default: 0).  1 — send without notification, 0 — send with notification

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)\
\
**entities** — with this parameter you can simply copy formatted text with all its features and specify from which character to which one it will be displayed with a particular style. You can check an example in tg\_request in the corresponding field. The parameter should be a dictionary.&#x20;

**show\_caption\_above\_media** - if set to True, the message caption will be displayed above the media\
\
Example of parameter passing:\
`entities = [{"offset":0,"length":5,"type":"bold"},{"offset":6,"length":4,"type":"text_link","url":"https://salebot.zmservice.ru"},{"offset":11,"length":9,"type":"strikethrough"},{"offset":21,"length":6,"type":"spoiler"},{"offset":29,"length":12,"type":"code"}]`  \
\
In this example, only the dictionary is shown, while the message text itself is stored in a variable

To simplify button set descriptions, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Example</summary>

Let’s make the task more complex and send an animation with copy and spoiler protection.

As always, the process starts with obtaining the internal Telegram link for the selected animation (details [here](/chatbot/messengers/telegram.md)).

<div data-with-frame="true"><figure><img src="/files/Bm6g9qAszHylQbWu0c5d" alt="" width="563"><figcaption></figcaption></figure></div>

Finally, put together the function:

<div data-with-frame="true"><figure><img src="/files/z0Df6pHQOlUEqccCR6Ma" alt=""><figcaption></figcaption></figure></div>

And check out the result of  work:

<div data-with-frame="true"><figure><img src="/files/qozpvRgBFtI952VlNxca" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

```
animation="CgACAgIAAxkBAAIQDWO9Dbb0QODBmI_CUMhKHoWch7MDAAJBIQACtjXoScUjA-n5kGCYLQQ"
caption = "Happy New Year!"
soob=tg_send_animation(platform_id, animation, caption, None, None, None, True,True)
```

</details>

## How to send videos

<details>

<summary>Send video using API Telegram <strong>tg_send_video()</strong></summary>

<mark style="color:red;">**!**</mark> This function allows you to send MPEG4 files up to 2GB in size. \
(Other formats can be sent as files using tg\_send\_document())

<mark style="background-color:green;">**! Work with Telegram business-account**</mark>&#x20;

**tg\_send\_video(platform\_id, video, caption, reply\_markup, parse\_mode, reply\_to\_message\_id, protect\_content, has\_spoiler, disable\_notification, message\_thread\_id, entities,** show\_caption\_above\_media, cover **)**

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;video** - video link. How yo get links via tg\_request see [here](/chatbot/messengers/telegram/webhook.md)&#x20;

**caption** - description up to 1024 characters

**reply\_markup** — buttons settings  [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**parse\_mode** — text formatting in the caption bold or italic  [**\*\*\***](/chatbot/builder/telegram_messages.md)**.** Possible values: html, markdown, markdownV2.

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''.

**has\_spoiler** — enables spoiler. To enable, set True

**disable\_notification** — flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)\
\
**entities** — with this parameter you can simply copy formatted text with all its features and specify from which character to which one it will be displayed with a particular style. You can check an example in tg\_request in the corresponding field. The parameter should be a dictionary.&#x20;

**show\_caption\_above\_media** - if set to True, the message text will be displayed above the media.

cover - video cover image in the message. Getting URL via tg\_request is [here](/chatbot/messengers/telegram/webhook.md). \
\
Example of passing parameter:\
`entities = [{"offset":0,"length":5,"type":"bold"},{"offset":6,"length":4,"type":"text_link","url":"https://salebot.zmservice.ru"},{"offset":11,"length":9,"type":"strikethrough"},{"offset":21,"length":6,"type":"spoiler"},{"offset":29,"length":12,"type":"code"}]`  \
\
In this example, only the dictionary is shown, while the message text itself is stored in a variable

To simplify button set descriptions, you can use the following[ lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Send several videos using API Telegram <strong>tg_send_some_video()</strong></summary>

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>&#x20;

**tg\_send\_some\_video(platform\_id, video\_list, disable\_notification, protect\_content, reply\_to\_message\_id, has\_spoiler, message\_thread\_id)**&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;video\_list** - an array of video files (details below)&#x20;

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**has\_spoiler** — enables spoiler formatting (optional; set to True to activate)

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)

**Example of vuilding a video array  video\_list:** \
'\[\["Video link1", "caption", "parse\_mode"], \["Video link2"], \["Video link3", "caption"]]'

**Example of building single audio :** \
\["Video link", "caption", "parse\_mode"]&#x20;

<mark style="color:red;">**The order of parameters is important!**</mark> When building the video files array, quotes "" can be omitted

**Parameters description:** \ <mark style="color:red;">**!**</mark>**&#x20;Video link** — internal Telegram video URL. Getting the link via tg\_request is described [here](/chatbot/messengers/telegram/webhook.md#how-to-get-webhook).\
**caption** — text caption up to 1024 characters\
**parse\_mode** — text formatting in the caption bold or italic  [**\*\*\***](/chatbot/builder/telegram_messages.md)**.** Possible values:  html, markdown, markdownV2.

</details>

<details>

<summary>Example</summary>

So, start by obtaining the link to the file we want to send, and then fill in the required function parameters:

<div data-with-frame="true"><figure><img src="/files/NssQVSTxFPBIoUz9PKrF" alt="" width="563"><figcaption><p>Getting video link via tg_request</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/wVbexLZXX2gppK6A7cn5" alt="" width="563"><figcaption><p>Sending video parameter</p></figcaption></figure></div>

After checking out we get the video:

<div data-with-frame="true"><figure><img src="/files/RW3AinPudUTVOip5yqVC" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

```
video="BAACAgIAAxkBAAIQFmO9Ycbt5JDIr9HKQh-XkhS9FqTxAALQIwACtjXoSXKlqfbH-I_gLQQ"
soob=tg_send_video(platform_id, video
```

</details>

## How to send a round video

<details>

<summary>Send round video <strong>tg_send_video_note()</strong></summary>

<mark style="color:red;">**!**</mark> Starting from version 4.0, Telegram supports sending round MPEG4 videos with a duration of up to one minute.

<mark style="background-color:green;">**! Work with Telegram business-account**</mark>

**tg\_send\_video\_note(platform\_id, video\_note,  reply\_markup, protect\_content, reply\_to\_message\_id, disable\_notification,  message\_thread\_id)** &#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;video\_note** - video link. How to get the link via tg\_request is described [here](/chatbot/messengers/telegram/webhook.md) \
**reply\_markup** — buttons settings [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**message\_thread\_id** —   thread ID (available in supergroups with forum functionality)

To simplify button set descriptions, you can use the following [lifehack ](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)

</details>

<details>

<summary>Example</summary>

If you have a square video, you can convert it to a round one using the <https://t.me/roundNoteBot> bot:&#x20;

<figure><img src="/files/fZ7ptSvWQTxoJhh11MQF" alt=""><figcaption><p>Getting rounding video bot via @roundNoteBot (https://t.me/roundNoteBot)</p></figcaption></figure>

Once you have the round video, send it to yourself in the bot to get the link (details [here](/chatbot/messengers/telegram/api/attachment.md)),  and then set up the function for sending the round video:

<figure><img src="/files/Jh9ru3f4TXYaqnDp6vzT" alt="" width="563"><figcaption></figcaption></figure>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

```
tg_send_video_note(platform_id, 'DQACAgIAAxkBAAER6cVi6OzIezJo9FWu6WyZPzDgQX8B3QACcxsAArR3SUtRizDeiHWLNikE','','1')

```

</details>

## How to send a location

<details>

<summary>Send geolocation <strong>tg_send_venue()</strong></summary>

<mark style="background-color:green;">**! Work with Telegram business-account**</mark>&#x20;

**tg\_send\_venue(platform\_id, latitude, longitude, title, address, protect\_content, disable\_notification, reply\_to\_message\_id, reply\_markup, message\_thread\_id)**&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;latitude** —latitude

<mark style="color:red;">**!**</mark>**&#x20;longitude** — longitude

<mark style="color:red;">**!**</mark>**&#x20;title** — title

<mark style="color:red;">**!**</mark>**&#x20;address** — address

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**reply\_markup** — buttons settings  [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)

To simplify button set descriptions, you can use the following[ lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Example</summary>

So, let’s start by determining the coordinates of the place. You can get them using  [Google Maps ](https://www.google.com/maps)

<div data-with-frame="true"><figure><img src="/files/dm0R3tyYI9KQ7P80PoNx" alt=""><figcaption></figcaption></figure></div>

Next, convert the obtained coordinates from decimal degrees to geographic format using any online [coordinates converter](https://coordinates-converter.com/en/decimal/51.000000,10.000000?karte=OpenStreetMap\&zoom=8):

<figure><img src="/files/5tgCaGSw2Qjn4h8PMG9R" alt="" width="375"><figcaption></figcaption></figure>

Now, let’s proceed with filling in the function parameters and obtaining the desired result:

<div data-with-frame="true"><figure><img src="/files/XuxB71Ufnz9tS8qjK0QF" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/MYxx0pKQRLm3hteZZmgi" alt="" width="375"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

```
soob=tg_send_venue(platform_id, "48°52′", "2°4′", "Dreams come true!", "Paris, Eiffel Tower") 
```

</details>

## How to send contacts

<details>

<summary>Send contact <strong>tg_send_contact()</strong></summary>

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>

Telegram provides a quick way to share contacts from your address book. The messenger supports sending **vCard** — an electronic business card

The function tg\_send\_contact allows sending a phone number with a first name (or organization name), as well as adding buttons and enabling content protection for the message.

**tg\_send\_contact(platform\_id, phone, first\_name, last\_name, protect\_content, disable\_notification, reply\_to\_message\_id, reply\_markup, message\_thread\_id)**&#x20;

<mark style="color:red;">**! - required function parameter**</mark>

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;phone** — phone number in international format. For example, for Russia: +7XXXXXXXXXX

<mark style="color:red;">**!**</mark>**&#x20;first\_name** and **last\_name** - first name and last name&#x20;

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**disable\_notification** — flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**reply\_markup** — buttons settings [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)

To simplify button set descriptions, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Example</summary>

Fill in the parameters: phone number, first name, and last name.

<div data-with-frame="true"><figure><img src="/files/kcfoz9WvmmpKrzKlojas" alt="" width="563"><figcaption><p>Example of filling in the parameters for the contact-sending function.</p></figcaption></figure></div>

Check out result:

<div data-with-frame="true"><figure><img src="/files/RJ6hilFtwm5nVvgEy21M" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

```
soob=tg_send_contact(platform_id, "+79999999999", "Ann", "Test", 1) 
```

</details>

## How to send a sticker

<details>

<summary>Send sticker <strong>tg_send_sticker()</strong></summary>

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>

**tg\_send\_sticker(platform\_id, sticker\_id, protect\_content,  disable\_notification, reply\_to\_message\_id, reply\_markup, message\_thread\_id)**&#x20;

Parameters:&#x20;

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;sticker\_id** - sticker ID. How to get a link via tg\_request is explained [here](/chatbot/messengers/telegram/webhook.md)&#x20;

**protect\_content** —  flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**disable\_notification** —   flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**reply\_markup** — button settings [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)

To simplify button set descriptions, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Example</summary>

Sending a sticker is no different from sending any other attachment:\
1\. Obtain the internal Telegram link (details here) \
2\. Fill in the function parameters\
3\. Send the block to yourself and check the result

<div data-with-frame="true"><figure><img src="/files/w0JcBRSEFkzPdK4vyPd1" alt="" width="563"><figcaption><p>Sending sticker</p></figcaption></figure></div>

Result:

<div data-with-frame="true"><figure><img src="/files/m1fP5zR0CpJxxatdeFzs" alt="" width="563"><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links</mark>

```
soob=tg_send_sticker(platform_id, 'CAACAgIAAxkBAAEawJ5jmNeyat8uPGBMP3JzubRNXGjH3wACrw4AAsYg4UqePobN94_jkywE')
```

</details>

## How to send a photo

{% hint style="warning" %}

#### **Understanding the `caption` parameter**

The **`caption`** parameter provides descriptive text for an image (e.g., a short summary or explanation). It functions as follows:

* **With a single image:** if a caption is provided, the message will contain both the image and the descriptive text.
* **With multiple images:** each image can have its own individual caption. In this case, each image will be sent alongside its specific description.

**User experience:** the caption text is typically revealed when a user clicks or taps on the image.

> **For detailed technical specifications and API behavior, please refer to the official Telegram documentation.**

**Note:** if you are following a video tutorial, please review the steps carefully as settings and interfaces may update over time.
{% endhint %}

<details>

<summary>Send photo <strong>tg_send_photo()</strong></summary>

<mark style="color:red;">**!**</mark> The photo should be no larger than 10 MB. The total width and height should not exceed 10,000 pixels. The width-to-height ratio should not exceed 20.

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>

**tg\_send\_photo(platform\_id, photo, caption, reply\_markup, parse\_mode, reply\_to\_message\_id, protect\_content, has\_spoiler, disable\_notification, message\_thread\_id, entities, show\_caption\_above\_media)**

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** —  Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;photo** - link to the image. How to get a link via tg\_request is explained [here](/chatbot/messengers/telegram/webhook.md).&#x20;

**caption** - description up to 1024 characters

**reply\_markup** — buttons settings  [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**parse\_mode** — text formatting in the caption bold or italic  [**\*\*\***](/chatbot/builder/telegram_messages.md)

**reply\_to\_message\_id -** ID of the message to reply to (i.e., quote)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**has\_spoiler** — enables spoiler formatting, set to True to activate

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)\
\
**entities** — with this parameter you can simply copy formatted text with all its features and specify from which character to which one it will be displayed with a particular style. You can check an example in tg\_request in the corresponding field. The parameter should be a dictionary.

show\_caption\_above\_media - if set to True, the message text will be displayed above the media\
\
Example of parameter sending: \
`entities = [{"offset":0,"length":5,"type":"bold"},{"offset":6,"length":4,"type":"text_link","url":"https://salebot.zmservice.ru"},{"offset":11,"length":9,"type":"strikethrough"},{"offset":21,"length":6,"type":"spoiler"},{"offset":29,"length":12,"type":"code"}]`  \
\
In this example, only the dictionary is shown, while the message text itself is stored in a variable

To simplify button set descriptions, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

</details>

<details>

<summary>Send several photos <strong>tg_send_some_photo()</strong></summary>

<mark style="color:red;">**!**</mark> The photo should be no larger than 10 MB. The total width and height should not exceed 10,000 pixels. The width-to-height ratio should not exceed 20.

<mark style="background-color:green;">**! Work with Telegram business-account**</mark>&#x20;

**tg\_send\_some\_photo(platform\_id, image\_list, disable\_notification=0**, **protect\_content=False, reply\_to\_message\_id=0, has\_spoiler=False,message\_thread\_id)**

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

<mark style="color:red;">**!**</mark>**&#x20;image\_list** - image files array  (details below)&#x20;

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**protect\_content** — flag to protect content from copying (optional parameter, to enable pass 1 as the value)

**reply\_to\_message\_id -**  ID of the message to reply to (i.e., quote)

**has\_spoiler** — enables spoiler formatting (optional; set to True to activate)

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)<br>

**Example image\_list:**

`'[["Image link 1", "caption", "parse_mode"], ["Image link 2"], ["Image link 3", "caption"]]'`

**Data example for a single image:** \
\["Image link 1", "caption", "parse\_mode"]&#x20;

<mark style="color:red;">**The parameter order is important!**</mark> When building the image files array, quotes "" can be omitted

**Parameters description:&#x20;**&#x20;

<mark style="color:red;">**!**</mark>**&#x20;Image link 1** - image link. How to get link via tg\_request is explained[ here](/chatbot/messengers/telegram/webhook.md) &#x20;

**caption** — caption up to 1024 characters

**parse\_mode** — text formatting in the caption bold or italic [**\*\*\***](/chatbot/builder/telegram_messages.md)

</details>

<details>

<summary>Example</summary>

Let's look at an example function for sending multiple images:

first, create an image array

<div data-with-frame="true"><figure><img src="/files/VrMP7cCntDwGCIqrUYJH" alt=""><figcaption></figcaption></figure></div>

Next, fill in the function parameters

<div data-with-frame="true"><figure><img src="/files/23UKdxwFkQLB3DaD3HVw" alt="" width="563"><figcaption></figcaption></figure></div>

Send the block to yourself and enjoy the result

<div data-with-frame="true"><figure><img src="/files/Z8I3Eq5uIu9L8g4jnURm" alt=""><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links for video</mark>

```
image_list='[["https://faktoria-print.ru/wp-content/uploads/2022/07/syre-dlya-bumagi.jpg"], ["https://www.solbum.ru/upload/medialibrary/2d1/2d18bd473d50fe9c2fe6a1eb401b4fe3.JPG"], ["https://www.solbum.ru/upload/medialibrary/bb7/bb786b67b57d9ab44ef5f7b8400810bb.jpg"], ["https://obumage.net/wp-content/uploads/2017/05/tual_bumaga.jpg"]]'
soob=tg_send_some_photo(platform_id, image_list)
```

</details>

## How to send a dice

<details>

<summary>Send an emoji with a random selection (Dice) <strong>tg_send_dice()</strong> </summary>

**tg\_send\_dice(platform\_id, emoji, reply\_markup, disable\_notification, reply\_to\_message\_id, protect\_content, message\_thread\_id)**

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>&#x20;

Parameters:

<mark style="color:red;">**!**</mark>**&#x20;platform\_id** — Telegram client ID to which the message should be sent [**\***](#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii)

**emoji** - the emoji to be sent. If you left parameter empty, a dice will be sent by default. You can pass either the emoji itself as a string or the keyword used to represent it

**reply\_markup** — buttons setting  [**\*\***](#kak-propisyvat-knopki-v-parametre-reply_markup)

**disable\_notification** —  flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

**reply\_to\_message\_id -**&#x49;D of the message to reply to (i.e., quote)

**protect\_content** — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

**message\_thread\_id** —  thread ID (available in supergroups with forum functionality)

To simplify button set descriptions, you can use the following [lifehack](/chatbot/messengers/telegram/buttons.md#telegram-web-application-button)&#x20;

&#x20;

**Possible emoji list:** \
1\) 'darts' or '🎯', values from 1 to 6 \
2\) 'dice' or '🎲', values from 1 to 6 \
3\) 'bowling' or '🎳', values from 1 to 6 \
4\) 'basketball' or '🏀',values from 1 to 5  \
5\) 'football' or '⚽', values from 1 to 5 \
6\) 'slots' or '🎰', values from 1 to 64&#x20;

\
Additionally, if a client sends one of these emoji to the bot, you will receive a callback containing information about the score and which emoji was used.

</details>

<details>

<summary>Example</summary>

The simplest option is to call the function with only one required parameter:

<div data-with-frame="true"><figure><img src="/files/K4s6VZC3hikUmH522KTo" alt="" width="563"><figcaption></figcaption></figure></div>

In this case, the client will receive a dice:

<div data-with-frame="true"><figure><img src="/files/25UUN1nEhyFalIyC6IP6" alt="" width="563"><figcaption></figcaption></figure></div>

If the client rolls the dice (by clicking on the received emoji), the bot will receive a callback with the number of points rolled:

<div data-with-frame="true"><figure><img src="/files/3Z58CCTg3KThCMdRf1pi" alt="" width="553"><figcaption></figcaption></figure></div>

You can experiment with this function. For example, let's create a slot machine and add a **Points** button. When the button is pressed, we will receive the client's total points:

<div data-with-frame="true"><figure><img src="/files/aHITriTdCMw65g4h5CJ2" alt="" width="563"><figcaption><p><strong>First message:</strong> Offer to play</p></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/xk8Xn3IPNI2ODhWiqrY9" alt="" width="563"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/bhyk77WnW8jJzNMR6dNY" alt="" width="563"><figcaption><p>Bot example</p></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

First example:

```
soob=tg_send_dice(platform_id)
```

Second example:

<pre><code>/* First example */
<strong>tg_send_message(platform_id,'Click on the slot machine to try your luck!')
</strong>opts='{"inline_keyboard": [[{"text": " 👓 ","callback_data":"Play"}]]}'
soob=tg_send_dice(platform_id, 'slots', opts)

/* Second block - Text Message */
<strong> #{res[1]} points rolled
</strong><strong>/* Second block - Calculator */
</strong>res=splitter('#{question}', ' ')
balls=if(balls==None,0,balls) + int(res[1])

/* Third block - Text Message */
You have total of #{balls} points
</code></pre>

</details>

## How to send a media group

<details>

<summary>Send media group tg_send_media_group()</summary>

<mark style="background-color:green;">**! Work with Telegram business - account**</mark>

A method for sending a group of photos, videos, documents, or audio files as an album. On success, an array of the sent files is returned.

<mark style="color:orange;">**Note: documents and audio files cannot be grouped with other file types!**</mark>

tg\_send\_media\_group(platform\_id, media\_list, disable\_notification, protect\_content, reply\_to\_message\_id, message\_thread\_id)

Parameters:

<mark style="color:red;">!</mark> platform\_id — Telegram client ID to which the message should be sent

<mark style="color:red;">!</mark> media\_list - an array containing from 2 to 10 photos, videos, documents, or audio files (details below);

disable\_notification — flag for sending the message with a sound notification (default: 0).   \
1 — send without notification, 0 — send with notification

protect\_content — flag to protect content from copying. To enable, pass any value other than 0, False, or empty quotes ''

reply\_to\_message\_id - ID of the message to reply to (i.e., quote)

message\_thread\_id — thread ID (available in supergroups with forum functionality);

**Content of the elements of media\_list array:**

<mark style="color:red;">!</mark> type - file type, “photo”, “video”, “audio” or ”document”

<mark style="color:red;">!</mark> media - file to send. Pass a file\_id to send a file that already exists on Telegram servers (recommended), an HTTP URL for Telegram to fetch the file from the Internet or «attach://\<file\_attach\_name>», to upload a new file using multipart/form-data with the name  \<file\_attach\_name>.

Read more: <https://core.telegram.org/bots/api#sending-files>

caption — title of the sending file, 0–1024 characters.

parse\_mode — text formatting in the caption bold or italic

Read more: <https://core.telegram.org/bots/api#sending-files>

Example of media\_list array:

\[{"type": "photo", "media": "AgACAgIAAxkBAAIKa2W6HqQG151EaWOKnCyy8feBi8p\_AAIH1zEbicvYSfi2QYj-CMreAQADAgADeAADNAQ", "caption": "ghosts video"}, {"type": "video", "media": "BAACAgIAAxkBAAIKpGW6P\_HGDoVz7u4blDF6925WO-hmAALVPQACicvYSYwIWCJKwKIWNAQ", “caption”: “hare video”}]

</details>

<details>

<summary>Example</summary>

Let's look at an example function for sending multiple images:

first, create an image array

<div data-with-frame="true"><figure><img src="/files/VrMP7cCntDwGCIqrUYJH" alt=""><figcaption></figcaption></figure></div>

Next, fill in the function parameters

<div data-with-frame="true"><figure><img src="/files/23UKdxwFkQLB3DaD3HVw" alt="" width="563"><figcaption></figcaption></figure></div>

Send the block to yourself and enjoy the result

<div data-with-frame="true"><figure><img src="/files/Z8I3Eq5uIu9L8g4jnURm" alt=""><figcaption></figcaption></figure></div>

</details>

<details>

<summary>Code example to copy</summary>

<mark style="color:red;">Remember that links are unique for each bot, so make sure to generate your own links for video</mark>

```
image_list='[["https://faktoria-print.ru/wp-content/uploads/2022/07/syre-dlya-bumagi.jpg"], ["https://www.solbum.ru/upload/medialibrary/2d1/2d18bd473d50fe9c2fe6a1eb401b4fe3.JPG"], ["https://www.solbum.ru/upload/medialibrary/bb7/bb786b67b57d9ab44ef5f7b8400810bb.jpg"], ["https://obumage.net/wp-content/uploads/2017/05/tual_bumaga.jpg"]]'
soob=tg_send_some_photo(platform_id, image_list)
```

</details>

## How to send large file attachments

<details>

<summary>Example</summary>

In Telegram (both for business accounts and regular accounts), you can send attachments via a link:

1. You can send attachments of any size, bypassing file size limits.
2. You can also send any type of attachment you need.

How to do it:

Copy the link to an attachment that is already publicly accessible:

<div data-with-frame="true"><figure><img src="/files/eVmaDxMiZptINBJ0jbUZ" alt="" width="563"><figcaption></figcaption></figure></div>

Then, paste the copied link into the attachment function in your block:

<div data-with-frame="true"><figure><img src="/files/3Ek3ikNXFUkhcHwdWub0" alt="" width="563"><figcaption></figcaption></figure></div>

Done. This way, you can send attachments of any type and size.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/chatbot/messengers/telegram/api/attachment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.