# Як створити бота для Telegram

{% hint style="warning" %}

#### **Вимоги та обмеження Telegram**

**1. Обмеження на повідомлення**

* **Повідомлення лише з текстом:** Максимум **4 096 символів**.
* **Повідомлення із зображенням:** Максимум **1 024 символи** (для зображення 1080x1080 px).

**2. Вимоги до зображень**

* **Формат:** Переважно квадратні зображення.
* **Оптимальний розмір:** 900x900 пікселів, максимум **5 МБ**.

**3. Вимоги до файлів**

Telegram API має спеціальні вимоги до завантажуваних файлів:

* Боти можуть надсилати файли до **2 ГБ**.
* Ви можете використовувати **file\_id** для роботи з файлами, завантаженими раніше. У цьому випадку обмеження на файли визначаються документацією Telegram.
* Файли можна надсилати за допомогою **URL** (бот завантажує і надсилає його):
  * **Фото:** ≤ 5 МБ
  * **Інші файли:** ≤ 20 МБ
* Для публікацій діють інші обмеження:
  * **Фото:** 10 МБ
  * **Інші файли:** 2 ГБ

[Докладніше читайте в оригінальному джерелі](https://core.telegram.org/bots/api#sending-files)
{% endhint %}

## Створення Telegram-бота

Telegram-бот створюється через **BotFather**, офіційну систему керування ботами Telegram. Цей перевірений інструмент (позначений синьою галочкою) дає змогу створити бота без жодних знань програмування та захищає вас від шахрайських копій.

**Кроки створення:**

1. **Почніть чат** на [BotFather](https://t.me/botfather).
2. Надішліть команду: `/newbot`
3. **Виберіть назву** для свого бота (це відображувана назва для користувачів).
4. **Виберіть ім'я користувача** для свого бота. Воно **має** закінчуватися на `bot` або `_bot` (наприклад, `my_test_bot`).

Якщо ім'я користувача доступне, BotFather надішле вам повідомлення з підтвердженням, яке міститиме **"token"**— унікальний ключ для доступу до API.

> **Важливо:** Цей токен — це пароль вашого бота. Збережіть його в безпечному місці та **ніколи не передавайте його** нікому.

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

Перейдіть до **Месенджери** , виберіть **Telegram**, і вставте токен вашого бота у надане поле.

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

Натисніть **Готово** кнопку, щоб завершити налаштування бота та активувати підключення до вашого проєкту.

### Робота з групами/каналами Telegram

**Корисна інформація**

Група Telegram — це канал спілкування між учасниками: усі учасники можуть писати в ній.

Канал Telegram — це односторонній засіб комунікації. Лише власник або адміністратори можуть надсилати повідомлення, тоді як решта учасників можуть лише переглядати їх і залишати коментарі.

#### Як додати бота до групи/каналу Telegram

Ця функція для бота включена в BotFather:

Крок 1. Перейдіть до налаштувань бота:

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

Крок 2. Натисніть на **"Allow Groups?'"**

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

Крок 3. Має бути статус увімкнено.

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

### Додайте бота як адміністратора в групі/каналі

Щоб автоматизувати роботу в чатах і каналах, потрібно додати власного бота як адміністратора.

Як це зробити?

Крок 1. Перейдіть до керування групою/каналом і виберіть **Адміністратори** вкладку

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

Крок 2. Натисніть **"Add Admin"** кнопку.

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

Крок 3. Введіть ім'я користувача вашого бота в поле пошуку.

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

Крок 4. Для повної функціональності переконайтеся, що бот має права читати та видаляти повідомлення.

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

### Змінні для роботи в чатах

{% hint style="warning" %}
Зверніть увагу!

Збереження змінних у групових чатах для подій на кшталт приєднання до чату, виходу з чату, нового лайка тощо недоступне.

Змінні будуть доступні лише всередині блоку, який спрацював. Ви можете виводити ці змінні в блоці, щоб відстежувати роботу.

Це НІЯКИМ ЧИНОМ не вплине на роботу чат-ботів, у розділі клієнтів буде неможливо відстежити, хто увійшов/вийшов.
{% endhint %}

* Змінні з інформацією про автора повідомлення

message\_from - ID автора повідомлення&#x20;

message\_from\_name - ім'я автора повідомлення

message\_from\_username - нік автора повідомлення в Telegram

<div data-with-frame="true"><figure><img src="/files/503edbac7592592c2a409446ec49bf724d0c6386" alt="" width="310"><figcaption></figcaption></figure></div>

* Змінні з інформацією про переслане повідомлення

reply\_message\_id - номер повідомлення, яке пересилається&#x20;

reply\_from - хто є автором пересланого повідомлення

reply\_from\_name - ім'я людини, чиє повідомлення пересилається

reply\_from\_username - нік людини, чиє повідомлення пересилається

reply\_from\_chat\_id - номер діалогу, з якого було переслано повідомлення

* Додавання та видалення з групи

У цьому випадку спрацьовують callbacks new\_chat\_member і left\_chat\_member (змінні не зберігаються в картці клієнта):

chat\_member\_name - ім'я користувача&#x20;

chat\_member\_username - нік користувача

chat\_member\_id - номер користувача

### Callbacks у Telegram

client\_unsubscribed - клієнт відписався, заблокував бота

client\_returned - клієнт розблокував бота

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

#### Callbacks у групах/каналах

new\_chat\_member - додано нового користувача

left\_chat\_member - користувач залишив канал&#x20;

kicked\_chat\_member - користувача видалено адміністратором

chat\_join\_request - отримано запит на приєднання до каналу

edited\_channel\_post - допис у каналі було відредаговано (edited\_channel\_post + дата й час редагування)

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

<div data-with-frame="true"><figure><img src="/files/594e3a9ea08532921a08c6d9710533d313bc5161" alt="" width="333"><figcaption></figcaption></figure></div>

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

Callbacks відображаються в **Клієнти** розділі

bot\_added\_to\_group - бота додано до чату (неважливо до якого, він відповість на будь-який, навіть якщо підключеного бота було додано до групи самостійно);

bot\_left\_group - подібний callback виникає під час видалення бота з каналу;

new\_like - поставлено лайк допису

like\_deleted - лайк до допису видалено

<div data-with-frame="true"><figure><img src="/files/903c5352fb1ea27464bd6b19d64af78366d4ffaf" alt="" width="358"><figcaption></figcaption></figure></div>

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

Число в callback (new\_like; like\_deleted) — це ID повідомлення, на яке відповіли або з якого було видалено реакцію.

{% hint style="warning" %}
Зверніть увагу!

* Callbacks для реакцій не відображаються в каналах Telegram! Callbacks для реакцій надходять лише в групах.
* Якщо одна людина поставила кілька лайків, а потім видалила 1 з них, не показується, який саме було видалено.
  {% endhint %}

Коли callbacks з реакціями з'являються в групах, у блоці доступні змінні:

reaction\_on\_message\_id - містить ID повідомлення, на яке було відреаговано

reaction\_from - id того, від кого була реакція

message\_from\_username - username того, від кого була реакція (якщо є)

reaction\_from\_name - ім'я того, від кого була реакція

<div data-with-frame="true"><figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfQptKK4YrlEATINQANRDaNEnpT95W_lgIGjMfOitIn387SG1GKI_n02rgWMZUrCP6hEGEnYAPiY99aZud2Ze4iOCYSlDCpzNsyHAMFdHd_mCxP5VfBpSx2iG7HzP1lgzDDly1Ziw?key=lL8rEUrFbZeHFjWugKFnxg" alt="" width="375"><figcaption></figcaption></figure></div>

Також, якщо Telegram відповідає на повідомлення, змінна reply\_text у картці міститиме повний текст повідомлення, на яке було дано відповідь.

<div data-with-frame="true"><figure><img src="/files/0624b54fc0374c5703ccb73f8957ae93aeae818d" alt="" width="337"><figcaption></figcaption></figure></div>

Якщо повідомлення було надіслано як відповідь (цитування попереднього повідомлення), система також згенерує `tg_quote` змінну, яка містить цитований текст.

<div data-with-frame="true"><figure><img src="/files/278509f7543b2bdeb3954bd0a9068a6a74662eee" alt="" width="188"><figcaption></figcaption></figure></div>

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

#### Callbacks з boost

* chat\_boost\_from user #{id\_user} - надав boost чату (або каналу):

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

Коли цей callback спрацьовує, генеруються змінні:

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

* remove\_boost\_from user #{id\_user} - забрали boost у чату (або каналу):

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

Коли цей callback спрацьовує,, генеруються змінні:

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

* chat\_boost from giveaway - видано під час розіграшу зірок у каналі
* remove\_chat\_boost from giveaway - період boost для розіграшу зірок у каналі завершився

#### Як автоматизувати видалення системних сповіщень у групах

Щоб автоматично видаляти всі системні повідомлення, достатньо присвоїти будь-яке значення змінній del\_tg\_system\_messages (змінна може бути як константою проєкту, так і змінною транзакції) і надати боту дозвіл на видалення повідомлень.

Змінну del\_tg\_system\_messages можна використовувати лише в групах. У каналах присвоєння будь-якого значення цій змінній не дасть жодного результату.

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

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

**Права адміністратора в налаштуваннях групи Telegram**

Видаляються такі типи системних сповіщень:

\- Назву групи змінено

\- Фото групи змінено

\- Фото групи видалено

\- Повідомлення закріплено

\- Користувач приєднався до групи

\- Користувач покинув групу

Якщо ви хочете видаляти лише вибрані типи системних сповіщень, то замість змінної del\_tg\_system\_messages створіть змінну del\_tg\_chosen\_messages і помістіть у неї масив із типами сповіщень, які потрібно видалити, через кому.

{% hint style="warning" %}
Зверніть увагу!

Ці змінні працюватимуть лише для груп Telegram, але не для каналів.
{% endhint %}

Параметри системних сповіщень:

* 'new\_chat\_member' – користувач приєднався до групи,
* 'left\_chat\_member' – користувач покинув групу,
* 'pinned\_message' – повідомлення закріплено,
* 'delete\_chat\_photo' – фото групи видалено,
* 'new\_chat\_photo' – фото групи змінено,
* 'new\_chat\_title' – назву групи змінено

Наприклад, вам потрібно видалити всі види системних повідомлень, окрім приєднання до групи; тоді потрібно додати всі види callbacks до змінної проєкту (константи), окрім "new\_chat\_member".

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

{% hint style="info" %}
Зверніть увагу!

Видалення системних сповіщень не вплине на callbacks. Буде видалено лише системне повідомлення з діалогу Telegram.
{% endhint %}

### Форум у Telegram

Форум — це група, де можна створювати окремі теми для обговорення. У форумі можна використовувати стандартні функції: прикріплювати медіафайли, публікувати опитування та налаштовувати сповіщення. Також можна закріплювати повідомлення та додавати окремих ботів до кожного чату.

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

Основна мета форуму — **структурувати спілкування** у межах великої спільноти.

У стандартному груповому чаті з багатьма учасниками відстежувати розмови та знаходити потрібні повідомлення стає складно. Форум вирішує цю проблему, організовуючи обговорення в **окремі тематичні гілки**. Це автоматично розділяє спільноту за темами й інтересами, роблячи спілкування більш сфокусованим і керованим.

Лише власник групи може створити тему, якщо в групі більше ніж 100 учасників. Якщо група пов'язана з каналом, то створити тему не вдасться. Теми увімкнено в **Налаштуваннях групи**:

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

Як адміністратор, ви можете створити тему в налаштуваннях групи форуму:

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

Після підключення **Тем**, аватар зміниться з круглого на квадратний, що дає змогу відрізнити форум від інших чатів Telegram:

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

### Як налаштувати зв'язку Telegram-клієнта з вебсайтом?

Докладніше про те, як пов'язати Telegram-клієнта і клієнта з вебсайту після [успішної оплати тут](#how-to-configure-a-telegram-client-bundle-with-a-website).


---

# 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/doc/uk/chatbot/mesendzheri/telegram/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.