Як надіслати повідомлення через бота Telegram: sendMessage, розмітка й кнопки
Щоб надіслати повідомлення через бота телеграм, достатньо одного 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 два обов'язкові параметри:
chat_id— числовий ідентифікатор чату або@usernameпублічного каналу чи супергрупи. Якщо id ще невідомий, перегляньте гайд як дізнатися chat id;text— від 1 до 4096 символів, рахуючи після розбору розмітки.
Відповідь завжди приходить у 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 розуміє обмежений набір тегів:
<b>/<strong>— жирний,<i>/<em>— курсив,<u>/<ins>— підкреслений,<s>/<strike>/<del>— закреслений;<tg-spoiler>або<span class="tg-spoiler">— спойлер;<a href="…">— посилання, зокремаtg://user?id=…для згадки користувача;<code>,<pre>і<pre><code class="language-python">— код, в останньому випадку з підсвічуванням;<blockquote>і<blockquote expandable>— звичайна й розгортна цитата.
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>"
}'
Усі символи <, > і &, що не входять до тегу, треба замінити на <, > і &. З іменованих HTML-сутностей API розуміє лише ці три та ", а також будь-які числові. Введення користувачів екрануйте завжди:
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, '&').replace(/</g, '<').replace(/>/g, '>');
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"}
]
]
}
}
callback_data— від 1 до 64 байтів, а не символів: кирилична літера в UTF-8 займає 2 байти. Кладіть туди короткий ідентифікатор, а самі дані зберігайте в себе.- На кожне натискання відповідайте методом
answerCallbackQueryзcallback_query_idз апдейту: поки відповіді немає, клієнт Telegram показує на кнопці індикатор завантаження. - Якщо параметри йдуть не JSON-тілом, а через query string чи form-data,
reply_markupпередається рядком із серіалізованим JSON.
Як надіслати повідомлення в групу чи канал
- Група й супергрупа. Додайте бота в чат і використовуйте id чату: у звичайних груп він від'ємний, у супергруп починається з
-100, наприклад-1001234567890. Privacy mode обмежує лише вхідні повідомлення й на надсилання не впливає. - Канал. Бот має бути адміністратором із правом публікації. У
chat_idпідійде@usernameпублічного каналу або числовий id вигляду-100…для приватного. - Тема форуму. Додайте параметр
message_thread_idз id теми. - Групу перетворили на супергрупу. Старий id перестає працювати: API поверне помилку 400, а новий id прийде в
parameters.migrate_to_chat_id— збережіть його.
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}
}
disable_notification— повідомлення прийде без звуку;link_preview_options— налаштування прев'ю:is_disabledвимикає його,urlзадає посилання для прев'ю,show_above_textставить прев'ю над текстом;protect_content— заборона пересилання та збереження;reply_parameters— відповідь на конкретне повідомлення за йогоmessage_id.
Типові помилки 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 без коду
- Відкрийте Bot API Tester на формі sendMessage.
- Вставте токен бота. Якщо токена ще немає, допоможе гайд як отримати токен бота.
- Заповніть
chat_idіtext, за бажанням оберітьparse_modeі додайтеreply_markup. - Натисніть 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.