Personal Telegram account connection

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.

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.

MORE ABOUT RESTRICTIONS

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:

«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.»

Tip: Spread out contact additions over a full day to prevent restrictions.

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.

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.

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.

Getting started

To connect your account, first get your api_id and api_hash. Go to https://my.telegram.org and log into your account.

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

Then fill in the fields:

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.

The [object Object] error on 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:

Account connection

Select "Telegram Account" in the "Messengers" section, then enter your phone number and the obtained credentials (api_id and api_hash).

Click "Get code":

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

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".

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

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.

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

PLEASE NOTE!

Consider the restrictions for Telegram account contact creation. Learn more in the Important to know section.

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.

The calculator also supports common/general methods.