Віджети Telegram для сайту: вхід через Telegram, вбудовування постів, коментарі й кнопка «Поділитися»
Для входу через Telegram на сайті та інших інтеграцій Telegram пропонує чотири віджети: Telegram Login (реєстрація й вхід через акаунт Telegram), віджет поста (вбудовування повідомлення з публічного каналу чи групи), віджет обговорення (коментарі до поста каналу) і кнопку «Поділитися». Кожен із них — невеликий фрагмент коду, який ви вставляєте у свій HTML. Це не ті інтерактивні віджети, які боти надсилають просто в чат починаючи з Bot API 10.4; про них — у гайді віджети Telegram у повідомленнях бота.
Віджети Telegram для сайту: огляд
| Віджет | Що робить | Потрібен бот? | Де взяти код |
|---|---|---|---|
| Telegram Login | Реєстрація та вхід через акаунт Telegram (OpenID Connect) | Так, плюс Allowed URLs і Client ID з @BotFather | Конструктор на core.telegram.org/bots/telegram-login |
| Login Widget (legacy) | Стара кнопка входу в iframe, документація в архіві | Так, домен прив'язується командою /setdomain | core.telegram.org/widgets/login-legacy |
| Віджет поста | Вбудовує повідомлення з публічного каналу або групи | Ні | Посилання t.me → EMBED або конструктор постів |
| Віджет обговорення | Показує пост каналу разом із коментарями | Ні | Конструктор обговорень |
| Кнопка «Поділитися» | Дає змогу надіслати ваше посилання в чат, групу, канал або «Збережене» | Ні | Конструктор кнопки або звичайне посилання |
Вхід через Telegram на сайті: новий Telegram Login (OpenID Connect)
Актуальний Telegram Login — це JavaScript-бібліотека й водночас стандартний провайдер OpenID Connect з Authorization Code Flow і PKCE. Можна використати кнопку з бібліотеки, будь-яку OIDC-сумісну бібліотеку чи платформу ідентифікації (Telegram наводить як приклад Keycloak, Authentik і Auth0) або нативні SDK для iOS і Android.
- Заведіть бота, який представлятиме сайт (як створити бота в Телеграм). Його ім'я та аватарку користувач побачить у вікні підтвердження, тож нехай вони збігаються з назвою й логотипом сайту.
- Зареєструйте Allowed URLs. Відкрийте Mini App @BotFather, виберіть бота, потім розділ Login Widget. Додайте origin сторінок, де стоїть кнопка (наприклад,
https://example.com), і redirect URI для OIDC (наприклад,https://example.com/auth/callback). Telegram обробляє вхід і робить редиректи лише для заздалегідь зареєстрованих адрес. - Збережіть Client ID і Client Secret з того самого розділу. Секрет зберігайте тільки на сервері.
- Додайте кнопку на сторінку.
- Перевірте ID token на сервері, перш ніж довіряти даним користувача.
Код, який видає офіційний конструктор, має такий вигляд (data-request-access необов'язковий: write дозволяє ботові писати користувачеві, phone запитує підтверджений номер телефону):
<script async src="https://oauth.telegram.org/js/telegram-login.js?6" data-client-id="123456789" data-onauth="onTelegramAuth(data)" data-request-access="write"></script>
<button class="tg-auth-button">Увійти через Telegram</button>
<script>
function onTelegramAuth(data) {
if (data.error) return console.warn(data.error);
// Надсилаємо data.id_token на сервер і перевіряємо його там
fetch('/auth/telegram', {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({id_token: data.id_token})
});
}
</script>
У колбек надходить id_token (JWT за стандартом OIDC), user (уже розкодовані claims) або error. Бібліотека має і JS API: Telegram.Login.init(InitOptions, callback), Telegram.Login.open([callback]) і Telegram.Login.auth(InitOptions, callback) з опціями client_id, scope, lang і nonce (випадковий рядок, який генерує сервер; він потрапляє в id_token і захищає від replay-атак).
Popup і COOP:telegram-login.jsвзаємодіє зі спливним вікном. Якщо сайт віддає заголовокCross-Origin-Opener-Policy: same-origin, вхід не спрацює: приберіть заголовок або замініть значення наsame-origin-allow-popups.
Scopes та ендпоінти OIDC
| Scope | Що дає | Claims |
|---|---|---|
openid | Обов'язковий. Унікальний ідентифікатор і час авторизації | sub, iss, iat, exp |
profile | ID користувача, ім'я, username, URL фото | id, name, preferred_username, picture |
phone | Підтверджений номер телефону за згодою користувача | phone_number |
telegram:bot_access | Бот зможе писати користувачеві після входу | — |
Для OIDC-клієнта використовуйте discovery-документ https://oauth.telegram.org/.well-known/openid-configuration, response type code і PKCE з S256. Якщо реалізуєте потік вручну, ендпоінти такі: https://oauth.telegram.org/auth, https://oauth.telegram.org/token (POST із сервера з Basic-авторизацією base64(client_id:client_secret)) і https://oauth.telegram.org/.well-known/jwks.json. Окремого ендпоінта UserInfo в Telegram немає: усі дані містяться в ID token, тож якщо бібліотека за замовчуванням звертається до userinfo, вимкніть цей запит.
Перевірка ID token
Перевірте підпис JWT за ключами з JWKS, потім переконайтеся, що iss дорівнює https://oauth.telegram.org, aud збігається з ID бота (тим, що ви передаєте як client_id), а exp ще не настав. За замовчуванням токени підписуються RS256; ES256, EdDSA і ES256K можна обрати в @BotFather у розділі Login Widget > Advanced (з EdDSA і ES256K доступний лише scope openid). Приклад на Node.js з бібліотекою jose:
import { createRemoteJWKSet, jwtVerify } from 'jose';
const JWKS = createRemoteJWKSet(new URL('https://oauth.telegram.org/.well-known/jwks.json'));
export async function verifyTelegramIdToken(idToken) {
const { payload } = await jwtVerify(idToken, JWKS, {
issuer: 'https://oauth.telegram.org',
audience: '123456789' // ваш Client ID (ID бота)
});
return payload; // sub, id, name, preferred_username, picture, phone_number...
}
Класичний віджет авторизації Telegram (legacy)
На багатьох сайтах досі стоїть оригінальний Login Widget на iframe. Його документація в архіві, тож нові проєкти робіть за схемою вище, але якщо ви підтримуєте старий віджет, ось як він улаштований.
- Надішліть @BotFather команду
/setdomain, щоб прив'язати домен сайту до бота. - Вставте скрипт. Варіант із колбеком:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-login="your_bot" data-size="large" data-onauth="onTelegramAuth(user)" data-request-access="write"></script>
<script type="text/javascript">
function onTelegramAuth(user) {
alert('Ви увійшли як ' + user.first_name + ' ' + user.last_name + ' (' + user.id + (user.username ? ', @' + user.username : '') + ')');
}
</script>
Замість data-onauth можна вказати data-auth-url="https://example.com/auth/telegram": користувача буде перенаправлено туди з параметрами id, first_name, last_name, username, photo_url, auth_date і hash у query string. Інші опції конструктора: data-size (large, medium, small), data-userpic="false", data-radius і data-request-access="write".
Перевірка hash на сервері
Не довіряйте даним, доки не перевірили підпис. Алгоритм: візьміть усі отримані поля, крім hash, відсортуйте за абеткою та з'єднайте у вигляді key=value через переведення рядка (\n) — це data-check-string. Секретний ключ — SHA256 від токена бота (сирі байти). Обчисліть HMAC-SHA-256 від data-check-string цим ключем і порівняйте hex-результат із hash. Потім переконайтеся, що auth_date (Unix-час) достатньо свіжий. Передавайте на перевірку лише поля від Telegram, без власних query-параметрів.
import hashlib
import hmac
import time
def check_telegram_auth(data: dict, bot_token: str, max_age: int = 86400) -> bool:
fields = {k: v for k, v in data.items() if k != "hash"}
data_check_string = "\n".join(f"{k}={fields[k]}" for k in sorted(fields))
secret_key = hashlib.sha256(bot_token.encode()).digest()
calc_hash = hmac.new(secret_key, data_check_string.encode(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(calc_hash, str(data.get("hash", ""))):
return False
return time.time() - int(fields["auth_date"]) <= max_age
# Flask: check_telegram_auth(request.args.to_dict(), BOT_TOKEN)const crypto = require('crypto');
function checkTelegramAuth(data, botToken, maxAgeSec = 86400) {
const { hash, ...fields } = data;
const dataCheckString = Object.keys(fields).sort()
.map((k) => `${k}=${fields[k]}`)
.join('\n');
const secretKey = crypto.createHash('sha256').update(botToken).digest();
const calcHash = crypto.createHmac('sha256', secretKey).update(dataCheckString).digest('hex');
if (typeof hash !== 'string' || hash.length !== calcHash.length) return false;
if (!crypto.timingSafeEqual(Buffer.from(calcHash), Buffer.from(hash))) return false;
return Date.now() / 1000 - Number(fields.auth_date) <= maxAgeSec;
}
// Express: checkTelegramAuth(req.query, process.env.BOT_TOKEN)Найчастіше hash не збігається через неправильний токен. Переконайтеся, що токен на сервері належить саме боту для входу: викличте getMe у Bot API Tester — поле username у відповіді має збігатися з data-telegram-login. Якщо токен треба знайти або перевипустити, зазирніть у гайд як отримати токен бота. Зверніть увагу: це не те саме, що перевірка initData у Mini App, де ключ отримують через HMAC із рядком WebAppData.
Як вбудувати пост Telegram на сайт
Вбудувати можна будь-яке повідомлення з публічного каналу або групи. Відкрийте посилання на нього (наприклад, t.me/durov/43) у браузері й натисніть < > EMBED або вставте посилання в конструктор віджета поста. На виході отримаєте один тег script:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-post="durov/43" data-width="100%"></script>
Опції конструктора: ширина (data-width, за замовчуванням 100%), фото автора (data-userpic="true" — показувати завжди, "false" — приховати, без атрибута — автоматично), колір акценту (data-color з hex-значенням, наприклад 13B4C6) і темна тема (data-dark="1"; разом із кольором конструктор може додати ще й data-dark-color).
Віджет обговорення: коментарі з Telegram на сайті
Віджет обговорення показує пост публічного каналу разом із коментарями. Передайте йому посилання на пост із коментарями:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-discussion="contest/198" data-comments-limit="5"></script>
Можна вказати й лише канал (data-telegram-discussion="your_channel"). Тоді на кожній сторінці статті з'явиться обговорення того поста каналу, який посилається на цю сторінку, — одразу після того, як ви опублікуєте посилання в каналі. Для такого режиму в <head> сторінки має бути тег <link rel="canonical" href="%page_url%"> з канонічним URL сторінки. Опції: ліміт коментарів (data-comments-limit, у конструкторі від 3 до 50), data-height, data-colorful="1" для різнокольорових імен, data-color і data-dark="1".
Кнопка «Поділитися» в Telegram
Коли відвідувач натискає кнопку «Поділитися», Telegram пропонує обрати чат, групу або канал і дає змогу відредагувати необов'язковий текст перед надсиланням. Конструктор на core.telegram.org/widgets/share видає такий код:
<script async src="https://telegram.org/js/telegram-widget.js?24" data-telegram-share-url="https://example.com/article" data-comment="Подивіться!" data-size="large"></script>
Без data-size кнопка буде середнього розміру, а data-text="notext" залишає тільки іконку. Якщо потрібен власний дизайн, зробіть посилання https://t.me/share/url?url={url}&text={text}, закодувавши обидва значення:
<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=%D0%9F%D0%BE%D0%B4%D0%B8%D0%B2%D1%96%D1%82%D1%8C%D1%81%D1%8F%21">Поділитися в Telegram</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
+ '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;
Типові проблеми
- Старий віджет пише «Bot domain invalid». Домен не прив'язано до бота. Надішліть @BotFather команду
/setdomainдля цього бота й укажіть точний домен сторінки. - Новий вхід нічого не робить або відхиляється. Origin сторінки чи redirect URI немає в Allowed URLs в @BotFather, або спливне вікно блокує заголовок
Cross-Origin-Opener-Policy: same-origin. - Віджет не відображається.
telegram-widget.jsзавантажується зtelegram.orgі вставляє iframe: зt.meдля постів, обговорень і кнопки «Поділитися», зoauth.telegram.orgдля старого віджета входу. Їх може заблокувати сувора Content-Security-Policy (script-src,frame-src) або блокувальник реклами. - Hash не збігається. Неправильний токен бота, як ключ узято сам токен, а не його SHA256, у data-check-string потрапили зайві поля (ваші власні query-параметри), значення полів змінилися або обрано не той роздільник. Потрібен
\n, а не&. - Пост не вбудовується. Вбудувати можна лише повідомлення з публічних каналів і груп: у приватних чатів немає публічного посилання t.me.
- На сторінці статті порожнє обговорення. Перевірте, що на сторінці є тег canonical і що посилання, опубліковане в каналі, веде саме на канонічний URL.
Що далі
- Створіть бота в Телеграм, який представлятиме ваш сайт у вікні входу.
- Знайдіть, перевірте або відкличте токен бота — він потрібен для перевірки hash у старому віджеті.
- Віджети Telegram у повідомленнях бота — HTML-віджети Bot API 10.4, це окрема можливість.
- Офіційна документація: core.telegram.org/widgets.
Поширені запитання
Як додати на сайт кнопку входу через Telegram?
Оберіть бота, відкрийте Mini App @BotFather, виберіть бота й розділ Login Widget, додайте origin сайту та redirect URI в Allowed URLs і скопіюйте Client ID. Потім вставте на сторінку скрипт telegram-login.js з data-client-id і перевіряйте отриманий id_token на сервері.
Чи працює ще старий Telegram Login Widget?
Його документацію перенесено в архів: core.telegram.org/widgets/login-legacy. Основним способом входу через Telegram тепер описано бібліотеку Telegram Login та OpenID Connect, тож у нових проєктах використовуйте їх.
Як перевірити дані віджета авторизації Telegram на сервері?
Для старого віджета зберіть data-check-string з усіх отриманих полів, крім hash: рядки key=value, відсортовані за абеткою та з'єднані через \n. Обчисліть HMAC-SHA-256 із ключем SHA256(bot_token), порівняйте hex-результат із hash і перевірте auth_date. Для нового входу перевіряйте JWT id_token за ключами JWKS Telegram.
Як вбудувати пост Telegram на сайт?
Відкрийте посилання на пост у браузері (наприклад, t.me/durov/43) і натисніть EMBED або скористайтеся конструктором на core.telegram.org/widgets/post. Вбудувати можна лише пости з публічних каналів і груп.
Як зробити власну кнопку «Поділитися в Telegram»?
Зробіть посилання https://t.me/share/url?url={url}&text={text}, закодувавши обидва значення, наприклад через encodeURIComponent у JavaScript. Текст необов'язковий, і користувач може відредагувати його перед надсиланням.
Читайте також
Як створити бота в Телеграм: від @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: 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 у тестері.
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.