إرسال واستقبال WhatsApp من PHP وLaravel

كيف تستقبل رسائل WhatsApp في Laravel؟

بتعريف مسارين على المسار نفسه في routes/api.php: واحد لـ GET وآخر لـ POST. شغّل php artisan install:api أولاً إذا لم يكن الملف موجوداً. مسارات API عديمة الحالة وخارج مجموعة web، فلا يُرفض طلب POST القادم من Meta. أما إذا وُضع المسار في routes/web.php فيُرفض الطلب لغياب رمز CSRF المطلوب.

مسار GET يجيب عن تحقق Meta. ترسل Meta الحقول hub.mode وhub.verify_token وhub.challenge، لكن PHP يستبدل النقاط في أسماء المتغيرات الواردة بشرطات سفلية، فيرى Laravel الأسماء hub_mode وhub_verify_token وhub_challenge. الشيفرة التي تقرأ الأسماء ذات النقاط تحصل على null ولا ينجح التحقق أبداً. أعد قيمة challenge كنص عادي، وليس عبر response()->json().

أما مسار POST فيمرّر الحمولة إلى مهمة في الطابور ويعيد 200 فوراً. ضع مفتاحاً عشوائياً طويلاً في المسار وتحقق منه في المسارين: توقّع Meta عمليات التسليم بالسر الخاص بتطبيق Tech Provider، لذا لا يمكنك التحقق من ترويسة التوقيع من جهتك.

use App\Jobs\HandleWhatsAppEvent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

Route::get('/whatsapp/{key}', function (Request $request, string $key) {
    abort_unless(hash_equals(config('services.whatsapp.url_key'), $key), 404);

    // PHP turns hub.mode into hub_mode: read the underscored names
    if ($request->query('hub_mode') === 'subscribe'
        && hash_equals(config('services.whatsapp.verify_token'),
                       (string) $request->query('hub_verify_token'))) {
        return response((string) $request->query('hub_challenge'), 200)
            ->header('Content-Type', 'text/plain');
    }

    abort(403);
});

Route::post('/whatsapp/{key}', function (Request $request, string $key) {
    abort_unless(hash_equals(config('services.whatsapp.url_key'), $key), 404);

    HandleWhatsAppEvent::dispatch($request->json()->all());

    return response('', 200);
});

كيف ترسل رسالة WhatsApp من Laravel؟

بعميل HTTP في Laravel: طلب POST واحد إلى نقطة النهاية الخاصة بالرسائل لمعرّف الرقم، مع رمز الوصول كرمز Bearer. القيمتان تأتيان من الاتصال، وتظهران في لوحة التحكم وتعيدهما الأداة get_api_credentials، ومكانهما config/services.php مدعوماً بمتغيرات البيئة وليس الشيفرة نفسها.

يعتمد شكل الجسم على التوقيت. خلال 24 ساعة من آخر رسالة للعميل، يعمل كائن text كما في المثال أدناه. وخارج هذه النافذة تقبل Meta كائن template فقط، يحدد قالباً معتمداً ولغته، ويفشل النص الحر بالخطأ 131047. والاستجابة هي المكان الذي ترى فيه ذلك: الطلب الفاشل يعيد كائن error يبيّن رمزه سبب المشكلة، فسجّله بدلاً من تجاهله.

لا شيء في الطلب خاص بـ EasyCoexistence. إنه الطلب نفسه الموجود في وثائق Meta، لذا يعمل أي عميل HTTP في PHP بالطريقة نفسها، سواء Guzzle أو cURL المباشر.

use Illuminate\Support\Facades\Http;

$response = Http::withToken(config('services.whatsapp.token'))
    ->post('https://graph.facebook.com/v25.0/'
        . config('services.whatsapp.phone_number_id') . '/messages', [
        'messaging_product' => 'whatsapp',
        'to' => '14155550188', // digits only, with country code
        'type' => 'text',
        'text' => ['body' => 'Thanks, we are on it.'],
    ]);

if ($response->failed()) {
    // error.code 131047: outside the window, send a template instead
    logger()->warning('WhatsApp send failed', $response->json('error', []));
}

ماذا يحتاج معالج Laravel في بيئة الإنتاج أكثر من ذلك؟

يحتاج إلى طابور حقيقي، وإزالة للتكرار، وفحص للنافذة الزمنية.

الطابور مهم لأن Meta تعيد المحاولة عندما تتأخر الاستجابة. لا يعود HandleWhatsAppEvent::dispatch() بسرعة إلا إذا كان اتصال الطابور حقيقياً ويعمل معه worker. أما مع المشغّل sync فتُنفَّذ المهمة داخل الطلب نفسه، فيتحول أي استدعاء بطيء لنموذج أو كتابة في قاعدة البيانات إلى تسليم مكرر.

أزل التكرار بالاعتماد على معرّف الرسالة، أي wamid في كل رسالة، لأن إعادة المحاولة أمر طبيعي وليست استثناءً. يكفي فهرس فريد على هذا العمود، أو قفل في الذاكرة المؤقتة مبني عليه.

واحفظ وقت آخر رسالة كتبها كل جهة اتصال. بهذا الطابع الزمني يختار مسار الإرسال بنفسه بين النص والقالب، بدلاً من أن يكتشف ذلك من الخطأ 131047 بعد أن ينتظر العميل. والردود المكتوبة على الهاتف في تطبيق WhatsApp Business تصل كأحداث echo على المسار نفسه، فيستطيع المعالج أيضاً معرفة متى تولّى شخص المحادثة.

الأخطاء الشائعة

• قراءة hub.challenge بالنقطة. غيّر PHP اسمه إلى hub_challenge، فيعيد المعالج جسماً فارغاً ولا تتحقق Meta أبداً.
• وضع خطاف الويب (webhook) في routes/web.php. طلب POST من Meta لا يحمل رمز CSRF فيُرفض بالخطأ 419.
• الإرسال إلى طابور sync. تُنفَّذ المهمة قبل إعادة 200، وتُعاد محاولة المعالجة البطيئة، فتُعالَج الرسائل مرتين.
• إعادة قيمة challenge عبر response()->json(). علامات الاقتباس حول القيمة تُفشل فحص Meta.

الأسئلة الشائعة

تابع القراءة