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-код, але працює з особистим акаунтом без офіційної підтримки.
| Можливість |
Cloud API |
Web Sidecar |
| QR-підключення |
Ні |
Так |
| Групи |
Ні |
Так |
| Довільні повідомлення |
24-год вікно |
Так |
| Бізнес-шаблони |
Так |
Ні |
| Офіційна підтримка |
Так |
Неофіційно |
Надсилання через обидва бекенди
Найпростіший виклик маршрутизує текстове повідомлення. Формат одержувача визначає, куди воно піде: телефонний номер у форматі 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.
