مستندات جامع SDK لاراول Telegram Core

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

برای آشنایی با امکانات سرویس، از صفحهٔ معرفی Telegram Core شروع کنید؛ سپس راهنمای نصب و استفاده از SDK و اطلاعات نسخهٔ SDK را بررسی کنید.

مراجع مستقل و رسمی برای پیاده‌سازی عبارت‌اند از مستندات Telegram Bot API برای متدهای تلگرام و مستندات Laravel برای چارچوب برنامه.

پیش‌نیازها و مدل اتصال

PHP 8.1 یا جدیدتر و Laravel 10، 11 یا 12 لازم است. مدیر Core باید برای برنامه شما Bot UUID و Consumer Secret صادر کند و آدرس HTTPS دریافت Update را روی Bot تنظیم کند.

نصب SDK

نصب عمومی با Composer

composer require amirkateb/telegram-core-client
php artisan tgcore:install

پس از انتشار روی Packagist، دستور بالا روش استاندارد نصب است. تا قبل از انتشار Packagist می‌توان repository عمومی GitHub را به Composer به‌عنوان VCS معرفی کرد.

بررسی نصب

php artisan tgcore:doctor
php artisan tgcore:status

پیکربندی Environment

TGCORE_URL=https://telegram.avaztek.ir
TGCORE_BOT_UUID=00000000-0000-0000-0000-000000000000
TGCORE_CONSUMER_SECRET=your-issued-secret
TGCORE_CONSUMER_PATH=/tgcore/webhook
TGCORE_TIMEOUT=30
TGCORE_CONNECT_TIMEOUT=7
TGCORE_SIGNATURE_TOLERANCE=300

TGCORE_URL باید از environment خوانده شود و هیچ دامنه‌ای در سورس کلاینت hard-code نشود. Consumer Secret فقط server-side است و نباید وارد JavaScript، اپ موبایل، repository یا log شود.

معماری، HMAC و اعتماد

در درخواست‌های JSON، SDK هدرهای X-TGCore-Bot-UUID، X-TGCore-Timestamp، X-TGCore-Signature و در صورت نیاز X-TGCore-Idempotency-Key را می‌سازد. امضا HMAC-SHA256 روی timestamp، idempotency key اختیاری و raw body است.

signature = HMAC_SHA256(
  timestamp + "\n" +
  [idempotencyKey + "\n"] +
  exactRawBody,
  consumerSecret
)

در Updateهای ورودی نیز SDK timestamp، امضا، Bot UUID و هویت پایدار Update را قبل از dispatch کردن Laravel Event بررسی می‌کند.

ارسال درخواست به Telegram

ارسال پیام متنی

use KatebSaber\TelegramCore\Facades\TelegramCore;
use Illuminate\Support\Str;

TelegramCore::sendMessage(
    123456789,
    'سلام از کلاینت',
    [],
    idempotencyKey: (string) Str::uuid(),
);

Location و Photo

TelegramCore::sendLocation(123456789, 35.6892, 51.3890);

TelegramCore::sendPhoto(123456789, config('app.url').'/media/photo.jpg', [
    'caption' => 'تصویر نمونه',
]);

دسترسی به تمام قابلیت‌های مجاز Bot API

SDK عمداً یک متد عمومی call() دارد. بنابراین برای قابلیت‌های جدید Telegram لازم نیست منتظر اضافه‌شدن wrapper جدید بمانید؛ registry خود Core مرجع نهایی مجاز بودن متد است. سرور فعلی 177 متد consumer-allowed از Bot API 10.3 ارائه می‌کند.

$result = TelegramCore::call('sendPoll', [
    'chat_id' => 123456789,
    'question' => 'انتخاب شما؟',
    'options' => [
        ['text' => 'گزینه اول'],
        ['text' => 'گزینه دوم'],
    ],
], idempotencyKey: (string) Str::uuid());

متدهای control-plane مانند مدیریت webhook، polling session و دریافت/تعویض managed bot token برای consumer مسدود هستند.

Capabilities

$capabilities = TelegramCore::capabilities();

برای تشخیص نسخه قرارداد، Bot API، allowlist و محدودیت‌های فایل همیشه از capabilities سرور استفاده کنید.

Idempotency و عملیات Mutating

برای عملیاتی که ممکن است به‌علت timeout دوباره ارسال شوند، کلید idempotency پایدار بفرستید. Core درخواست یکسان را replay می‌کند، درخواست متفاوت با همان کلید را conflict می‌داند و در نتیجه مبهم عملیات mutating از تکرار کور جلوگیری می‌کند.

دریافت Update و Event

Package مسیر TGCORE_CONSUMER_PATH را ثبت می‌کند. پس از اعتبارسنجی، event زیر dispatch می‌شود:

use KatebSaber\TelegramCore\Events\TelegramUpdateReceived;

Event::listen(TelegramUpdateReceived::class, function ($event) {
    $event->botUuid();
    $event->updateDbId();
    $event->updateId();
    $event->type();
    $payload = $event->payload;
});

فایل، Media و Staged Upload

دانلود امن

$bytes = app(\KatebSaber\TelegramCore\Http\TelegramCoreClient::class)
    ->downloadFile($fileId);

Core فایل را با Bot Token داخلی resolve می‌کند؛ URL توکن‌دار Telegram به کلاینت نمی‌رسد.

Staged Upload

$upload = TelegramCore::stageUpload(
    storage_path('app/private/video.mp4')
);

برای محدودیت‌های اندازه، تعداد فایل و ظرفیت staging از capabilities() استفاده کنید. Multipart signing شامل hash بایت فایل، اندازه و نام فایل است.

خطاها، Rate Limit و Retry

پاسخ‌های 4xx/5xx با UpstreamException ارائه می‌شوند و status و envelope پاک‌سازی‌شده Core در دسترس است. اطلاعات Telegram مانند description، error code و retry_after در صورت وجود حفظ می‌شود.

try {
    TelegramCore::call('sendMessage', $payload, $key);
} catch (\KatebSaber\TelegramCore\Exceptions\UpstreamException $e) {
    $status = $e->status;
    $response = $e->response;
}

روی عملیات mutating بعد از timeout یا خطای شبکه retry کور انجام ندهید؛ همان idempotency key را حفظ کنید.

Health Check عمومی و ماشین‌خوان Core

برای مانیتورینگ اتصال و وضعیت عملیاتی Telegram Core، همان Health Check عمومی که در بخش «سلامت سیستم» پنل مدیریت نمایش داده می‌شود در دسترس کلاینت‌ها و سامانه‌های مانیتورینگ است. آدرس endpoint از APP_URL محیط فعلی ساخته می‌شود و در هیچ بخشی از SDK یا مستندات دامنه production به‌صورت hard-code قرار نمی‌گیرد.

درخواست

GET https://telegram.avaztek.ir/health
Accept: application/json

نمونه پاسخ

{
  "name": "avaztek telegram",
  "contract": "tgcore-health/v1",
  "ok": true,
  "healthy": true,
  "status": "healthy",
  "score": 100,
  "checked_at": "ISO-8601 timestamp",
  "time": "ISO-8601 timestamp",
  "checks": {
    "application": "ok",
    "database": "ok",
    "redis": "ok",
    "storage": "ok",
    "queue": "ok",
    "scheduler": "ok",
    "nginx": "ok",
    "php_fpm": "ok",
    "ssl": "ok"
  }
}

معنی status و HTTP

مقادیر هر عضو checks یکی از ok، warning، down یا unknown است. پاسخ موفق هدر X-TGCore-Health-Contract: 1 دارد و با Cache-Control: no-store, max-age=0 برگردانده می‌شود. Snapshot داخلی حداکثر ۱۵ ثانیه cache می‌شود تا probeهای سلامت فشار غیرضروری به سرویس‌ها وارد نکنند.

استفاده در Client و Monitoring

$response = Http::acceptJson()->get(
    rtrim(config('tgcore.url'), '/') . '/health'
);

if ($response->status() === 503) {
    // Core is unhealthy; alert/fail over according to your policy.
}

$status = $response->json('status');
$checks = $response->json('checks', []);

این endpoint عمداً بدون authentication ارائه می‌شود، اما فقط خلاصه کم‌جزئیات سلامت را برمی‌گرداند و نباید hostname، IP، URL داخلی، exception، token، secret یا جزئیات حساس زیرساخت را افشا کند. برای diagnostic عمیق از صفحه احراز هویت‌شده «سلامت سیستم» در پنل مدیریت استفاده کنید.

دستورات Artisan

چک‌لیست Production

1. Secretها فقط در environment/secret manager باشند.
2. Consumer URL حتماً HTTPS عمومی و پایدار باشد.
3. بعد از تغییر env، cacheهای Laravel rebuild شوند.
4. Queue و listenerهای business برای at-least-once آماده باشند.
5. Timeoutها محدود و logging بدون secret باشد.
6. قبل از deploy، tgcore:doctor و tgcore:status اجرا شوند.

نسخه، Compatibility و Upgrade

نسخه major SDK با breaking change قرارداد کلاینت تغییر می‌کند، نه با هر نسخه Bot API. قابلیت‌های جدید Telegram از generic call() قابل استفاده‌اند. قبل و بعد از upgrade خروجی capabilities را بررسی کنید.

رفع اشکال سریع

401 / Signature invalid

Consumer Secret، ساعت سیستم، raw body و Bot UUID را بررسی کنید. Secret سمت Core و client باید دقیقاً یکسان باشد.

409 Idempotency conflict

یک idempotency key برای payload متفاوت استفاده شده است. برای عملیات جدید کلید جدید بسازید.

Method owned by Core

متد در control-plane قرار دارد و عمداً از consumer قابل فراخوانی نیست.

Update تکراری

این رفتار در مدل at-least-once ممکن است. side-effect را با update_db_id یا هویت تجاری مناسب dedupe کنید.