Telegram Bot API

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

· 8 хв читання

Щоб надіслати повідомлення через бота телеграм, достатньо одного HTTP-запиту до методу sendMessage: https://api.telegram.org/bot<token>/sendMessage з параметрами chat_id (кому) і text (що). Нижче — готові приклади на curl, Python і JavaScript, форматування через parse_mode (HTML і MarkdownV2), inline-кнопки, надсилання в групи й канали та розбір помилок, які найчастіше повертає Telegram Bot API.

Telegram Bot API: надіслати повідомлення — формат запиту

Будь-який метод Telegram Bot API викликається за адресою https://api.telegram.org/bot<token>/НАЗВА_МЕТОДУ. Зверніть увагу: слово bot пишеться разом із токеном, без скісної риски. Підтримуються GET і POST, а параметри можна передати в query string, як application/x-www-form-urlencoded, application/json або multipart/form-data (останній потрібен для завантаження файлів).

У sendMessage два обов'язкові параметри:

Відповідь завжди приходить у JSON: у разі успіху — "ok": true і надіслане повідомлення (об'єкт Message) у полі result, у разі помилки — "ok": false, error_code і description. І головне обмеження: бот не може написати користувачеві першим. Людина має сама відкрити бота й натиснути «Почати» (/start).

Надсилання повідомлення через curl

Найшвидший спосіб перевірити, що все працює. Підставте свій токен і chat id:

TOKEN="123456789:AAEexampleTokenReplaceWithYours"

curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{"chat_id": 123456789, "text": "Привіт! Це повідомлення надіслано через Bot API"}'

Успішна відповідь (скорочено):

{
  "ok": true,
  "result": {
    "message_id": 42,
    "chat": {"id": 123456789, "first_name": "Олена", "type": "private"},
    "date": 1793275200,
    "text": "Привіт! Це повідомлення надіслано через Bot API"
  }
}

Якщо параметрів небагато, можна обійтися без JSON — curl сам закодує кирилицю та спецсимволи:

curl -s "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -d chat_id=123456789 \
  --data-urlencode "text=Збірка #512 пройшла успішно"

Приклад на Python (requests) і JavaScript (fetch)

import requests

TOKEN = "123456789:AAEexampleTokenReplaceWithYours"
API_URL = f"https://api.telegram.org/bot{TOKEN}"


def send_message(chat_id, text, **params):
    payload = {"chat_id": chat_id, "text": text, **params}
    resp = requests.post(f"{API_URL}/sendMessage", json=payload, timeout=10)
    data = resp.json()
    if not data["ok"]:
        raise RuntimeError(f"{data['error_code']}: {data['description']}")
    return data["result"]


msg = send_message(123456789, "Привіт із Python!")
print("message_id:", msg["message_id"])
// Node.js 18+: fetch вбудований. Запуск: BOT_TOKEN=... node send.mjs
const TOKEN = process.env.BOT_TOKEN ?? '123456789:AAEexampleTokenReplaceWithYours';

async function sendMessage(chatId, text, extra = {}) {
  const res = await fetch(`https://api.telegram.org/bot${TOKEN}/sendMessage`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ chat_id: chatId, text, ...extra }),
  });
  const data = await res.json();
  if (!data.ok) throw new Error(`${data.error_code}: ${data.description}`);
  return data.result;
}

const msg = await sendMessage(123456789, 'Привіт із JavaScript!');
console.log('message_id:', msg.message_id);

Функція повертає об'єкт Message: message_id знадобиться, щоб згодом відредагувати чи видалити повідомлення. Додаткові параметри передаються іменованими аргументами, наприклад send_message(chat_id, text, parse_mode="HTML"), а в JavaScript — об'єктом: sendMessage(chatId, text, { parse_mode: 'HTML' }).

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

parse_mode HTML: жирний текст, посилання й код

Щоб оформити текст, передайте "parse_mode": "HTML". Telegram розуміє обмежений набір тегів:

curl -s -X POST "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_id": 123456789,
    "parse_mode": "HTML",
    "text": "<b>Замовлення №1024 оплачено</b>\nСума: <code>$49.90</code>\n<a href=\"https://example.com/orders/1024\">Відкрити замовлення</a>"
  }'

Усі символи <, > і &, що не входять до тегу, треба замінити на &lt;, &gt; і &amp;. З іменованих HTML-сутностей API розуміє лише ці три та &quot;, а також будь-які числові. Введення користувачів екрануйте завжди:

import html

name = "<Олена & Ко>"  # прийшло від користувача
text = f"Нове замовлення від <b>{html.escape(name, quote=False)}</b>"
send_message(123456789, text, parse_mode="HTML")
const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');

const name = '<Олена & Ко>'; // прийшло від користувача
const text = `Нове замовлення від <b>${escapeHtml(name)}</b>`;
await sendMessage(123456789, text, { parse_mode: 'HTML' });

MarkdownV2 у Telegram: синтаксис та екранування

MarkdownV2 компактніший за HTML: *жирний*, _курсив_, __підкреслений__, ~закреслений~, ||спойлер||, `код`, [посилання](https://example.com), а рядки, що починаються з >, перетворюються на цитату. Підступ — в екрануванні: поза розміткою кожен із символів _ * [ ] ( ) ~ ` > # + - = | { } . ! треба випереджати зворотним слешем \, інакше API поверне помилку розбору. Сам \ теж екранується. Усередині `коду` і блоків ``` екрануються лише ` і \, а всередині круглих дужок посилання — ) і \.

import re

def escape_md2(text: str) -> str:
    return re.sub(r"([_*\[\]()~`>#+\-=|{}.!\\])", r"\\\1", text)

price = "$19.90 (знижка -10%)"
send_message(123456789, f"*Разом:* {escape_md2(price)}", parse_mode="MarkdownV2")
# буде надіслано текст: *Разом:* $19\.90 \(знижка \-10%\)
const escapeMd2 = (s) => s.replace(/[_*[\]()~`>#+\-=|{}.!\\]/g, '\\$&');

const price = '$19.90 (знижка -10%)';
await sendMessage(123456789, `*Разом:* ${escapeMd2(price)}`, { parse_mode: 'MarkdownV2' });
// буде надіслано текст: *Разом:* $19\.90 \(знижка \-10%\)

Старий режим Markdown залишено лише для зворотної сумісності: у ньому немає підкреслення, закреслення, спойлерів і цитат. Для нових ботів обирайте HTML або MarkdownV2, а якщо текст надходить від користувачів, HTML зазвичай надійніший — екранувати треба лише три символи.

Inline-кнопки: reply_markup з url і callback_data

Кнопки під повідомленням задаються параметром reply_markup з полем inline_keyboard — це масив рядів, а кожен ряд — масив кнопок. Кнопка з url відкриває посилання, кнопка з callback_data надсилає боту апдейт callback_query.

{
  "chat_id": 123456789,
  "text": "Підтвердьте замовлення №1024",
  "reply_markup": {
    "inline_keyboard": [
      [{"text": "Відкрити сайт", "url": "https://example.com"}],
      [
        {"text": "Підтвердити", "callback_data": "confirm:1024"},
        {"text": "Скасувати", "callback_data": "cancel:1024"}
      ]
    ]
  }
}

Як надіслати повідомлення в групу чи канал

curl -s "https://api.telegram.org/bot$TOKEN/sendMessage" \
  -d chat_id=@my_channel \
  --data-urlencode "text=Новий допис у каналі"

Тихі повідомлення, прев'ю посилань і відповіді

{
  "chat_id": 123456789,
  "text": "Нічний звіт готовий: https://example.com/report",
  "disable_notification": true,
  "link_preview_options": {"is_disabled": true},
  "protect_content": true,
  "reply_parameters": {"message_id": 42}
}

Типові помилки sendMessage і що з ними робити

ПомилкаПричинаЩо робити
400 Bad Request: chat not foundНеправильний chat_id, користувач не запускав бота, бота немає в групі чи каналіПеревірте id через getUpdates, додайте бота в чат
400 Bad Request: can't parse entitiesПомилка розмітки: неекранований символ MarkdownV2 або незакритий тегЕкрануйте текст, перевірте теги
400 Bad Request: message is too longТекст довший за 4096 символівРозбийте його на кілька повідомлень
401 UnauthorizedНеправильний або відкликаний токенПеревірте токен через getMe
403 Forbidden: bot was blocked by the userКористувач заблокував ботаВилучіть його з розсилки
403 Forbidden: bot can't initiate conversation with a userКористувач жодного разу не запускав ботаПопросіть його натиснути «Почати»
429 Too Many Requests: retry after NПеревищено ліміт частотиЗачекайте retry_after секунд і повторіть

Так виглядає відповідь із помилкою 429:

{"ok": false, "error_code": 429, "description": "Too Many Requests: retry after 7", "parameters": {"retry_after": 7}}

Докладно про ліміти та про те, як робити розсилки без 429, — у гайді ліміти Telegram Bot API.

Спробуйте sendMessage без коду

  1. Відкрийте Bot API Tester на формі sendMessage.
  2. Вставте токен бота. Якщо токена ще немає, допоможе гайд як отримати токен бота.
  3. Заповніть chat_id і text, за бажанням оберіть parse_mode і додайте reply_markup.
  4. Натисніть Ctrl+Enter: у відповіді з'явиться message_id або текст помилки.

Повний опис усіх параметрів методу — на сторінці sendMessage. Окрім тексту, бот може надіслати й інтерактивний віджет методом sendWidget — готовий код є в гайді приклади віджетів Telegram.

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

Як надіслати повідомлення через бота телеграм без бібліотек?

Надішліть HTTP-запит на https://api.telegram.org/bot<token>/sendMessage з параметрами chat_id і text. Підійде curl, requests у Python або fetch у JavaScript — SDK для цього не потрібен.

Чому бот не може написати користувачеві першим?

Так влаштований Telegram: бот не може сам почати діалог. Користувач має відкрити бота й натиснути «Почати» (/start) — доти sendMessage повертатиме помилку (400 chat not found або 403).

Які символи треба екранувати в MarkdownV2?

Поза розміткою — _ * [ ] ( ) ~ ` > # + - = | { } . ! і сам зворотний слеш: перед кожним ставиться \. Інакше Telegram поверне помилку 400 про те, що не може розібрати сутності.

Як надіслати повідомлення в канал через бота?

Зробіть бота адміністратором каналу з правом публікації і вкажіть у chat_id @username каналу. Для приватного каналу використовуйте числовий id на кшталт -1001234567890.

Що обрати для parse_mode: HTML чи MarkdownV2?

Для тексту від користувачів надійніший HTML: екранувати треба лише <, > і &. MarkdownV2 компактніший, але вимагає екранувати 18 спецсимволів.

Що робити з помилкою 429 Too Many Requests?

Зачекати стільки секунд, скільки вказано в parameters.retry_after, і повторити запит. Щоб не ловити 429, тримайте темп не вище 1 повідомлення на секунду в один чат і близько 30 повідомлень на секунду загалом.

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

Як створити бота в Телеграм: реєстрація в @BotFather, токен, перевірка через getMe, перше повідомлення на curl і Python, команди та опис бота.

Що нового в 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: як отримати, де знайти, як перевірити й відкликати

Токен бота Телеграм: як отримати його в @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.