مستندات

داده‌ی عمومی

حساب‌های تأییدشده

کاربر چطور مالکیت وب‌سایت، گیت‌هاب یا حساب تلگرام را ثابت می‌کند، و چطور ربات تلگرام را خودتان اجرا کنید.

حساب تأییدشده حسابی است که کاربر ثابت کرده مال خودش است. با یک تیک آبی روی پروفایلش دیده می‌شود و در فیلد verified_accounts در JSON عمومی می‌آید. امروز چهار نوع داریم: وب‌سایت، گیت‌هاب، لینکدین و تلگرام. فیلد network هر مورد یکی از website، github، linkedin یا telegram است.

تأیید همچنین یک لینک را قابل‌اعتماد می‌کند: حساب‌های تأییدشده با rel="me" نمایش داده می‌شوند، یعنی روش استاندارد گفتن «این لینک همان شخص است».

وب‌سایت

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

روش چه چیزی منتشر شود
تگ meta <meta name="avatarak-verification" content="TOKEN"> داخل <head> صفحه‌ی اصلی
فایل https://DOMAIN/.well-known/avatarak-verification.txt که فقط TOKEN در آن باشد
DNS یک رکورد TXT روی DOMAIN با مقدار avatarak-verification=TOKEN

صفحه را از سرور خودمان می‌گیریم. اگر سایت به یک دامنه‌ی دیگر ریدایرکت کند، چیزی ثابت نمی‌شود (ریدایرکت از دامنه‌ی بدون www به www مشکلی ندارد). فقط به آدرس‌های عمومی روی پورت‌های ۸۰ و ۴۴۳ وصل می‌شویم.

گیت‌هاب

دو روش دارد و در هر دو حساب با شناسه‌ی عددی گیت‌هاب ذخیره می‌شود (نام کاربری قابل تغییر است و ممکن است کس دیگری بگیردش، شناسه نه):

روش چطور
Gist عمومی کاربر یک Gist عمومی با نام avatarak-verification.txt و محتوای avatarak-verification=TOKEN می‌سازد و بررسی کن را می‌زند. نیازی به هیچ تنظیمی روی سرور نیست.
ورود با گیت‌هاب با یک کلیک؛ وقتی روی سرور یک اپ OAuth تنظیم شده باشد. فقط نام کاربری و شناسه‌ی عمومی را می‌خوانیم.

Gistهای خصوصی و Gistهای حساب‌های دیگر نادیده گرفته می‌شوند. بعد از تأیید می‌شود Gist را پاک کرد.

لینکدین

فقط وقتی روی سرور یک اپ لینکدین تنظیم شده باشد (Sign In with LinkedIn using OpenID Connect). کاربر با لینکدین وارد می‌شود؛ شناسه‌ی پایدار لینکدین و نام حساب را نگه می‌داریم. لینکدین آدرس پروفایل عمومی نمی‌دهد، پس برای لینکدینِ تأییدشده در API و JSON مقدار url: null است: نام را نشان بدهید، نه لینک.

تلگرام

کاربر نام کاربری تلگرامش را می‌نویسد، تأیید با تلگرام را می‌زند، ربات ما را باز می‌کند و Start را می‌زند. تلگرام به ما می‌گوید چه کسی زده و ما تأیید می‌کنیم نام کاربری با چیزی که وارد شده یکی است. حساب را با شناسه‌ی عددی تلگرام ذخیره می‌کنیم، چون نام کاربری ممکن است آزاد شود و بعداً کس دیگری بگیردش.

قواعد

  • یک حساب خارجی فقط برای یک کاربر تأیید می‌شود. ادعای دوم رد می‌شود.
  • هر کد یک‌بارمصرف است، بعد از ۷۲ ساعت منقضی می‌شود و حداکثر ۴۰ بار بررسی می‌شود.
  • مالکیت یک‌بار و هنگام تأیید بررسی می‌شود. دامنه‌ای که بعداً منقضی شود تا وقتی کاربر حذفش نکند تأییدشده می‌ماند.
  • فقط شناسه‌ی حساب، روش و زمان را ذخیره می‌کنیم. هیچ توکنی از سرویس‌های دیگر نگه نمی‌داریم.

تنظیمات اختیاری گیت‌هاب (میزبانی شخصی)

روش Gist به هیچ تنظیمی نیاز ندارد. دو افزودنی اختیاری در .env:

GITHUB_API_TOKEN=          # سقف درخواست ناشناس گیت‌هاب را بالا می‌برد (۶۰ درخواست در ساعت برای هر IP سرور)
GITHUB_CLIENT_ID=          # با ساخت یک اپ OAuth، «ورود با گیت‌هاب» فعال می‌شود
GITHUB_CLIENT_SECRET=

آدرس callback اپ OAuth را روی https://avatarak.ir/account/verifications/github/callback بگذارید.

اجرای ربات تلگرام (میزبانی شخصی)

  1. با @BotFather یک ربات بسازید و توکن و نام کاربری‌اش را بردارید.

  2. در .env اضافه کنید (رمز را با openssl rand -hex 32 بسازید):

    TELEGRAM_BOT_TOKEN=123456:ABC...
    TELEGRAM_BOT_USERNAME=your_bot
    TELEGRAM_WEBHOOK_SECRET=<64 random hex characters>
    
  3. دریافت پیام‌ها را به یکی از دو روش راه بیندازید:

    php artisan telegram:webhook     # production: an HTTPS URL Telegram can reach
    php artisan telegram:poll        # local development: no public URL needed
    

وبهوک هر درخواستی را که دقیقاً رمز را در X-Telegram-Bot-Api-Secret-Token نداشته باشد رد می‌کند و تا وقتی تلگرام تنظیم نشده اصلاً وجود ندارد. توکن ربات را هرگز به کسی ندهید؛ اگر لو رفت به BotFather بنویسید /revoke.

تلگرام در بعضی کشورها فیلتر است. سرور باید به api.telegram.org برسد و تلگرام هم باید به آدرس وبهوک شما برسد. اگر telegram:poll خطای اتصال داد، --timeout=3 را امتحان کنید یا آن را از طریق VPN یا پروکسی اجرا کنید.