ویجت تلگرام برای سایت: ورود با تلگرام، جاسازی پست، کامنتها و دکمه اشتراکگذاری
تلگرام چهار ویجت برای وبسایتها دارد: 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 و اندروید استفاده کنید.
- یک ربات برای سایت آماده کنید (آموزش ساخت ربات تلگرام). کاربر نام و عکس پروفایل همین ربات را در پنجره تأیید میبیند، پس آنها را با نام و لوگوی سایت هماهنگ کنید.
- Allowed URLs را ثبت کنید. مینی اپ @BotFather را باز کنید، ربات را انتخاب کنید و بعد Login Widget را بزنید. originهایی که دکمه را در آنها میگذارید (مثلاً
https://example.com) و redirect URIهای OIDC (مثلاًhttps://example.com/auth/callback) را اضافه کنید. تلگرام ورود و ریدایرکت را فقط برای همین آدرسهای از پیش ثبتشده انجام میدهد. - Client ID و Client Secret را ذخیره کنید؛ هر دو در همین بخش نمایش داده میشوند. 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">ورود با تلگرام</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 را دارند. مستندات آن آرشیو شده، پس در پروژه جدید از روش بالا استفاده کنید؛ اما اگر نگهداری یک پروژه قدیمی با شماست، این ویجت اینطور کار میکند:
- دستور
/setdomainرا به @BotFather بفرستید تا دامنه سایت به ربات وصل شود. - اسکریپت را در صفحه بگذارید. نمونه با 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;
رفع مشکلات رایج
- ویجت قدیمی پیام «Bot domain invalid» میدهد. دامنه به ربات وصل نشده است. برای همان ربات،
/setdomainرا با دامنه دقیق صفحه به @BotFather بفرستید. - ورود جدید کاری نمیکند یا رد میشود. origin صفحه یا redirect URI در Allowed URLs داخل @BotFather نیست، یا هدر
Cross-Origin-Opener-Policy: same-originجلوی popup را میگیرد. - ویجت نمایش داده نمیشود.
telegram-widget.jsازtelegram.orgبارگذاری میشود و یک iframe اضافه میکند: برای پست، گفتوگو و دکمه اشتراکگذاری ازt.meو برای لاگین قدیمی ازoauth.telegram.org. Content-Security-Policy سختگیرانه (script-src،frame-src) یا افزونه تبلیغگیر میتواند جلوی آنها را بگیرد. - hash نمیخواند. توکن اشتباه، استفاده از خود توکن به جای SHA256 آن به عنوان کلید، فیلدهای اضافه در data-check-string (query parameterهای خودتان)، تغییر مقدار فیلدها یا جداکننده اشتباه. از
\nاستفاده کنید، نه&. - پست جاسازی نمیشود. فقط پیامهای کانالها و گروههای عمومی قابل جاسازیاند؛ چتهای خصوصی لینک عمومی t.me ندارند.
- گفتوگو در صفحه مقاله خالی است. بررسی کنید صفحه تگ لینک canonical را دارد و لینکی که در کانال منتشر کردهاید دقیقاً به همان آدرس canonical اشاره میکند.
قدمهای بعدی
- ساخت ربات تلگرام تا در پنجره ورود، نماینده سایت شما باشد.
- پیدا کردن، بررسی و باطل کردن توکن ربات؛ برای بررسی hash در ویجت قدیمی لازم است.
- ویجت تلگرام در پیامهای ربات: ویجتهای HTML در Bot API 10.4، قابلیتی کاملاً جدا.
- مستندات رسمی: core.telegram.org/widgets.
پرسشهای متداول
چطور دکمه ورود با تلگرام را به سایتم اضافه کنم؟
یک ربات انتخاب کنید، مینی اپ @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، محدودیتها، جاهایی که فعلاً کار میکند و تفاوت با مینی اپ.