Telegram Bot API

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

· 9 мин чтения

Для сайтов у 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. Заведите бота, который будет представлять сайт (как создать бота в Telegram). Его имя и аватарку пользователь увидит в окне подтверждения, так что пусть они совпадают с названием и логотипом сайта.
  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%D1%81%D0%BC%D0%BE%D1%82%D1%80%D0%B8%D1%82%D0%B5%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 Login Widget на сервере?

Для старого виджета соберите 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, разметка и кнопки

Как отправить сообщение через бота Telegram: sendMessage на curl, Python и JavaScript, parse_mode HTML и MarkdownV2, кнопки и ошибки 400, 403, 429.

Токен бота Telegram: как получить, где найти, как проверить и отозвать

Как получить токен бота Телеграм в @BotFather, где взять токен уже созданного бота, как проверить его через getMe и что делать, если токен утёк.

Вебхук для Telegram-бота: настройка setWebhook, проверка и удаление

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

Как узнать chat id в Telegram: пользователь, группа, канал и тема форума

Как узнать chat id в Telegram через 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.