Laravel WhatsApp: два бекенди за єдиним Facade

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

Наявність двох бекендів зумовлена їхніми різними перевагами, і пакет чесно окреслює компроміси. Cloud API — це офіційний шлях для роботи з шаблонними бізнес-повідомленнями, проте він обмежує вільні відповіді 24-годинним вікном і не підтримує групи. Web sidecar не має таких обмежень: він дозволяє створювати групи, публікувати статуси та підключатися через QR-код, проте працює через особистий акаунт без офіційної підтримки.

# Надсилання через будь-який бекенд

Найпростіший виклик відправляє звичайний текст. Куди піде повідомлення, залежить від формату отримувача: номер телефону в E.164 обробляється через Cloud API, тоді як ідентифікатор @c.us спрямовує його у вебсесію.

WhatsApp::send('+14155550123', 'Ваш дайджест Laravel News готовий до читання.');
WhatsApp::send('14155550123@c.us', 'Дякуємо за підписку!');

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

WhatsApp::messages()->sendTemplate('+14155550123', 'issue_published', 'en_US', [
    ['type' => 'body', 'parameters' => [['type' => 'text', 'text' => 'Випуск #312']]],
]);

Веббекенд відкриває можливості, недоступні для Cloud API. Оскільки сесії мають назви, можна керувати кількома особистими акаунтами одночасно:

WhatsApp::web('main')->groups()->create('Учасники Laracon', ['14155550123@c.us']);
WhatsApp::web('main')->messages()->sendImage('14155550123@c.us',
    ['url' => 'https://example.com/laracon-schedule.png', 'caption' => 'До зустрічі на кейноті!']);

# Черги та вхідні події

Вихідні повідомлення можна надсилати як завдання через вбудований Job SendMessage. Це дозволяє винести процес відправки за межі життєвого циклу запиту на ваші queue workers:

SendMessage::dispatch('+14155550123', 'Нове на Laravel News: огляд екосистеми за тиждень.');

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

use \Kstmostofa\LaravelWhatsApp\Events\Web\MessageReceived;
 
Event::listen(MessageReceived::class,
    function ($event) {
        Log::info('Читач відповів', ['from' => $event->from(), 'body' => $event->body()]);
    }
);

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

# Адмін-панель та збереження даних

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

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

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

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

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 у файл оточення:

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

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

Вихідний код, повний гайд із налаштування та список команд доступні на GitHub.