😉 Вітаю, тут ти зможеш знайти багато цікавої інформації про розробку телеграм ботів на aiogram і не тільки

📚 Документації
~ aiogram 3.X | aiogram 2.X

👾 Вивчення фреймворку
~ aiogram roadmap
~ Groosha & aiogram 3.X | aiogram 2.X
~ Latand & botfather.dev
~ ще канал про aiogram як цей

👩‍💻 Github
~ aiogram | contributors
~ examples 3.Х | examples 2.Х

❤️‍🔥 Підтримати aiogram
~ Open Collective

💭 Форуми спільноти
🇺🇸 @aiogram 🇺🇦 @aiogramua
🇺🇿 @aiogram_uz 🇰🇿 @aiogram_kz
🇮🇷 @aiogram_fa 🇧🇷 @aiogram_br

📺 Канали
• новини • меми

📣 Пости
#активіст
#порада
#цікаве

🍐 Groosha
😳 Tishka17
⏰ Відправка в заданий час
🔌 Збірка хостингів
🪝 Як підняти вебхук
✍️ Вебхук із самопідписаним сертифікатом
📂 Шаблони для бота
🕸 Про фільтри
🔒 Middleware
🏭 Про Callback Factory
📼 Машина станів (FSM)
🗄 СУБД Redis
🤖 Створення мультиботу
🔗 Deep Linking
📦 Технології для тг ботів
💬 Про Chat Actions
😀 aiogram roadmap
🌍 i18n, i10n - мови у боті
📥 Деплой ботів та SSH ключі
🔍 Inline Mode

💭 Всі пости про бібліотеку я буду писати для версії aiogram 3.X, старатимусь брати найновішу версію

💎 Підтримати канал
• TON (The Open Network)
UQDi31xJvtUmkKYepZ8NsblY0t_YJtcCKfC_1HyIrTc_IePV
• https://send.monobank.ua/jar/2RPWpMWwz5

🍐 Groosha #активіст

@Groosha - активний учасник спільноти, він пише якісні та зрозумілі статті, а також ботів з благородною метою - навчити людей, нижче представлено кілька його робіт

📚 Книги зі створення Telegram-ботів мовою Python за допомогою aiogram (НОВАЧКАМ ЧИТАТИ)
~ aiogram 3.X | aiogram 2.X

👩‍💻 Демонстрація роботи aiogram разом з асинхронною sqlalalchemy і базою даних PostgreSQL

😀 Ігровий бот для гри в сапера

💬 Бот для зворотного зв'язку без використання бази даних

🔔 Бот для ловлі скарг від користувачів у групі

🎰 Демонстраційний бот для гри з кістками в Telegram

🏭 Що таке callback factory (калбек фабрика)? #цікаве

👉 Callback Data Factory (CDF) - це інструмент для створення фільтрів на інлайн кнопках, він дозволяє поміщати в них данні (до 64 байтів - ліміт тг), які потім можна отримувати і відповідно реагувати (чимось схожий на enums)

🤨 І навіщо мені цим користуватись?
Корисна штука, коли вам в інлайн кнопках потрібна callback_data по типу item_1_73627352, item_2_7262626 (тобто декілька змінних у рядку). Для цього вже є готовий інструмент

👀 Як цим користуватись?

1️⃣ Імпортуємо CallbackData

from aiogram.filters.callback_data import CallbackData

2️⃣ Створюємо підклас CallbackData, наприклад

class ItemForSale(CallbackData, prefix='item'):
   item_id: int
   seller_id: int

📌 prefix - це обов'язковий кейворд, який робить такі фільтри унікальними (це типу їхнє ід чи ім'я, воно в callback_data на першому місці)

📌 атрибути item_id і seller_id - допомагають розрізняти змінні в callback_data

3️⃣ Робимо інлайн клавіатуру з кнопкою

from aiogram.utils.keyboard import InlineKeyboardBuilder

kb = InlineKeyboardBuilder()
kb.button(
    text='Item',
    callback_data=ItemForSale(
        item_id=1, 
        seller_id=2,
    ).pack(),
)
kb = kb.as_markup()

📌 метод pack() повертає данні об'єкту ItemForSale у вигляді рядка "item:1:2", тому зміна порядку атрибутів може щось зламати (також є unpack, він робить навпаки - перетворює рядок в об'єкт)

📌 CDF використовують в поєднанні з InlineKeyboardBuilder, бо потрібна динамічна клавіатура (данні можуть змінюватися)

4️⃣ Ловимо данні по кліку на кнопку

@router.callback_query(ItemForSale.filter())
async def test(
    call: CallbackQuery,
    callback_data: ItemForSale,
):
    print(callback_data.item_id)
    print(callback_data.seller_id)

📌 тепер при натисканні на кнопку в консолі ми побачимо данні item_id і seller_id (які задавали при створенні кнопки)

📌 не можна змінювати назву аргументу callback_data в хендлері

📌 щоб ловити натискання ми користуємось методом filter() підкласу CallbackData, також в ньому можна писати правила магічного фильтру «F» якщо треба вказати щось точніше, наприклад F.item_id == 1 означає, що хендлер буде реагувати якщо заданий item_id в кнопці був 1

📚 Читати про це в документації
🍐 Книга Груші, про Callback factory

📼 Що таке FSM, ФСМ, машина станів? #цікаве

👉 Finite State Machine (FSM) - це абстрактна машина, яка може перебувати в одному з кінцевого числа станів у будь-який момент часу. FSM може переходити з одного стану в інший як того забажає розробник

🤨 І навіщо мені цим користуватись?

Це стане в нагоді коли ми захочемо приймати якісь дані від юзера, наприклад під час заповнення анкети, реєстрації на щось чи просто обслуговування клієнта

👀 Як цим користуватись?

1️⃣ Потрібно зберігати введені данні

from aiogram.fsm.storage.memory import MemoryStorage

dp = Dispatcher(storage=MemoryStorage())

📌 ми додали в диспетчер параметр storage, він визначає де бот буде зберігати данні, в цьому випадку є декілька варіантів, але для практики вистачить оперативної пам'яті (коли ми вимкнемо бота - всі данні пропадуть). Якщо ми не хочемо втрачати данні при зупинці бота, то можемо використати наприклад бд Redis.

📌 за замовчуванням storage=MemoryStorage(), я вказав його для більш зрозумілого пояснення

2️⃣ Будуємо машину станів

from aiogram.fsm.state import StatesGroup, State

class Application(StatesGroup):
    name = State()
    phone_number = State()
    denoscription = State()

📌 один підклас StatesGroup - одна машина станів, у ній ми пишемо атрибути-екземпляри класу State, їх можна сприймати як флашки чи фільтри на які реагує хендлер

3️⃣ Вводимо нашого бота в стан

from aiogram.fsm.context import FSMContext

@router.message(Command('start'))
async def start_cmd(msg: Message, state: FSMContext):
    await state.set_state(Application.name)
    await msg.answer('Як тебе звати?')

📌 ми передаємо в хендлер аргумент state, за допомогою нього ми можемо керувати машинами станів, метод set_state задає новий стан, FSMContext потрібен для аннотації (так через IDE можна передивитись всі доступні методи)

📌 коли ми відправимо боту команду /start, то він увійде в стан і запитає наше ім'я

4️⃣ Ловимо повідомлення у стані

@router.message(Application.name)
async def get_name(msg: Message, state: FSMContext):
    await state.update_data(name=msg.text)
    await state.set_state(Application.name)
    await msg.answer('Добре, тепер відправ свій номер')

📌 в якості фильтра хендлера ми вказуємо очікуваний стан - тобто назву класу + атрибут, метод update_data оновлює данні які ми зберігаємо в storage, важливо розуміти, що вони не залежать від станів

📌 далі по аналогії можна ловити іншу інформацію, головне не забувати міняти стан і данні в storage та вказувати правильний тип апдейту (атрибут декоратора хендлера)

📌 після того, як ми отримаємо збереженні данні у вигляді словника за допомогою методу state.get_data(), їх можна видалити методом state.clear() - проте він чистить і стан, якщо потрібно прибрати тільки стан, то state.set_state(state=None) або тільки видалити дані - state.set_data({})

📚 Читати про це в документації
🍐 Книга Груші, про FSM

🗄 Що за бд редіс, Redis? #цікаве

👉 База даних Redis - (абр. remote dictionary server) швидке NoSQL сховище даних в форматі «ключ-значення», які зберігаються в оперативній пам'яті

📌 офіційної підтримки на Windows немає, але «якось» працювати можна

😀 І навіщо мені цим користуватись?
Наприклад, якщо взяти MemoryStorage, то данні які ми обробляємо за допомогою FSM будуть видалятися при зупинці бота. Але якщо ми хочемо, щоб данні зберігались? От для цього і підходить Redis (також з ним поєднують планувальники задач і черги, застосовують для роботи з хешем)

👀 Як цим користуватись?

1️⃣ Завантажуємо Redis

💭 Саме так і ніяк інакше, ви не під'єднаєтесь до того, чого у вас немає. Для кожної ОС є свої інструкції, які можуть різнитись, тому я не зможу описати процес встановлення персонально для вас - шукаємо це в інтернеті

2️⃣ Підключаємось до Redis

from aiogram.fsm.storage.redis import (
    RedisStorage, 
    DefaultKeyBuilder,
)

storage = RedisStorage.from_url(
    config.redis_url,
    key_builder=DefaultKeyBuilder(
        with_destiny=True,
    ),
    state_ttl=timedelta(days=1),
    data_ttl=timedelta(days=1),
)

dp = Dispatcher(storage=storage)

📌 клас RedisStorage потрібен для з'єднання з редісом, він приймає екземпляр коннекту до бд або url з даними для підключення. Тут використано метод from_url, саме він приймає url і просуває іменовані аргументи якби ми передали їх у RedisStorage напряму

📌 параметр key_builder можна використати для класу DefaultKeyBuilder, який потрібен для налаштування побудови ключів у редісі, ми вказуємо with_destiny=True, щоб вони були більш унікальними один для одного

📌 аргументи state_ttl і data_ttl - задають час в секундах, після закінчення якого ключи (для state і data відповідно) будуть видалятися. За замовчуванням у ключів в редісі немає TTL (time to live) - тому вони просто не видаляються і накопичуються

3️⃣ Користуємось FSM і поглиблюємо знання

💭 В принципі на цьому можна було б закінчити, оскільки після вищезазначених інструкцій нічого змінювати більше не треба, машини станів будуть працювати зовнішньо так само як це було б з MemoryStorage (дякуємо розробникам aiogram). Надалі можна лише поглиблюватись в те, як саме працює Redis і будуються (виглядають) ключі

📌 потренуватись можна в Docker

📌 ключі можуть бути - рядками, списками, множинами, хешами та сортованими множинами, а значення - рядками, числами, списками, множинами, хешами і бітовими рядками (в останньому до речі зберігаються ключі FSM)

📌 Redis може містити кілька баз даних, кожна з яких має унікальний номер. За замовчуванням їх 16 штук, від 0 до 15. Але це діло можна змінити в конфігураційних файлах

📚 Читати про це в документації

😀 Відправка в заданий час #цікаве

👉 Відправляти повідомлення через певний час - запланувати його, тобто зберігати до тих пір, поки воно не буде надіслано

😀 Що робити?
Якщо немає на стороні телеграм - треба робити у себе. Можна спробувати такі інструменти:
• asyncio
• apscheduler
• додаткові технології
│ RabbitMQ
│ Apache Kafka
│ Redis
╰ Celery

💭 Якщо контент просто треба надіслати пізніше, то можна взяти функції asyncio, наприклад create_task, call_later чи call_at. Проте, якщо вам потрібно більше гнучкості, наприклад видаляти задачу до її виконання чи відслідковувати прогрес розсилки, зупиняти її і так далі, то треба дивитись на інші варіанти

😀 В цьому пості ми розглянемо гнучкий і найбільш простий варіант для бота

⏲ APScheduler (абр. advanced python scheduler) - це бібліотека для планування завдань

В ній є 4 базові типи компонентів:
• тригери (date, interval, cron)
• сховища задач (in-memory, Redis..)
• планувальники (є AsyncIOScheduler)
• виконавці (відправляють завдання на виконання)

1️⃣ Екземпляр планувальника та його запуск

from apscheduler.schedulers.asyncio import AsyncIOScheduler

scheduler = AsyncIOScheduler()
scheduler.start()

📌 взагалі є декілька варіантів планувальника, але в нашому випадку потрібна асинхронність, тому беремо саме AsyncIOScheduler

2️⃣ Міні-інтерактив по документації

• створення завдань
• видалення завдань
• призупинення і поновлення завдань
• отримати всі завдання
• змінити завдання
• керування планувальником

💭 Можу запропонувати більш практичну статтю по APS від @Latand для aiogram 2.X - ось

😀 Про фільтри #цікаве

👉 Фільтр в aiogram - це об'єкт який викликається, приймає дані апдейту і порівнює їх з вашими умовами, він повертає boolean або dict

📌 на хендлер можна повісити декілька фільтрів через кому, тоді апдейт дійде до нього тільки якщо всі вони повернуть True (логічне AND). Якщо ми хочемо логічне OR, тоді можна створити ще один декоратор чи реєстрацію. З цього випливає те, що один хендлер може ловити декілька типів апдейтів

📌 Основні види фільтрів
• Текстові
• Магічні
• Кастомні
• CDF
• Спец. апдейти
• Для відлову помилок

✏️ Текстові
from aiogram.filters import Command

Command("start")
Command(commands=("foo", "bar"))

📌 фільтр Command створений для відлову команд, має для цього додаткові кейворди (prefix, ignore_mention), також з ним можна поєднувати CommandObject - цей об'єкт надає зручний спосіб вибирати будь-які дані команди, наприклад з "/get 65" взяти тільки 65. Для цього в хендлер передай кейворд command з анотацією із from aiogram.filters.command import CommandObject

🔮 Magic filers
from aiogram import F

🪄 Магічні фільтри працюють завдяки додатковій бібліотеці magic-filter, яку підтримують розробники aiogram, проте окремо вона має трохи менше функціоналу. F це аліас для MagicFilter

💭 «магічні вирази» можна розуміти і представляти як lambda функцію. Від мене: для розуміння, F у ролі фільтра можна уявляти як сам об'єкт апдейту, тобто Message, CallbackQuery і т.д.
Приклади (деякі методи універсальні):

🔻 Message
F.text == "hello"
F.photo
F.text.in_({"1", "2"})
F.text.contains("bar")
F.text.startswith("stop")
F.text.endswith("foo")
🔻 CallbackQuery
F.data == "my_data"
F.data.in_({"close", "cancel"})
F.chat.type == "private"
🔻 Regex
F.text.regexp(r'Hi, .+')

😀 Вони підтримують логічні оператори

• and через символ &
F.text == 1 & F.chat.id == 8
• or через символ |

F.text == "k" | F.text.len() == 1

• not через символ ~
~F.chat.id.in_({1, 2, 3})
• ще є такі варіанти

📌 є прикольний метод as('value'), він передає «відфільтрований» апдейт у аргументи хендлера під вашою назвою value, приклад у Груші (листай нижче)

📌 MagicData із aiogram.filters.magic_data - це інструмент для створення фільтрів з вашими данними, які можуть бути передані в аргументи хендлера (через мідлвар, Distpacher чи іншим способом). Наприклад - MagicData(F.from_user.id == F.config.admin_id), де config переданий аргумент

💭 на те, що не вмістилося в пост я зробив посилання, див. вище «Основні види фільтрів»

🪝 Як підняти вебхук #цікаве

👉 Webhook (для тг ботів) - це механізм отримання апдейтів шляхом ловлі POST-запитів до вашого веб-сервера, а не опитування телеграма на пряму

💡при polling (опитуванні) ми беремо апдейти з ендпоінту api.telegram.org, а от з вебхуком задаємо наше персональне посилання, куди вже сам телеграм буде відправляти апдейти, а ми їх ловити

🤨 І навіщо мені цим користуватись?

• у ситуації, коли бот має дуже велике навантаження, тобто отримує багато апдейтів за одиницю часу. Відомо, що опитування (getUpdates) дає можливість взяти максимально 100 апдейтів за виклик

• якщо не хочемо бачити записи в консолі про те, що не вдалося отримати апдейти. При polling кожний бот постійно робить запити на api.telegram.org навіть якщо апдейтів немає. Треба пам'ятати, що кожен виклик getUpdates має час виконання і певне навантаження

• цей механізм дає можливість розподіляти апдейти на потрібні вам сервера обробки і реалізувати горизонтальне масштабування проекту

👀 Як цим користуватись?

1️⃣ Домен або IP-адреса з сервером

💭 Очевидно, що телеграм буде слати апдейти на вказаний URL, до якого ви повинні мати доступ, тому необхідно завести свій сервер з необов'язковим доменом. Про організацію цього моменту можна почитати в інтернеті, а вибрати хостинг тут

2️⃣ Безпечне з'єднання з сервером

💭 Телеграм в якійсь мірі переймається про безпеку та конфіденційність своїх користувачів, тому не буде відправляти апдейти по небезпечному з'єднанню

• сервер повинен мати SSL/TLS сертифікат (другий наступник першого), щоб підтримувати HTTPS запити від телеграму. Дозволяється самописний сертифікат, але його встановлення відрізняється, для когось це може бути дещо складнішим (такий зазвичай прив'язують до IP-адреси)

📌 На каналі є пости про це
• Самопідписаний сертифікат
• Сертифікат від Let's Encrypt

3️⃣ Отримання апдейтів

💭 Є багато способів стежити за вхідними POST-запитами на ваш сервер, наприклад за допомогою:
• aiohttp
• FastAPI
• Flask
• reverse proxy server

🪄 Приклад з aiohttp (оригінал коду для мультибота):

bot.set_webhook(URL_FOR_UPDATES)

app = web.Application()
SimpleRequestHandler(
    dispatcher=dp, bot=bot,
).register(
    app, path=WEBHOOK_PATH,
)
setup_application(app, dp, bot=bot)
web.run_app(
    app, 
    host=WEB_SERVER_HOST, 
    port=WEB_SERVER_PORT,
)

📌 bot.set_webhook - метод, який передає телеграму URL для подальшої відправки туди апдейтів

📌 web та app - модуль для взаємодії з HTTP протоколом і екземпляр-додаток aiohttp відповідно

📌 SimpleRequestHandler - спец. фільтр aiogram, який ловить лише POST запити і перенаправляє їх на обробку до нашого бота

📌 setup_application - функція aiogram, яка допомагає налаштувати startup-shutdown процеси aiohttp додатку разом з ботом

4️⃣ Безпека та секретні токени

💭 Якщо є сервер який приймає запити, то цим можуть скористатися хацкери. От наприклад, вони відправлять свій POST запит, бот подумає що це апдейт - неправильно сериліазує і виникне помилка. Щоб перешкоди подібному деякі перевіряють IP-адресу відправника (у тг вони статичні), хтось додає в запити телеграму свої ключі, які звіряють на сервері, але вибір лишається за вами, проте я не рекомендую користуватись API токеном бота в ролі секрету, якщо це не мультибот

5️⃣ Як безкоштовно спробувати вебхук без SSL сертифікату та домену (листай вниз посту)

🌀 Telegram Bot API - Webhooks
🍐 Якийсь вебхук Груші

@Tishka17 😳 GitHub #активіст

Розробник. Помічник в чаті. Контрибьютор aiogram

😀Чим займався/ється:

• веде свій особистий канал із дієвими порадами. Буде корисний будь-яким розробникам - @advice17

• творець aiogram-dialog. Це фреймворк з графічним інтерфейсом для тг ботів. Натхненний ідеями Android SDK та React.js (простіше кажучи він допомагає працювати з інлайн кнопками). Є бот для демонстрації роботи бібліотеки - @aiogram_dialog_demo_bot
~ 📚 Документація | 💭 Чат

https://news.1rj.ru/str/about_aiogram/17