Збираємо Telegram-бота в Cursor: від ідеї до деплою за один вечір

Telegram-бот — ідеальний перший проєкт, щоб спробувати «програмування з ІІ» на чомусь справжньому. Він маленький, приносить користь одразу, а його логіка зрозуміла на пальцях: прийшло повідомлення — бот відповів. Але між «hello world на ноутбуці» і «бот, який живе у хмарі й відповідає всім» є кілька кроків, де новачки стабільно спотикаються: асинхронний код, зберігання токена й деплой.

Cursor — редактор коду з ІІ-агентом — саме гарний тим, що прискорює ці складні місця. Він не «пише бота за вас магією», а допомагає не потонути в асинхронних патернах, структурі обробників і налаштуванні оточення. У цьому гайді зберемо робочого бота від токена до деплою й дорогою розберемо одну пастку Cursor, про яку мовчать звичайні туторіали: той самий файл .env, який створюють, щоб НЕ зберігати токен у коді, Cursor прочитає сам, якщо його не виключити.

Що знадобиться

Три речі:

• Cursor — сам редактор ставиться безкоштовно; для першого бота вистачає безкоштовного тарифу Hobby. Якщо хочете зрозуміти, що це за інструмент загалом, у нас є повний огляд можливостей Cursor.
• Python 3.10 або новіший — сучасні бібліотеки для ботів вимагають саме його.
• Акаунт Telegram — для спілкування з BotFather.

Жодного досвіду в Python для старту не потрібно: команди й код отримуватимемо від агента, а наше завдання — розуміти, що відбувається, і ухвалювати правильні рішення.

Крок 1. BotFather і токен (і куди його НЕ класти)

Єдиний офіційний спосіб створити бота — через @BotFather у самому Telegram:

Opus 5 коштує як Opus 4.8, а працює вдвічі дешевше за Fable — Anthropic продає не потужність, а економію токенів

Яку модель вмикати в Cursor під задачу: Composer, Grok, Claude і GPT

Файл .cursorrules і правила проєкту: як налаштувати Cursor під свій стек

Agent Mode у Cursor на максимум: Plan Mode і прийоми професіоналів

Робочий воркфлоу вайб-кодингу в Cursor, який доїжджає до продакшену

1. Напишіть /newbot.
2. Задайте відображуване ім’я бота (наприклад, «Мій перший бот»).
3. Задайте username — він обов’язково закінчується на bot (наприклад, my_first_1234_bot).
4. BotFather надішле токен — довгий рядок виду 8628738987:AAG....

Запам’ятайте головне: токен — це пароль від вашого бота. Будь-хто з цим токеном може керувати ботом. Тому його не можна вставляти прямо в код і тим паче комітити в git. Правильне місце — змінні оточення, про які поговоримо на кроці про секрети. Поки просто скопіюйте токен у надійне місце.

Крок 2. aiogram чи python-telegram-bot

Для Python є дві основні бібліотеки, і вибір залежить від задачі.

Для нашого першого бота візьмемо aiogram — він сучасний, швидкий і добре лягає на асинхронну природу ботів. Саме тут Cursor і виручає: асинхронний код з async/await — типове місце, де новачок плутається, а агент напише коректний каркас і пояснить кожен рядок.

Крок 3. Просіть план, а не одразу код

Головна помилка новачка в Cursor — одразу вимагати «напиши мені бота цілком». Агент видасть стіну коду, у якій ви не розберетеся, а перша ж помилка заведе в глухий кут. Професійний підхід — спершу план, потім код по кроках.

Увімкніть Plan Mode (сполучення Shift+Tab у полі вводу агента) і сформулюйте задачу людською мовою:

«Допоможи зібрати Telegram-бота на aiogram 3.x. Потрібні команди /start і /help, відповідь на текстові повідомлення відлунням, токен зі змінної оточення. Спершу запропонуй план по кроках, код не пиши.»

Агент поставить уточнювальні запитання й видасть план: встановлення залежностей, структура файлів, обробники, запуск. Ви читаєте план, за потреби правите — і лише потім просите реалізувати по одному кроку. Так ви рухаєтеся маленькими кроками й усе розумієте.

Крок 4. Правила проєкту: навчіть Cursor вашим вимогам

Щоб агент не вигадував стиль і не забував про безпеку, задайте йому правила. У Cursor це файли .cursor/rules/*.mdc — постійний контекст, що підкладається в кожен запит. Створіть .cursor/rules/telegram-bot.mdc:

---
description: Правила для Telegram-бота на aiogram
alwaysApply: true
---

- Бібліотека — aiogram 3.x, лише async/await.
- Токен і будь-які секрети — ЛИШЕ зі змінних оточення (os.getenv), ніколи не в коді.
- Кожен хендлер — окрема функція зі зрозумілим іменем.
- Логування через модуль logging, не print.

Тепер агент триматиме ці вимоги в голові протягом усієї роботи — і, що важливо, сам не стане хардкодити токен.

Крок 5. Секрети: .env, .gitignore і головна пастка Cursor

Ось місце, заради якого варто читати саме цей гайд. Правильний спосіб зберігати токен — у файлі .env:

BOT_TOKEN=8628738987:AAG...ваш_токен

У коді токен читається з оточення:

import os
from dotenv import load_dotenv

load_dotenv()
TOKEN = os.getenv("BOT_TOKEN")

І обов’язково додайте .env у .gitignore, щоб він не потрапив у git:

.env

А тепер пастка, специфічна для Cursor. Файл .env ви створюєте саме для того, щоб токен не лежав у коді. Але ІІ-агент Cursor читає файли вашого проєкту, щоб розуміти контекст, — і .env він теж прочитає, якщо його не виключити. Токен-пароль поїде в контекст моделі.

Рішення — файл .cursorignore в корені проєкту (працює як .gitignore, але для агента Cursor):

.env

Це стик двох світів безпеки, який не проговорює жоден звичайний Telegram-туторіал: .gitignore ховає секрет від git, .cursorignore — від ІІ-агента. Потрібні обидва.

Крок 6. Хендлери й запуск

Тепер можна просити агента реалізувати бота. Мінімальний каркас на aiogram виглядає так:

import asyncio, os, logging
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import Message
from dotenv import load_dotenv

load_dotenv()
logging.basicConfig(level=logging.INFO)
bot = Bot(os.getenv("BOT_TOKEN"))
dp = Dispatcher()

@dp.message(Command("start"))
async def start(msg: Message):
    await msg.answer("Привіт! Я твій перший бот.")

@dp.message()
async def echo(msg: Message):
    await msg.answer(msg.text)

async def main():
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

Коли агент щось пропонує, читайте диф і приймайте зміни усвідомлено, а не тисніть «прийняти все» наосліп. Не розумієте рядок — спитайте агента прямо в чаті: «поясни, що робить dp.start_polling».

Крок 6.5. Зробимо бота корисним: кнопки й меню

Ехо-бот — це навчальний мінімум. Справжня користь починається, коли в бота є зрозуміле меню і він щось робить. Найпростіший спосіб — кнопки під повідомленням (inline-клавіатура). Попросіть агента: «додай до команди /start дві кнопки — „Про бота“ і „Допомога“ — й обробив їхні натискання». Він видасть приблизно таке:

from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton
from aiogram.filters import Command
from aiogram import F

@dp.message(Command("start"))
async def start(msg: Message):
    kb = InlineKeyboardMarkup(inline_keyboard=[[
        InlineKeyboardButton(text="Про бота", callback_data="about"),
        InlineKeyboardButton(text="Допомога", callback_data="help"),
    ]])
    await msg.answer("Привіт! Обери дію:", reply_markup=kb)

@dp.callback_query(F.data == "about")
async def about(cb):
    await cb.message.answer("Мене зібрано в Cursor за один вечір.")
    await cb.answer()

Далі за тим самим принципом навішується будь-яка логіка: запит погоди, нагадування, приймання заявок. Важливий прийом — рухатися по одній фічі за раз: додали кнопки, перевірили, закомітили; потім наступну функцію. Це рівно той підхід «маленькими кроками», що відділяє робочого бота від каші, яку потім неможливо чинити.

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

Крок 7. Тест локально: polling

Тут важливо зрозуміти різницю двох способів, якими бот отримує повідомлення:

• Polling — бот сам постійно питає Telegram «є нові повідомлення?». Просто, не потребує сервера й домену — ідеально для локальної розробки й тесту.
• Webhook — Telegram сам надсилає повідомлення на вашу адресу. Потребує HTTPS і публічного домену — це для продакшену.

Для тесту запускаємо polling (dp.start_polling у коді вище). Встановіть залежності й запустіть:

pip install aiogram python-dotenv
python bot.py

Відкрийте свого бота в Telegram, напишіть /start — він має відповісти. Працює локально? Чудово, половина справи зроблена.

Крок 8. Деплой: куди поселити бота

Бот на ноутбуці живе, поки відкритий термінал. Щоб він працював цілодобово, потрібен хостинг. Три популярні варіанти:

Для першого бота Railway — найм’якший вхід. По кроках:

1. Залийте код у репозиторій на GitHub (про це попросіть агента, якщо не знаєте git — він підкаже команди).
2. Переконайтеся, що в репозиторії є requirements.txt зі списком залежностей (aiogram, python-dotenv) — агент згенерує його командою або руками.
3. У Railway створіть новий проєкт → Deploy from GitHub repo → оберіть свій репозиторій.
4. У налаштуваннях проєкту, у розділі Variables, додайте змінну BOT_TOKEN зі значенням вашого токена. Саме тут, а не в коді — так токен потрапить в оточення сервера, але не в git.
5. Railway сам збере проєкт і запустить бота.

За практикою простий хобі-бот на polling витрачає близько 40 центів на тиждень, тож безкоштовного кредиту Railway ($5) вистачає на пару-трійку місяців. Коли кредит закінчиться, тариф Hobby коштує недорого — для одного бота це копійки.

При переїзді в продакшен на постійний домен є сенс перемкнутися з polling на webhook — це надійніше під навантаженням. Попросіть агента переписати запуск під webhook: він знає шаблон і пояснить, що поміняти.

Типові помилки й ризики новачка

Щоб не наступити на граблі, про які дізнаються вже в бою:

• Токен витік у git. Найчастіша й найболючіша помилка. Перевірте, що .env у .gitignore ДО першого коміту. Якщо токен усе ж потрапив в історію — негайно перевипустіть його через BotFather (команда /token) й отримайте новий.
• Токен поїхав у контекст Cursor. Той самий .cursorignore — не забудьте про нього, інакше секрет прочитає агент.
• Тимчасовий бан від Telegram. При частих перезапусках бота й повторних авторизаціях Telegram може тимчасово обмежити бота. Не смикайте перезапуск у циклі — особливо якщо агент «чинить» бота ітераціями.
• Агент щось вигадав. ІІ-інструменти інколи «галюцинують» — пропонують неіснуючі методи бібліотеки. Якщо код не запускається з дивною помилкою, звіртеся з офіційною документацією aiogram, а не сліпо довіряйте агентові.
• Сплутали polling і webhook. Не можна запускати обидва одночасно — Telegram віддає повідомлення або туди, або туди. На локалі — polling, у проді — webhook, але не разом.

Відлагодження: що робити, коли бот мовчить

Бот не відповідає — найчастіша ситуація в новачка. Пройдіть по списку, перш ніж кликати агента чинити навмання:

• Токен не підхопився. Перевірте, що .env лежить поруч із bot.py, змінна називається рівно BOT_TOKEN, а load_dotenv() викликаний до читання токена. Порожній токен — найчастіша причина «тиші».
• Бот запущений, але в іншому чаті. Переконайтеся, що пишете саме тому боту, чий username вам видав BotFather, а не старому тестовому.
• Помилка в логах. Ми не дарма ввімкнули logging — при запуску дивіться в термінал. Пітонівський traceback прямо вкаже рядок із проблемою; скопіюйте його агентові в чат, і він пояснить причину.
• Конфлікт polling/webhook. Якщо раніше ставили webhook, а тепер запускаєте polling, Telegram може віддавати повідомлення «у старі двері». Попросіть агента додати await bot.delete_webhook(drop_pending_updates=True) перед стартом polling.
• Не ті версії бібліотек. Код під aiogram 2.x не запрацює на aiogram 3.x — синтаксис змінився. Перевірте, що встановлена версія 3.x, і явно скажіть агентові, під яку версію писати.

Гарна звичка — просити агента додавати зрозумілі повідомлення в лог на кожному кроці. Тоді будь-який збій видно одразу, а не перетворюється на загадкову тишу.

Якого бота зібрати першим

Щоб не застрягнути на виборі ідеї, почніть із простого, але корисного особисто вам. Хороші перші проєкти:

• Бот-нагадувалка — приймає текст і час, надсилає нагадування. Учить працювати зі станом і планувальником.
• Бот-шпаргалка — за командою видає заготовлені відповіді (розклад, контакти, посилання). Майже чиста логіка на кнопках.
• Бот-агрегатор — за запитом підтягує дані з відкритого API (курс валют, погода, статус сервісу). Учить робити HTTP-запити.
• Бот для заявок — збирає форму по кроках і надсилає вам у приватні. Знадобиться для маленького бізнесу.

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

Коротко про головне

Зібрати Telegram-бота в Cursor реально за один вечір, навіть без досвіду в Python: токен у BotFather, aiogram для логіки, Plan Mode замість «напиши все одразу», секрети в .env — і обов’язково в .cursorignore, щоб токен не поїхав до агента. Локально тестуємо на polling, у хмару викочуємо на Railway. Головне — рухатися маленькими кроками й розуміти кожен рядок, а не приймати код наосліп.

Щоб така збірка перестала бути разовим везінням, її варто поставити на процес: правила проєкту, план, маленькі кроки, рев’ю і перевірка перед запуском — це робочий воркфлоу вайб-кодингу в Cursor.

Якщо вам сподобався сам підхід «будую продукт з ІІ», почитайте, що таке вайб-кодинг і де в нього межі — бот тут лише початок. А далі той самий шлях веде до серйозніших проєктів: вебзастосунків, автоматизацій, власних інструментів. Навичка лишається тією самою — чітко ставити задачу, рухатися маленькими кроками й розуміти код, який пише агент.

Поширені запитання

Чи потрібно знати Python, щоб зібрати бота в Cursor? Для першого простого бота — ні. Код пише агент, а ваше завдання — розуміти логіку й ухвалювати рішення. Але базове розуміння Python сильно прискорить подальшу роботу.

Де взяти токен для бота? Лише в @BotFather у Telegram: команда /newbot, задаєте ім’я й username, у відповідь отримуєте токен. Це єдиний офіційний спосіб.

Чим polling відрізняється від webhook? Polling — бот сам питає Telegram про нові повідомлення, підходить для локального тесту без сервера. Webhook — Telegram надсилає повідомлення на вашу HTTPS-адресу, потрібен для продакшену. Одночасно використовувати не можна.

Як безпечно зберігати токен у Cursor? У файлі .env, читати через змінні оточення. Додайте .env і в .gitignore (щоб не потрапив у git), і в .cursorignore (щоб його не прочитав ІІ-агент). Потрібні обидва файли.

Куди задеплоїти бота безкоштовно? На старті підійде Railway ($5 безкоштовного кредиту) або Render (free-тариф на 750 годин, але сервіс «засинає» без активності). Токен задавайте у змінних оточення хостингу, а не в коді.