Laravel WhatsApp: Два Бекенди За Одним Фасадом

Laravel WhatsApp - це пакет від Md Mostafijur Rahman для надсилання та отримання WhatsApp-повідомлень із Laravel-застосунків. Його особливість полягає у підтримці двох способів комунікації з WhatsApp: через офіційний Cloud API Meta для бізнес-повідомлень та через неофіційний Node-сервіс whatsapp-web.js, який використовує headless Chromium для роботи з тим самим WebSocket-протоколом, що й веб-версія WhatsApp для особистих акаунтів. Обидва бекенди працюють через єдиний фасад WhatsApp::, тому код застосунку не потребує знати, який саме обробляє конкретне повідомлення. Пакет підтримує Laravel 11, 12 і 13 на PHP 8.2 або новіших версіях.

Два бекенди для різних завдань

Два бекенди існують тому, що кожен добре справляється з різними задачами, і пакет чесно розповідає про компроміси. Cloud API - це офіційний шлях для шаблонних бізнес-повідомлень, але він обмежує довільні відповіді 24-годинним вікном і не підтримує групи. Веб-сервіс не має таких обмежень і може створювати групи, публікувати статуси та підключатися через 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!');

Для бізнес-повідомлень ви використовуєте підтримку шаблонів Cloud API безпосередньо, передаючи назву шаблону, локаль та компоненти параметрів:

WhatsApp::messages()->sendTemplate('+14155550123', 'issue_published', 'en_US', [
 ['type' => 'body', 'parameters' => [['type' => 'text', 'text' => 'Issue #312']]],
]);

Веб-бекенд відкриває операції, недоступні в Cloud API. Сесії мають назви, тому ви можете запускати кілька особистих акаунтів і звертатися до кожного за ім'ям:

WhatsApp::web('main')->groups()->create('Laracon Attendees', ['14155550123@c.us']);
WhatsApp::web('main')->messages()->sendImage('14155550123@c.us',
 ['url' => 'https://example.com/laracon-schedule.png', 'caption' => 'See you at the keynote!']);

Чергове надсилання та вхідні події

Вихідні повідомлення можна відправляти як Jobs через job SendMessage пакета, що переносить надсилання повідомлень із циклу запиту на ваші queue-воркери:

SendMessage::dispatch('+14155550123', 'New on Laravel News: this week in the ecosystem.');

Вхідні повідомлення від веб-сервісу інтегруються в систему подій Laravel. Процес whatsapp:web:listen, що працює тривалий час, спостерігає за Node-сервісом і генерує типізовані події, такі як MessageReceived, на які ви можете підписатися як на будь-яку іншу подію:

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

Cloud API обробляє вхідний трафік через вебхуки з верифікацією HMAC-підпису за допомогою секрету вашого Meta-застосунку.

Адмін-інтерфейс та рівень персистентності

Якщо ви встановите опціональні залежності Livewire та Flux, пакет монтує адмін-інтерфейс за адресою /whatsapp. Він включає дашборд, екран для обміну повідомленнями, представлення розмов у вигляді чат-бульбашок та сторінки для груп, контактів і журналів вебхуків. Якщо додати Laravel Reverb, представлення розмов оновлюються в реальному часі.

Персистентність включається через три Eloquent-моделі: WaSession, WaMessage та WaContact. Вони можуть працювати на окремому з'єднанні з базою даних, якщо ви хочете тримати WhatsApp-дані осторонь від основної схеми. Пакет також обробляє фонове мостування подій, моніторинг стану сесій та кешування аватарів і медіа.

Початок роботи

Встановіть пакет та опублікуйте його конфігурацію та міграції:

composer require kstmostofa/laravel-whatsapp
php artisan vendor:publish --tag=laravel-whatsapp-config
php artisan vendor:publish --tag=laravel-whatsapp-migrations
php artisan migrate

Для роботи з Cloud API потрібні ваші Meta-credentials в оточенні:

WHATSAPP_ACCESS_TOKEN=EAAG...
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_BUSINESS_ACCOUNT_ID=987654321098765
WHATSAPP_APP_SECRET=your-meta-app-secret
WHATSAPP_VERIFY_TOKEN=any-string-you-make-up

Веб-сервіс встановлюється та запускається через artisan-команди, після чого процес-слухач інтегрує його події назад в Laravel:

php artisan whatsapp:sidecar:install
php artisan whatsapp:sidecar:start
php artisan whatsapp:web:listen main &

Ви можете ознайомитися з вихідним кодом, повним довідником конфігурації та списком доступних команд на GitHub.