Telegram Bot API

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

· 9 хв читання

Для входу через 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, документація в архівіТак, домен прив'язується командою /setdomaincore.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.

  1. Заведіть бота, який представлятиме сайт (як створити бота в Телеграм). Його ім'я та аватарку користувач побачить у вікні підтвердження, тож нехай вони збігаються з назвою й логотипом сайту.
  2. Зареєструйте Allowed URLs. Відкрийте Mini App @BotFather, виберіть бота, потім розділ Login Widget. Додайте origin сторінок, де стоїть кнопка (наприклад, https://example.com), і redirect URI для OIDC (наприклад, https://example.com/auth/callback). Telegram обробляє вхід і робить редиректи лише для заздалегідь зареєстрованих адрес.
  3. Збережіть Client ID і Client Secret з того самого розділу. Секрет зберігайте тільки на сервері.
  4. Додайте кнопку на сторінку.
  5. Перевірте 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
profileID користувача, ім'я, 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. Його документація в архіві, тож нові проєкти робіть за схемою вище, але якщо ви підтримуєте старий віджет, ось як він улаштований.

  1. Надішліть @BotFather команду /setdomain, щоб прив'язати домен сайту до бота.
  2. Вставте скрипт. Варіант із колбеком:
<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;

Типові проблеми

Що далі

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

Як додати на сайт кнопку входу через 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.