📡 وب‌هوک و به‌روزرسانی‌ها

کار با به‌روزرسانی‌های وب‌هوک و دریافت دستی به‌روزرسانی‌ها (Long-polling).

دریافت به‌روزرسانی‌ها

دو روش متضاد برای دریافت به‌روزرسانی‌ها برای ربات شما وجود دارد: متد getUpdates() از یک طرف و وب‌هوک‌ها از طرف دیگر. به‌روزرسانی‌های ورودی بر روی سرور بله ذخیره می‌شوند تا زمانی که ربات آن‌ها را به هر نحوی دریافت کند، اما بیشتر از ۲۴ ساعت نگهداری نخواهند شد.

صرف نظر از اینکه کدام گزینه را انتخاب کنید، به عنوان نتیجه شیء Update دریافت خواهید کرد.

از طریق وب‌هوک

برای دریافت به‌روزرسانی‌ها از طریق وب‌هوک، ابتدا باید URL وب‌هوک خود را به بله اعلام کنید. می‌توانید از متد setWebhook($url) برای مشخص کردن URL و دریافت به‌روزرسانی‌های ورودی از طریق یک وب‌هوک خروجی استفاده کنید.

هر زمان که به‌روزرسانی برای ربات وجود داشته باشد، بله یک درخواست HTTPS POST به URL مشخص شده ارسال می‌کند که شامل یک شیء Update است. در صورت درخواست ناموفق، بله پس از تعداد معقولی تلاش، درخواست را متوقف خواهد کرد.

اگر می‌خواهید اطمینان حاصل کنید که درخواست وب‌هوک از طرف بله است، پیشنهاد می‌کنیم از یک مسیر مخفی در URL استفاده کنید، مثلاً https://www.example.com/<token>/webhook. از آنجا که هیچ‌کس جز شما توکن رباتتان را نمی‌داند، می‌توانید مطمئن باشید که این درخواست از طرف بله است.

برای مشاهده لیست پارامترهای پشتیبانی‌شده و اطلاعات دیگر، به مستندات setWebhook مراجعه کنید.

تنظیم وب‌هوک

Standalone

$response = $bale->setWebhook(['url' => 'https://example.com/<token>/webhook']);

# Or if you are supplying a self-signed-certificate
$response = $bale->setWebhook([
    'url' => 'https://example.com/<token>/webhook',
    'certificate' => '/path/to/public_key_certificate.pub'
]);

Laravel

$response = Bale::setWebhook(['url' => 'https://example.com/<token>/webhook']);

# Or if you are supplying a self-signed-certificate
$response = Bale::setWebhook([
    'url' => 'https://example.com/<token>/webhook',
    'certificate' => '/path/to/public_key_certificate.pub'
]);

تنظیم مسیر در لاراول

یک مسیر POST به صورت /<token>/webhook تنظیم کنید.

IMPORTANT

مهم شما باید مسیر خود را به آرایه $except در فایل app/Http/Middleware/VerifyCsrfToken.php اضافه کنید تا فرآیند تأیید توکن CSRF که هر بار یک مسیر POST فراخوانی می‌شود را دور بزنید.

در اینجا یک مثال مبتنی بر سناریوی فوق آمده است:

app/Http/Middleware/VerifyCsrfToken.php

protected $except = [
    '/<token>/webhook'
];

نکات

1. تا زمانی که یک وبهوک خروجی تنظیم شده باشد، شما نمی‌توانید از getUpdates() برای دریافت بروزرسانی‌ها استفاده کنید.

2. برای استفاده از یک گواهی خودامضا، باید گواهی عمومی خود را با استفاده از پارامتر certificate بارگذاری کنید. لطفاً هنگام بارگذاری، مسیر کامل گواهی را وارد کنید.

3. پورت‌های پشتیبانی‌شده برای وبهوک‌ها: 443, 80, 88, 8443.

اگر در تنظیم وبهوک‌ها مشکل دارید، لطفاً این راهنما برای وبهوک‌ها را بررسی کنید.

دریافت بروزرسانی وبهوک

پس از تنظیم وبهوک، می‌توانید از تابع زیر برای دریافت بروزرسانی‌هایی که به URL وبهوک شما ارسال می‌شوند استفاده کنید. این تابع یک آرایه از اشیاء Update باز می‌گرداند.

Standalone

$updates = $bale->getWebhookUpdate();

Laravel

// Put this inside the POST route /<token>/webhook or POST Controller
$updates = Bale::getWebhookUpdate();

// Example of POST Route:
Route::post('/<token>/webhook', function () {
    $updates = Bale::getWebhookUpdate();

    return 'ok';
});

حذف وبهوک

برای حذف وبهوک (در صورتی که قبلاً تنظیم شده باشد).

Standalone

$response = $bale->removeWebhook();

Laravel

$response = Bale::removeWebhook();

از طریق Long Polling

شما می‌توانید از متد getUpdates() برای دریافت به‌روزرسانی‌های ورودی از طریق لانگ پولینگ استفاده کنید. یک آرایه از اشیاء Update بازگشت داده می‌شود.

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

Standalone

$response = $bale->getUpdates();

Laravel

$response = Bale::getUpdates();

Notes

این متد در صورتی که یک وبهوک خروجی تنظیم شده باشد، کار نخواهد کرد.

برای جلوگیری از دریافت به‌روزرسانی‌های تکراری، پس از هر پاسخ سرور، آفست را مجدداً محاسبه کنید.