Telegram Bot API

ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنت‌ها و دکمه اشتراک‌گذاری

· 9 دقیقه مطالعه

تلگرام چهار ویجت برای وب‌سایت‌ها دارد: Telegram Login برای ورود با تلگرام در سایت (کاربر با حساب تلگرامش وارد می‌شود)، ویجت پست برای جاسازی پیام یک کانال یا گروه عمومی، ویجت گفت‌وگو برای نمایش کامنت‌های پست کانال و دکمه اشتراک‌گذاری. هر کدام یک تکه کد کوچک است که در HTML خودتان می‌چسبانید. این‌ها با ویجت‌های تعاملی که ربات‌ها از Bot API 10.4 داخل پیام چت می‌فرستند فرق دارند؛ برای آن‌ها ویجت تلگرام در پیام‌های ربات را بخوانید.

ویجت‌های تلگرام برای سایت در یک نگاه

ویجتکاربردربات لازم دارد؟کد را از کجا بگیریم
Telegram Loginثبت‌نام و ورود با حساب تلگرام (OpenID Connect)بله، به‌علاوه Allowed URLs و Client ID از @BotFatherسازنده در core.telegram.org/bots/telegram-login
Login Widget (قدیمی)دکمه ورود قدیمی مبتنی بر iframe، الان آرشیو شدهبله، با دامنه‌ای که با ‎/setdomain وصل شدهcore.telegram.org/widgets/login-legacy
ویجت پستجاسازی پیام یک کانال یا گروه عمومیخیرلینک t.me ← EMBED، یا سازنده ویجت پست
ویجت گفت‌وگو (Discussion)نمایش پست کانال همراه کامنت‌هایشخیرسازنده ویجت گفت‌وگو
دکمه اشتراک‌گذاریبازدیدکننده لینک شما را به چت، گروه، کانال یا Saved Messages می‌فرستدخیرسازنده دکمه Share یا یک لینک ساده

Telegram Login: ورود با تلگرام در سایت به روش جدید (OpenID Connect)

Telegram Login فعلی یک کتابخانه جاوااسکریپت است به‌علاوه یک ارائه‌دهنده استاندارد OpenID Connect که از Authorization Code Flow با PKCE استفاده می‌کند. می‌توانید از دکمه خود کتابخانه، هر کتابخانه یا پلتفرم هویتی سازگار با OIDC (تلگرام Keycloak، Authentik و Auth0 را مثال می‌زند) یا SDKهای بومی iOS و اندروید استفاده کنید.

  1. یک ربات برای سایت آماده کنید (آموزش ساخت ربات تلگرام). کاربر نام و عکس پروفایل همین ربات را در پنجره تأیید می‌بیند، پس آن‌ها را با نام و لوگوی سایت هماهنگ کنید.
  2. Allowed URLs را ثبت کنید. مینی اپ @BotFather را باز کنید، ربات را انتخاب کنید و بعد Login Widget را بزنید. originهایی که دکمه را در آن‌ها می‌گذارید (مثلاً https://example.com) و redirect URIهای OIDC (مثلاً https://example.com/auth/callback) را اضافه کنید. تلگرام ورود و ریدایرکت را فقط برای همین آدرس‌های از پیش ثبت‌شده انجام می‌دهد.
  3. Client ID و Client Secret را ذخیره کنید؛ هر دو در همین بخش نمایش داده می‌شوند. 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">ورود با تلگرام</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>

callback یکی از این‌ها را می‌گیرد: id_token (یک JWT استاندارد OIDC)، user (claimهای رمزگشایی‌شده) یا error. کتابخانه یک API جاوااسکریپت هم دارد: Telegram.Login.init(InitOptions, callback)، Telegram.Login.open([callback]) و Telegram.Login.auth(InitOptions, callback) با گزینه‌های client_id، scope، lang و nonce (رشته تصادفی که سرور می‌سازد و برای جلوگیری از حمله replay داخل id_token قرار می‌گیرد).

پنجره popup و COOP: telegram-login.js با یک پنجره popup کار می‌کند. اگر سایت شما هدر Cross-Origin-Opener-Policy: same-origin می‌فرستد، ورود شکست می‌خورد؛ هدر را بردارید یا از same-origin-allow-popups استفاده کنید.

scopeها و endpointهای OIDC

Scopeچه چیزی می‌دهدClaimها
openidالزامی. شناسه یکتا و زمان احراز هویتsub، iss، iat، exp
profileآیدی کاربر، نام، یوزرنیم، آدرس عکسid، name، preferred_username، picture
phoneشماره تلفن تأییدشده، با رضایت کاربرphone_number
telegram:bot_accessربات شما بعد از ورود می‌تواند به کاربر پیام بدهد—

برای کلاینت OIDC از discovery document در https://oauth.telegram.org/.well-known/openid-configuration، نوع پاسخ code و PKCE با S256 استفاده کنید. اگر جریان را دستی پیاده می‌کنید، endpointها این‌ها هستند: https://oauth.telegram.org/auth، https://oauth.telegram.org/token (درخواست POST سمت سرور با Basic auth به شکل base64(client_id:client_secret)) و https://oauth.telegram.org/.well-known/jwks.json. تلگرام endpoint جداگانه UserInfo ندارد و همه داده‌ها داخل ID token است؛ اگر کتابخانه شما درخواست userinfo می‌فرستد، آن را غیرفعال کنید.

اعتبارسنجی ID token

امضای JWT را با کلیدهای endpoint مربوط به JWKS بررسی کنید و بعد مطمئن شوید iss برابر https://oauth.telegram.org است، aud با آیدی ربات شما (همان مقداری که به عنوان 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 شما (آیدی ربات)
  });
  return payload; // sub, id, name, preferred_username, picture, phone_number...
}

Telegram Login Widget کلاسیک (قدیمی)

خیلی از سایت‌ها هنوز Login Widget قدیمی مبتنی بر iframe را دارند. مستندات آن آرشیو شده، پس در پروژه جدید از روش بالا استفاده کنید؛ اما اگر نگهداری یک پروژه قدیمی با شماست، این ویجت این‌طور کار می‌کند:

  1. دستور ‎/setdomain را به @BotFather بفرستید تا دامنه سایت به ربات وصل شود.
  2. اسکریپت را در صفحه بگذارید. نمونه با callback:
<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 parameter می‌رسند. گزینه‌های دیگر سازنده: 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 رشته را با این کلید حساب کنید و شکل hex آن را با hash مقایسه کنید. بعد بررسی کنید auth_date (Unix timestamp) تازه باشد. فقط فیلدهایی را حساب کنید که تلگرام فرستاده، نه query parameterهای خودتان را.

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 در مینی اپ فرق دارد؛ آنجا کلید با HMAC و رشته WebAppData ساخته می‌شود.

جاسازی پست تلگرام در سایت

هر پیامی از یک کانال یا گروه عمومی قابل جاسازی است. لینک t.me آن (مثلاً 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 را هم اضافه کند).

ویجت گفت‌وگو: کامنت‌های تلگرام در سایت

ویجت گفت‌وگو یک پست کانال عمومی را همراه کامنت‌هایش نشان می‌دهد. لینک پستی را که کامنت دارد به آن بدهید:

<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%"> را با آدرس canonical صفحه داشته باشد. گزینه‌ها: تعداد کامنت (data-comments-limit، در سازنده بین 3 تا 50)، data-height، data-colorful="1" برای رنگ‌های متفاوت نام‌ها، data-color و data-dark="1".

دکمه اشتراک‌گذاری تلگرام

وقتی بازدیدکننده دکمه اشتراک‌گذاری را می‌زند، تلگرام از او می‌خواهد چت، گروه یا کانال را انتخاب کند و اجازه می‌دهد متن اختیاری را قبل از ارسال ویرایش کند. سازنده 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="Check this out!" data-size="large"></script>

بدون data-size دکمه اندازه متوسط می‌شود و data-text="notext" فقط آیکون را نشان می‌دهد. برای طراحی دلخواه، به https://t.me/share/url?url={url}&text={text} لینک بدهید و هر دو مقدار را URL-encode کنید:

<a href="https://t.me/share/url?url=https%3A%2F%2Fexample.com%2Farticle&text=Check%20this%20out%21">اشتراک‌گذاری در تلگرام</a>
const shareUrl = 'https://t.me/share/url?url=' + encodeURIComponent(location.href)
  + '&text=' + encodeURIComponent(document.title);
document.querySelector('#tg-share').href = shareUrl;

رفع مشکلات رایج

قدم‌های بعدی

پرسش‌های متداول

چطور دکمه ورود با تلگرام را به سایتم اضافه کنم؟

یک ربات انتخاب کنید، مینی اپ @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 Login و جریان OpenID Connect را راه اصلی ورود با تلگرام معرفی می‌کند، پس در پروژه‌های جدید از همین‌ها استفاده کنید.

داده‌های Telegram Login Widget را روی سرور چطور بررسی کنم؟

در ویجت قدیمی، همه فیلدهای دریافتی به جز hash را به ترتیب الفبا به شکل خطوط key=value با \n به هم بچسبانید. HMAC-SHA-256 این رشته را با کلید SHA256(bot_token) حساب کنید، خروجی hex را با hash مقایسه کنید و auth_date را هم چک کنید. در ورود جدید، JWT مربوط به id_token را با JWKS تلگرام اعتبارسنجی کنید.

چطور یک پست تلگرام را در سایت جاسازی کنم؟

لینک t.me پست (مثلاً t.me/durov/43) را در مرورگر باز کنید و EMBED را بزنید، یا از سازنده core.telegram.org/widgets/post استفاده کنید. فقط پست‌های کانال‌ها و گروه‌های عمومی قابل جاسازی هستند.

دکمه اشتراک‌گذاری تلگرام با طراحی دلخواه چطور ساخته می‌شود؟

به https://t.me/share/url?url={url}&text={text} لینک بدهید و هر دو مقدار را URL-encode کنید، مثلاً با encodeURIComponent در جاوااسکریپت. متن اختیاری است و کاربر قبل از ارسال می‌تواند ویرایشش کند.

ساخت ربات تلگرام: آموزش قدم‌به‌قدم از BotFather تا اولین پیام با Python

ساخت ربات تلگرام قدم‌به‌قدم: ساخت ربات در BotFather، گرفتن توکن، تست با getMe، پیدا کردن chat id و ارسال اولین پیام با curl و Python.

ارسال پیام با ربات تلگرام از طریق API تلگرام (sendMessage)

آموزش ارسال پیام با ربات تلگرام از طریق API تلگرام: متد sendMessage با curl، Python و JavaScript، قالب‌بندی HTML و MarkdownV2، دکمه شیشه‌ای و رفع خطاها.

توکن ربات تلگرام: چیست، چطور بگیریم، بررسی و باطل کنیم

توکن ربات تلگرام چیست و از کجا بگیریم؟ گرفتن توکن از BotFather، پیدا کردن توکن ربات قبلی، تست با getMe، باطل کردن توکن لو رفته و نگهداری امن آن.

وب هوک ربات تلگرام: راه‌اندازی setWebhook، بررسی و رفع خطا

آموزش ست وب هوک تلگرام با setWebhook: پیش‌نیازهای HTTPS و پورت‌ها، secret_token، بررسی با getWebhookInfo، حذف وب هوک و رفع خطاهای رایج مثل 409.

چت آیدی تلگرام: چیست، کجاست و چطور chat id کاربر، گروه و کانال را پیدا کنیم

چت آیدی تلگرام کجاست؟ پیدا کردن chat_id کاربر، گروه، سوپرگروه، کانال و تاپیک با getUpdates، معنی آیدی‌های منفی و رفع مشکل نتیجه خالی و خطای 409.

سرور تست تلگرام: چطور ربات را در محیط تست تلگرام تست کنیم

سرور تست تلگرام برای ربات‌ها: ورود به محیط تست، ساخت ربات تست در BotFather، فراخوانی Bot API با مسیر /test/ و سوییچ TEST در تستر ما.

مرجع API جاوااسکریپت TelegramWidget: رویدادها، کدهای خطا و محدودیت‌ها

مرجع API جاوااسکریپت ویجت تلگرام: ویژگی‌ها، request()، رویدادها، کدهای خطا، متغیرهای CSS، widget_query و answerWidgetQuery و همه محدودیت‌ها.

مثال ویجت تلگرام: کد کامل HTML و ربات پایتون

مثال‌های کامل ویجت تلگرام با کد: کارت سفارش ثابت، شمارنده با widget_query، نظرسنجی زنده با ویجت اشتراکی و پیش‌نمایش در مرورگر با ربات پایتون.

ویجت تلگرام چیست؟ HTML تعاملی داخل پیام‌های ربات

ویجت تلگرام در Bot API 10.4 چیست؟ ارسال با sendWidget، وضعیت chat_data و public_data، محدودیت‌ها، جاهایی که فعلاً کار می‌کند و تفاوت با مینی اپ.