# Bot usage

## How to work with a Telegram bot description (full and short)

### To configure welcome message

**tg\_set\_bot\_description(description, language\_code)** - bot description shown when the chat with the bot is empty

Parameters:

<table><thead><tr><th width="315.25">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>description</strong></td><td>Passing an empty string as the bot description will remove the existing description.</td></tr><tr><td><strong>language_code</strong></td><td><p>A two-letter language code according to the ISO 639-1 standard for text localization.</p><p></p><p>If left empty, the short description will be applied to all users who do not have a specific short description set.</p></td></tr></tbody></table>

<details>

<summary>Example</summary>

Example of configuring a welcome message and bot menu:

<div data-with-frame="true"><figure><img src="/files/6gHxWsYAUu7ouw4E56AF" alt="" width="563"><figcaption><p>Configuring a block in MaviBot: using functions to set commands and descriptions</p></figcaption></figure></div>

After the launch (this should be done once using an administrator command):

<div data-with-frame="true"><figure><img src="/files/5kPAEgvV3nBNJ5EzhnrE" alt="" width="375"><figcaption><p>Welcome message and bot menu</p></figcaption></figure></div>

Code example for copying:

`tg_set_bot_description('Welcome! I am your virtual assistant, Yurgram.🤖') command = [["private_office", "Personal Account"]] tg_set_command(command, '', 'default')`

</details>

### To configure short preview description

**tg\_set\_bot\_short\_description(description, language\_code)** - a short description of the bot that appears on the bot’s profile page and is sent along with the link when users share the bot.

Parameters:

<table><thead><tr><th width="315.25">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>description</strong></td><td>Passing an empty string as the bot description will remove the existing description.</td></tr><tr><td><strong>language_code</strong></td><td><p>A two-letter language code according to the ISO 639-1 standard for text localization.</p><p></p><p>If left empty, the short description will be applied to all users who do not have a specific short description set.</p></td></tr></tbody></table>

### To get current description

**tg\_get\_bot\_description(language\_code)** - use this method to get the current bot description for the specified user language.

<table><thead><tr><th width="315.25">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>language_code</strong></td><td><p>A two-letter language code according to the ISO 639-1 standard for text localization.</p><p></p><p>If left empty, the short description will be applied to all users who do not have a specific short description set.</p></td></tr></tbody></table>

### To get current short description

**tg\_get\_bot\_short\_description(language\_code)** - use this method to get the current short description of the bot for the specified user language.

<table><thead><tr><th width="315.25">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>language_code</strong></td><td><p>A two-letter language code according to the ISO 639-1 standard for text localization.</p><p></p><p>If left empty, the short description will be applied to all users who do not have a specific short description set.</p></td></tr></tbody></table>

## How to configure commands for the bot

### To configure commands

**`tg_set_command(commands, language, scope, platform_id, user_id)`**

<table><thead><tr><th width="239.27734375">Parameter </th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark><strong> commands</strong></td><td><p>Bot commands in the form of a list of lists, each nested list consists of 2 elements:
<br></p><p>1 – the command name, 2 – its description (there is a limit of 100 commands).</p></td></tr><tr><td><strong>language</strong></td><td><p>A two-letter language code according to ISO 639-1, e.g., 'ru' or 'en'.</p><p></p><p>If not specified, the commands will apply to all users whose language does not have specifically assigned commands.</p></td></tr><tr><td><strong>scope</strong></td><td>A parameter that defines the scope of users for whom the commands are created. The default value is <em><strong>'default'</strong></em>.</td></tr><tr><td><strong>platform_id</strong></td><td><p>Chat identifier within Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>. </p><p></p><p>Applies only for specific values of the <strong>scope</strong> parameter.</p></td></tr><tr><td><strong>user_id</strong></td><td><p>User identifier within Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>. </p><p></p><p>Applies only for specific values of the <strong>scope</strong> parameter.</p></td></tr></tbody></table>

<details>

<summary>Example</summary>

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

**command = \[\["count", "return count of user"],\["unpin", "unpin all message"]] tg\_set\_command(command, '', 'all\_chat\_administrators')**

In this example, the commands are placed in a separate variable. You can also add these commands directly into the function.

**tg\_set\_command('\[\["count", "return count of user"],\["unpin", "unpin all message"]]', '', 'all\_chat\_administrators')**

{% hint style="warning" %}
To call the commands, type the '/' symbol in the message input field. If everything was configured correctly, you'll see a suggestion list of available commands. The commands will appear in bold, with their descriptions shown to the right.
{% endhint %}

To use commands, configure a reaction to messages containing commands.

</details>

## **How to view commands for the bot**

### **tg\_get\_command()** &#x20;

<mark style="background-color:blue;">**To view commands**</mark>

**`tg_get_command(language, scope, platform_id, user_id)`**

<table><thead><tr><th width="262.8671875">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>language</strong></td><td>A two-letter language code according to ISO 639-1, e.g., 'ru' or 'en'.
<br>If not specified, commands applied to all users within the given area who do not have dedicated commands for their language will be shown.</td></tr><tr><td><strong>scope</strong></td><td>A parameter that defines the scope of users for whom the commands should be shown (optional parameter; if not used, the default value <em><strong>'default'</strong></em> will be applied).</td></tr><tr><td><strong>platform_id</strong> </td><td><p>Chat identifier within Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>. <br></p><p>Applies only for specific values of the <strong>scope</strong> parameter.</p></td></tr><tr><td><strong>user_id</strong></td><td><p>User identifier within Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a>. <br></p><p>Applies only for specific values of the <strong>scope</strong> parameter..</p></td></tr></tbody></table>

{% hint style="info" %}
If you do not want to use the language parameter but need to use the scope parameter, be sure to specify an empty parameter first, as in the example:

**tg\_get\_command('', scope)**
{% endhint %}

<details>

<summary>Example</summary>

***command = tg\_get\_command('', 'all\_chat\_administrators')***

Assign this function to a variable, and the variable will contain the server’s response with commands for the user scope specified in the parameter.

***{"ok":true,"result":\[{"command":"count","description":"return count of user"},{"command":"unpin","description":"unpin all message"}]}***

If the function is called without parameters, the scope will be set to ***'default'***.

***command = tg\_get\_command()***

</details>

## **How to delete commands in the bot**

### **tg\_delete\_command()**

<mark style="background-color:blue;">**To delete commands**</mark>

**tg\_delete\_command(language, scope, platform\_id, user\_id),** where

<table><thead><tr><th width="308.98828125">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>language</strong></td><td>A two-letter language code according to ISO 639-1, e.g., 'ru' or 'en' (optional parameter; if not specified, commands applied to all users within the given scope who do not have dedicated commands for their language will be deleted).</td></tr><tr><td><strong>scope</strong></td><td>A parameter that defines the scope of users for whom the commands will be deleted.
<br>If not specified, the default value <em><strong>'default'</strong></em> will be applied.</td></tr><tr><td><strong>platform_id</strong></td><td>Chat identifier (optional parameter, applies only for specific values of the scope parameter).</td></tr><tr><td><strong>user_id</strong></td><td>User identifier (optional parameter, applies only for specific values of the scope parameter).</td></tr></tbody></table>

{% hint style="info" %}
If you do not want to use the language parameter but need to use the scope parameter, be sure to specify an empty value for the first parameter, as in the example:

**tg\_delete\_command('', scope)**
{% endhint %}

{% hint style="info" %}
A command like tg\_delete\_command() will delete commands without specifying the language parameter, using the default scope value.
{% endhint %}

<details>

<summary>Example</summary>

You can delete the set commands by calling the function with parameters in the calculator:

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

**Code example for copying:**

**`tg_delete_command('', 'all_chat_administrators')`**

</details>

## How to configure reactions to commands

For commands in a private chat with the bot, you need to react to messages like: **'/command\_name'** – where **command\_name** is the command.

For commands in groups and chats, messages will appear as: **'/command\_name\@bot\_username'** – where **command\_name** is the command and **@bot\_username** is the bot’s username.

**Scope values list:**

<table><thead><tr><th width="214.984375">Parameter</th><th>Value</th></tr></thead><tbody><tr><td><strong>'default'</strong></td><td>The default parameter implies that the commands will work in private messages with the bot.</td></tr><tr><td><strong>'all_private_chats'</strong></td><td>All private chats: commands are available to everyone in private chats where the bot has been added.</td></tr><tr><td><strong>'all_group_chats'</strong></td><td>All group and supergroup chats: commands are available to everyone in these types of chats where the bot has been added.</td></tr><tr><td><strong>'all_chat_administrators'</strong> </td><td>Commands for administrators of all group and supergroup chats where the bot has been added.</td></tr><tr><td><strong>'chat'</strong></td><td>Commands for a specific chat (if you choose this option, you should specify the <strong>platform_id</strong>).</td></tr><tr><td><strong>'chat_administrators'</strong></td><td>Commands for administrators of a specific chat (if you choose this option, you should specify the <strong>platform_id</strong>).</td></tr><tr><td><strong>'chat_member'</strong></td><td>Commands for a specific member of a particular chat (if you choose this option, you should specify both <strong>platform_id</strong> and <strong>user_id</strong>; the specified user must be a member of the given chat).</td></tr></tbody></table>

{% hint style="info" %}
If you do not want to use the language parameter but need to use the scope parameter, be sure to specify an empty value for the first parameter, as in the example:

**tg\_delete\_command('', scope)**
{% endhint %}


---

# 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/chatbot.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.