# Chatbot for a Personal Telegram account

## Important to know

Restrictions based on the usage scenario can be applied when using an account. Exact data is not available, but approximate limit values can be found in open sources.

{% hint style="warning" %}
LIMITATIONS & RECOMMENDATIONS

1. You can add any number of contacts during the first synchronization on a new Telegram account (just registered).
2. Existing accounts have a limit of 200 contacts.
3. For a new account where contacts have been added before, the limit is 200.
4. If you exceed the 200-contact limit, you can still add up to 15 contacts manually per day.
5. To avoid further restrictions, add contacts gradually throughout the day. Adding too many at once (e.g., 15 in 5-10 minutes) will trigger stricter daily limits: 5 contacts the next day, and eventually just 1 contact per day if the lower limit is also exceeded.
6. If you add 15 contacts throughout the day, no limits will be set the next day.
7. The daily limit is 40 messages to different chats, after which your account will be temporarily restricted.
   {% endhint %}

<details>

<summary>MORE ABOUT RESTRICTIONS</summary>

### Contacts

To send a message to a phone number, you must first add it to your Telegram contacts list.

**Contact list synchronization:**

a) For a newly created account with a number never used on Telegram, the first contact sync has no import limits.

b) For phone numbers previously registered with Telegram, the initial contact import is limited to 200 contacts. This limit also applies to new numbers if a re-synchronization is performed.

c) Once the limit of 200 entries has been reached, new contacts must be added *manually*.

#### Manual contact creation

Adding too many contacts too quickly (e.g., 15 in a minute) will reduce your limit to 5 contacts the next day.

Adding 5 more contacts rapidly the same day will further reduce the limit to 1 per day. However, spreading additions evenly (e.g., 15 throughout the day) preserves the full limit for the next day.

The restriction does not reset over time.

According to Telegram:

> &#x20;*«To protect our users from spam and abuse, we have implemented safeguards that limit the number of contacts that can be imported at once. If you exceed these limits, your account will be restricted from importing contacts further. In such cases, you will be able to manually add up to five new numbers per day. Any additional contacts added beyond this limit will not be recognized as Telegram users — even if they are already on the platform.»*

{% hint style="success" %}
**Tip:** Spread out contact additions over a full day to prevent restrictions.
{% endhint %}

### Username addition limits

If a user has a username, you don't need to save them to your contacts — you can message them directly. However, searching for such users is limited to approximately 200 requests per day.

### No spam allowed

Telegram will issue a temporary or permanent account ban for excessive messaging or sending messages to too many chats at once.

{% hint style="warning" %}
While temporary restrictions last minutes, hours, or days, a permanent ban revokes account access indefinitely. This penalty is typically reserved for severe violations, including mass spamming, fraud, sharing prohibited content, or repeated user reports.
{% endhint %}

1. You can send up to 40 messages to different chats per day, after which a temporary block will be activated.
2. Repeated violations of the messaging limit result in progressively longer blocks, ranging from minutes and hours to days or weeks, potentially escalating to a permanent account ban.
3. If you send identical messages in a row without pauses, a block may be imposed after just a few attempts.
4. Content identified as spam can result in an immediate and permanent ban.
5. If your messages receive complaints (reports) from other users, a block is also inevitable.

</details>

## Getting started

To connect your account, first get your api\_id and api\_hash. Go to [https://my.telegram.org](https://my.telegram.org/) and log into your account.

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

After logging in, proceed to the **"API development tools"** section.

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

Then fill in the fields:

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

1. The **"App title"** field must be filled without spaces or any symbols, using only letters (no underscores, commas, etc.).
2. The **"Short name"** field must be filled without spaces or any symbols, using only letters and numbers (no underscores, commas, periods, dashes, hyphens, etc.).
3. The **"URL"** field is a valid link to your website.
4. Choose **"WEB"** in the **"Platform".**
5. The description should be in **Latin**.

Then click **Create application**.&#x20;

The `[object Object]` error on [**my.telegram.org**](https://my.telegram.org/) means there is invalid data. Ensure all fields are correct and that your **'app title'** and **'short name'** are not already taken.

If you have filled out everything correctly, you will see the following data:

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

## Account connection

Select "Telegram Account" in the "Messengers" section, then enter your phone number and the obtained credentials (api\_id and api\_hash).

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

Click **"Get code"**:

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

A verification code will be sent to your Telegram account. Enter it:

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

If two-factor authentication (2FA) is enabled on your account, you will also need to enter your password.

## Group chats

To allow the bot to reply in group chats, set the client variable answer\_on\_group\_chat = "1". By default, this feature is disabled.

## Chat archive

Archived chats are excluded from processing.

## Starting a chat using a phone number

To start a dialog with a new client, go to the **"Clients"** section and click **"Write in Telegram".**

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

Enter the client's phone number and name in the displayed window, and confirm by clicking **"Add"**.

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

If the new client has configured his Telegram privacy settings to permit discovery by phone number, a new client record will be generated.

## Client import from file

You can import clients from a file. To do this, click **Upload a list of clients** in the **Messengers** section of the desired bot.

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

Once the import is finished, client profiles will be generated for those who can be added to contacts based on their phone number.

{% hint style="danger" %}
PLEASE NOTE!

Consider the restrictions for Telegram account contact creation. Learn more in the [Important to know ](#important-to-know)section.&#x20;
{% endhint %}

## Calculator methods

create\_telegram\_client(phone, name, group) - adds the specified number to the contacts in the Telegram account and creates a corresponding client in MaviBot.

phone - client's phone

name - client's name

group - target bot user ID for bot linking.

{% hint style="success" %}
The calculator also supports common/general methods.
{% 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/personal.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.