‏واتس‌اپ تو لاراول: دو بک‌اند، یه Facade

پکیج Laravel WhatsApp نوشتهٔ Md Mostafijur Rahman برای فرستادن و گرفتن پیام واتس‌اپ از دل یه اپلیکیشن لاراولیه، و به گفتهٔ Laravel News فرقش اینه که با دو زبان مختلف با واتس‌اپ حرف می‌زنه: یکی Cloud API رسمی متا برای پیام‌رسانی تجاری، یکی هم یه sidecar نودی روی whatsapp-web.js که با کرومیوم headless دقیقاً همون پروتکل WebSocket واتس‌اپ وب رو برای یه اکانت شخصی صدا می‌زنه. هر دو زیر یه Facade واحد نشستن و از لاراول ۱۱، ۱۲ و ۱۳ روی PHP 8.2 به بالا پشتیبانی می‌کنن.

دلیل وجود هر دو مسیر اینه که هرکدوم تو یه چیز خوبن و پکیج هم صادقانه معامله‌ش رو می‌ذاره وسط. Cloud API مسیر رسمی و پشتیبانی‌شدست و قالب‌های تجاری (template) داره، ولی پاسخ آزاد رو به پنجرهٔ ۲۴ ساعته محدود می‌کنه و اصلاً گروه نداره. sidecar وب این محدودیت‌ها رو نداره: گروه می‌سازه، استوری می‌ذاره و با QR جفت می‌شه — به قیمت اینکه روی یه اکانت شخصی و بدون پشتیبانی رسمی می‌چرخه.

سادگی ماجرا اینجاست که فرمت گیرنده تصمیم می‌گیره پیام از کدوم مسیر بره: شمارهٔ E.164 می‌ره روی Cloud API و شناسهٔ @c.us می‌خوره به سشن وب. کد اپلیکیشن هیچ‌وقت لازم نیست بدونه کدوم بک‌اند داره کار رو انجام می‌ده.

WhatsApp::send('+14155550123', 'Your Laravel News digest is ready to read.');
WhatsApp::send('14155550123@c.us', 'Thanks for subscribing to the newsletter!');

برای پیام تجاری مستقیم سراغ sendTemplate() می‌ری و اسم قالب، زبان و پارامترها رو می‌دی. سمت وب هم چیزهایی داره که Cloud API از پسشون برنمی‌آد؛ سشن‌ها اسم دارن، پس می‌شه چند اکانت شخصی رو هم‌زمان بالا نگه داشت و هرکدوم رو با اسم صدا زد و مثلاً باهاش گروه ساخت یا عکس فرستاد. پیام‌های خروجی رو هم می‌شه با جاب SendMessage انداخت رو صف تا از چرخهٔ ریکوئست بیرون بمونه.

سمت ورودی، یه پروسهٔ همیشه‌روشن با دستور whatsapp:web:listen مراقب sidecar نوده و رویدادهای تایپ‌دار مثل MessageReceived رو به سیستم رویداد لاراول پل می‌زنه؛ یعنی دقیقاً مثل هر ایونت دیگه بهش گوش می‌دی. ترافیک ورودی Cloud API هم از راه webhook می‌آد و امضاش با HMAC و app secret متا تأیید می‌شه.

Event::listen(MessageReceived::class, function ($event) {
    Log::info('Reader replied', ['from' => $event->from(), 'body' => $event->body()]);
});

اگه Livewire و Flux رو هم نصب کنی، پکیج یه پنل ادمین روی مسیر /whatsapp بالا می‌آره: داشبورد، صفحهٔ ارسال پیام، نمای گفت‌وگو به شکل حباب‌های چت، و صفحه‌های گروه‌ها، مخاطبین و لاگ وبهوک — و با اضافه‌کردن Reverb، گفت‌وگوها بلادرنگ آپدیت می‌شن. ذخیره‌سازی اختیاریه و با سه مدل WaSession، WaMessage و WaContact انجام می‌شه که حتی می‌تونی روی یه کانکشن دیتابیس جدا بذاریشون تا دیتای واتس‌اپ قاطی اسکیمای اصلی نشه.

نکات کلیدی:

• دو بک‌اند (Cloud API رسمی و sidecar وب) پشت یه Facade واحد؛ کد اپلیکیشن از تفاوتشون بی‌خبر می‌مونه.
• فرمت گیرنده مسیر رو انتخاب می‌کنه: شمارهٔ E.164 یعنی Cloud API، شناسهٔ @c.us یعنی سشن وب.
• Cloud API قالب تجاری داره ولی پنجرهٔ آزادش ۲۴ ساعتست و گروه نداره؛ مسیر وب گروه و QR داره ولی غیررسمیه.
• پیام ورودی با یه پروسهٔ listener به ایونت‌های لاراول پل می‌خوره و وبهوک Cloud API با HMAC تأیید می‌شه.
• پنل ادمین اختیاری با Livewire و Flux، آپدیت بلادرنگ با Reverb، و سه مدل Eloquent برای ذخیرهٔ سشن، پیام و مخاطب.