Telegram Bot API

Як створити бота в Телеграм: від @BotFather до першого повідомлення

· 8 хв читання

Щоб створити бота в Телеграм, надішліть @BotFather команду /newbot, задайте ім'я та username із закінченням bot — у відповідь прийде токен, з яким бота вже можна викликати через Bot API. Реєстрація займає кілька хвилин і нічого не коштує. Нижче — покрокова інструкція: перевіримо токен через getMe, дізнаємося chat id, надішлемо перше повідомлення на curl і Python, налаштуємо команди й розберемо, куди рухатися далі.

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

Крок 1. Створіть телеграм-бота через BotFather

@BotFather — офіційний бот Telegram, через який створюють і налаштовують усіх інших ботів. Шукайте саме @BotFather з позначкою верифікації: підробки мають схожі імена.

  1. Відкрийте @BotFather і надішліть команду /newbot.
  2. Введіть ім'я (name) — воно показується в профілі та списку чатів. Можна українською і з пробілами, пізніше його змінюють командою /setname.
  3. Введіть username — 5–32 символи: латинські літери, цифри та підкреслення, наприкінці обов'язково bot, наприклад tetris_bot або TetrisBot. Регістр не має значення. Якщо ім'я зайняте, BotFather попросить вигадати інше.
  4. BotFather надішле повідомлення з посиланням на бота вигляду t.me/your_bot і токеном для доступу до HTTP API.

Обирайте username уважно: на відміну від імені, його не можна змінити пізніше. Ті самі дії доступні в Mini App @BotFather — функції там ті самі, лише через кнопки.

Крок 2. Збережіть токен

Токен має вигляд 123456789:AAEexampleTokenReplaceWithYours: число, двокрапка й секретний рядок. Це водночас логін і пароль бота — будь-хто, хто його має, повністю керує ботом. Тому:

Де знайти токен пізніше, як його перевірити й відкликати — в окремому гайді як отримати токен бота.

Крок 3. Перевірте токен через getMe

Метод getMe не потребує параметрів і потрібен саме для цього — перевірити токен. Адреса будь-якого методу має вигляд https://api.telegram.org/bot<token>/НАЗВА_МЕТОДУ, причому слово bot пишеться разом із токеном.

export BOT_TOKEN="123456789:AAEexampleTokenReplaceWithYours"

curl -s "https://api.telegram.org/bot$BOT_TOKEN/getMe"

Якщо токен робочий, прийде "ok": true, а в result — об'єкт бота: id, first_name, username і прапорці на кшталт can_join_groups та can_read_all_group_messages. Відповідь 401 Unauthorized означає, що токен скопійовано з помилкою або вже відкликано, а 404 Not Found — що адресу складено неправильно: найчастіше забули bot перед токеном.

Без термінала: відкрийте getMe у Bot API Tester, вставте токен і натисніть Ctrl+Enter. Токен залишається в localStorage вашого браузера, а запити йдуть напряму на api.telegram.org.

Крок 4. Дізнайтеся chat id і надішліть перше повідомлення

Бот не може написати людині першим: спочатку користувач має відкрити чат із ботом і натиснути «Почати» (Start) — клієнт надішле команду /start. Зробіть це зі свого акаунта, а потім заберіть апдейти методом getUpdates:

curl -s "https://api.telegram.org/bot$BOT_TOKEN/getUpdates"
{
  "ok": true,
  "result": [
    {
      "update_id": 851234567,
      "message": {
        "message_id": 1,
        "from": {"id": 123456789, "is_bot": false, "first_name": "Олена", "language_code": "uk"},
        "chat": {"id": 123456789, "first_name": "Олена", "type": "private"},
        "date": 1793275200,
        "text": "/start"
      }
    }
  ]
}

Потрібне значення — message.chat.id. В особистому чаті воно збігається з id користувача в from.id. Якщо result порожній, напишіть боту ще раз: апдейти зберігаються не довше 24 годин. Як знайти id групи чи каналу, розібрано в гайді як дізнатися chat id.

Тепер надішлемо повідомлення методом sendMessage:

curl -s -X POST "https://api.telegram.org/bot$BOT_TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Привіт! Це мій перший бот"}'

Те саме на Python або JavaScript, а заразом найпростіший ехо-бот на long polling — він відповідає на кожне текстове повідомлення:

import os
import requests

TOKEN = os.environ.get("BOT_TOKEN", "123456789:AAEexampleTokenReplaceWithYours")
API = f"https://api.telegram.org/bot{TOKEN}"


def call(method, **params):
    data = requests.post(f"{API}/{method}", json=params, timeout=40).json()
    if not data["ok"]:
        raise RuntimeError(f"{method}: {data['error_code']} {data['description']}")
    return data["result"]


call("sendMessage", chat_id=123456789, text="Привіт із Python!")

offset = 0
while True:
    # long polling: Telegram тримає запит до 30 секунд, поки не з'являться апдейти
    for update in call("getUpdates", offset=offset, timeout=30):
        offset = update["update_id"] + 1  # підтверджуємо отримані апдейти
        message = update.get("message")
        if message and "text" in message:
            call("sendMessage", chat_id=message["chat"]["id"], text="Ви написали: " + message["text"])
// збережіть як bot.mjs і запустіть: BOT_TOKEN=... node bot.mjs
const TOKEN = process.env.BOT_TOKEN ?? "123456789:AAEexampleTokenReplaceWithYours";
const API = `https://api.telegram.org/bot${TOKEN}`;

async function call(method, params = {}) {
  const data = await (await fetch(`${API}/${method}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(params),
    signal: AbortSignal.timeout(40_000),
  })).json();
  if (!data.ok) {
    throw new Error(`${method}: ${data.error_code} ${data.description}`);
  }
  return data.result;
}

await call("sendMessage", { chat_id: 123456789, text: "Привіт із JavaScript!" });

let offset = 0;
while (true) {
  // long polling: Telegram тримає запит до 30 секунд, поки не з'являться апдейти
  for (const update of await call("getUpdates", { offset, timeout: 30 })) {
    offset = update.update_id + 1; // підтверджуємо отримані апдейти
    const message = update.message;
    if (message && "text" in message) {
      await call("sendMessage", { chat_id: message.chat.id, text: "Ви написали: " + message.text });
    }
  }
}

Запустіть скрипт (BOT_TOKEN=... python bot.py) і напишіть боту — він відповість. Параметр offset обов'язковий: без нього getUpdates знову й знову повертатиме ті самі апдейти. Форматування, кнопки та помилки надсилання детально розібрано в гайді як надіслати повідомлення через бота.

Крок 5. Опис і команди бота

Необов'язковий, але корисний крок: користувач одразу зрозуміє, що вміє бот. Основні команди @BotFather:

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

curl -s -X POST "https://api.telegram.org/bot$BOT_TOKEN/setMyCommands" \
  -H "Content-Type: application/json" \
  -d '{"commands": [
        {"command": "start", "description": "Запустити бота"},
        {"command": "help", "description": "Що вміє бот"},
        {"command": "settings", "description": "Налаштування"}
      ]}'

Обмеження: команда — 1–32 символи (малі латинські літери, цифри й підкреслення), опис — 1–256 символів, загалом не більше 100 команд. Параметри scope і language_code дають змогу показувати різні списки в групах, адміністраторам і користувачам з різними мовами. Telegram радить усім ботам підтримувати /start і /help, а за наявності налаштувань — /settings. Описи теж задаються з коду: методи setMyDescription і setMyShortDescription.

Якщо щось не працює

СимптомПричина й рішення
401 UnauthorizedНеправильний або відкликаний токен. Скопіюйте його знову: /mybots → бот → API Token
getUpdates повертає "result": []Нових повідомлень немає або минуло понад 24 години. Напишіть боту й повторіть запит
409 Conflict у відповідь на getUpdatesУ бота встановлено вебхук або токен паралельно використовує інший процес. Викличте deleteWebhook або зупиніть другий екземпляр
403 Forbidden: bot can't initiate conversation with a userКористувач ще не запускав бота — хай відкриє чат і натисне «Почати»
400 Bad Request: chat not foundНеправильний chat_id або бота немає в цьому чаті
Бот мовчить у групіУвімкнено privacy mode: бот бачить лише команди вигляду /start@your_bot, відповіді на свої повідомлення та службові повідомлення

Що далі: polling, вебхук, бібліотеки та Mini Apps

Polling чи вебхук. Ехо-бот вище працює на long polling: він сам забирає апдейти через getUpdates, тому запускається будь-де, навіть за NAT. У продакшені часто обирають вебхук — Telegram сам надсилає апдейти на вашу HTTPS-адресу. Одночасно обидва способи не працюють. Налаштування описано в гайді вебхук для телеграм-бота.

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

Бібліотеки. Працювати з HTTP вручну корисно для розуміння, але справжнього бота простіше писати на фреймворку: він візьме на себе polling, маршрутизацію команд, клавіатури та стан діалогів.

Mini Apps. Якщо інтерфейс не вміщується в повідомлення й кнопки, бот може відкривати вебзастосунок просто всередині Telegram. Як його зробити й налагодити, розповідає гайд тестування Mini App, а спробувати Telegram.WebApp API можна в Mini App Tester. Усі методи Bot API з параметрами й прикладами зібрано в довіднику методів.

Віджети. Із Bot API 10.4 бот може надсилати просто в повідомленні інтерактивний HTML-віджет — докладніше в гайді віджети Telegram. А якщо потрібен вхід через Telegram на вашому сайті, той самий бот знадобиться для віджета авторизації.

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

Скільки коштує створити бота в Телеграм?

Нічого: реєстрація в @BotFather і запити до Bot API безкоштовні. Платити доведеться лише за сервер, якщо бот має працювати цілодобово, і за окремі функції на кшталт платних розсилок.

Чи можна створити бота без програмування?

Зареєструвати бота в @BotFather можна без коду, але сам по собі він нічого не робить. Відповідатиме на повідомлення ваш скрипт, фреймворк або сервіс автоматизації на кшталт n8n, якому ви передасте токен.

Який username можна дати боту?

5–32 символи: латинські літери, цифри та підкреслення, наприкінці обов'язково bot — наприклад, tetris_bot або TetrisBot. На відміну від імені, username потім змінити не можна.

Чому щойно створений бот не відповідає?

Бот відповідає, лише поки працює ваш код: він отримує апдейти через getUpdates або вебхук і викликає sendMessage. Перевірте токен через getMe і переконайтеся, що запущено рівно один екземпляр бота.

Як додати боту команди в меню?

Командою /setcommands в @BotFather або методом setMyCommands. Команда — до 32 символів із малих латинських літер, цифр і підкреслень, опис — до 256 символів, загалом до 100 команд.

На чому писати Telegram-бота: Python чи JavaScript?

Підійде будь-яка мова, що вміє надсилати HTTP-запити. На Python найчастіше обирають aiogram або python-telegram-bot, на Node.js — grammY або Telegraf.

Що нового в Telegram Bot API 10.0–10.5: налаштування бота, віджети, rich-повідомлення, ефемерні повідомлення й гостьовий режим

Що нового в Telegram Bot API 10.0–10.5: setMySettings і BotFullInfo, HTML-віджети, rich- та ефемерні повідомлення, гостьовий режим — з прикладами.

Ліміти Telegram Bot API: повідомлення на секунду, помилка 429 і розміри файлів

Ліміти Telegram Bot API в одному місці: повідомлення на секунду, помилка 429 і retry_after, платні розсилки, розміри файлів, довжина тексту й підпису.

Як надіслати повідомлення через бота Telegram: sendMessage, розмітка й кнопки

Як надіслати повідомлення через бота телеграм: sendMessage на curl, Python і JavaScript, parse_mode HTML і MarkdownV2, кнопки та помилки 400, 403, 429.

Токен бота Telegram: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @BotFather, де знайти токен наявного бота, як перевірити через getMe і що робити, якщо токен витік.

Вебхук для телеграм-бота: налаштування setWebhook, перевірка та видалення

Як налаштувати вебхук телеграм-бота: вимоги до HTTPS і портів, setWebhook із secret_token, перевірка через getWebhookInfo, видалення та типові помилки.

Як дізнатися chat id у Телеграм: користувач, група, канал і тема форуму

Як дізнатися chat id у Телеграм через getUpdates: особистий чат, група, супергрупа, канал і тема форуму. Формати id з -100 і що робити з порожнім result.

Тестовий сервер Telegram: як тестувати бота в тестовому середовищі

Тестовий сервер Telegram для ботів: вхід у тестове середовище, створення тестового бота, запити до Bot API через /test/ і перемикач TEST у тестері.

Віджети Telegram для сайту: вхід через Telegram, вбудовування постів, коментарі й кнопка «Поділитися»

Вхід через Telegram на сайті: новий Telegram Login (OIDC), старий Login Widget із перевіркою hash, вбудовування постів, коментарі та кнопка «Поділитися».

TelegramWidget JavaScript API: властивості, події, коди помилок і ліміти

Довідник TelegramWidget API: властивості, request(), події, коди помилок, CSS-змінні, widget_query та answerWidgetQuery, а також усі ліміти віджетів.

Приклади віджетів Telegram: готовий HTML і код бота на Python

Робочі приклади віджетів Telegram із повним кодом: картка замовлення, лічильник із запитами widget_query, спільне живе опитування та прев'ю в браузері.

Віджети Telegram: інтерактивний HTML просто в повідомленнях бота

Віджети Telegram у Bot API 10.4: що це, як працюють sendWidget, chat_data і public_data, де віджети доступні зараз і чим вони відрізняються від Mini Apps.

Тестування Telegram Mini App: від браузера до налагодження на телефоні

Тестування Telegram Mini App крок за кроком: mock-режим у браузері, HTTPS-тунель для localhost, тестове середовище, DevTools на телефоні та initData.