PHPackages                             katema/laravel-whatsapp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. katema/laravel-whatsapp

ActiveLibrary[API Development](/categories/api)

katema/laravel-whatsapp
=======================

Laravel package for Meta WhatsApp chatbots, flows, and AI automation

0.4.7(6mo ago)017MITPHPPHP ^8.1

Since Dec 18Pushed 6mo agoCompare

[ Source](https://github.com/Aeronk/laravel-whatsapp)[ Packagist](https://packagist.org/packages/katema/laravel-whatsapp)[ RSS](/packages/katema-laravel-whatsapp/feed)WikiDiscussions main Synced today

READMEChangelog (1)Dependencies (1)Versions (18)Used By (0)

Laravel WhatsApp Automation Package
===================================

[](#laravel-whatsapp-automation-package)

A comprehensive Laravel package for building WhatsApp chatbots, flows, and AI-powered automation using Meta's WhatsApp Cloud API.

Features
--------

[](#features)

✅ **Meta WhatsApp Cloud API Integration** - Full API support
✅ **Webhook Handling** - Automatic message and status processing
✅ **WhatsApp Flows v7.3+** - Build interactive forms and experiences
✅ **Chatbot Engine** - Rule-based logic with AI fallback
✅ **AI Integration** - OpenAI & Google Gemini support
✅ **Database Models** - Messages, users, sessions, and flows
✅ **Event-Driven** - Laravel events for extensibility
✅ **Clean API** - Intuitive, Laravel-native interface

Installation
------------

[](#installation)

```
# Easy installation command
php artisan whatsapp:install

# Or manually publish
php artisan vendor:publish --tag=whatsapp-config
php artisan vendor:publish --tag=whatsapp-migrations
php artisan migrate
```

Configuration
-------------

[](#configuration)

Add to your `.env`:

```
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_BUSINESS_ACCOUNT_ID=your_business_account_id
WHATSAPP_VERIFY_TOKEN=your_verify_token

# Optional: AI Integration
WHATSAPP_AI_PROVIDER=openai
OPENAI_API_KEY=your_openai_key
# OR
WHATSAPP_AI_PROVIDER=gemini
GEMINI_API_KEY=your_gemini_key
```

Quick Start
-----------

[](#quick-start)

#### Fluent Builder (Recommended)

[](#fluent-builder-recommended)

```
use Katema\WhatsApp\Facades\WhatsApp;

WhatsApp::to('1234567890')->text('Hello from Laravel!')->send();
```

#### Basic Methods

[](#basic-methods)

```
// Send text message
WhatsApp::sendMessage('1234567890', 'Hello from Laravel!');

// Send local image (Auto-uploads to Meta)
WhatsApp::sendImage('1234567890', storage_path('app/public/image.jpg'), 'Local Image');

// Send remote image
WhatsApp::sendImage('1234567890', 'https://example.com/remote.jpg', 'Remote Image');
```

### 2. Send Interactive Messages

[](#2-send-interactive-messages)

```
// Buttons
WhatsApp::sendInteractive('1234567890', [
    'type' => 'button',
    'body' => ['text' => 'Choose an option:'],
    'action' => [
        'buttons' => [
            ['type' => 'reply', 'reply' => ['id' => 'btn_1', 'title' => 'Option 1']],
            ['type' => 'reply', 'reply' => ['id' => 'btn_2', 'title' => 'Option 2']],
        ],
    ],
]);

// List
WhatsApp::sendInteractive('1234567890', [
    'type' => 'list',
    'body' => ['text' => 'Select from menu:'],
    'action' => [
        'button' => 'View Menu',
        'sections' => [
            [
                'title' => 'Main Menu',
                'rows' => [
                    ['id' => 'item_1', 'title' => 'Item 1', 'description' => 'Description'],
                    ['id' => 'item_2', 'title' => 'Item 2', 'description' => 'Description'],
                ],
            ],
        ],
    ],
]);
```

### 3. Build a Chatbot

[](#3-build-a-chatbot)

Create an event listener:

```
namespace App\Listeners;

use Katema\WhatsApp\Events\MessageReceived;
use Katema\WhatsApp\Services\Chatbot\ChatbotEngine;

class HandleWhatsAppMessage
{
    public function __construct(protected ChatbotEngine $chatbot)
    {
    }

    public function handle(MessageReceived $event): void
    {
        $this->chatbot
            ->addRule(
                // Condition
                fn($msg) => strtolower($msg->content['body'] ?? '') === 'hi',
                // Action
                fn($msg, $user, $session, $whatsapp) =>
                    $whatsapp->sendMessage($user->phone_number, 'Hello! How can I help?'),
                priority: 10
            )
            ->addRule(
                fn($msg) => str_contains(strtolower($msg->content['body'] ?? ''), 'price'),
                fn($msg, $user, $session, $whatsapp) =>
                    $whatsapp->sendMessage($user->phone_number, 'Our prices start at $10'),
                priority: 20
            )
            ->process($event->message, $event->user);
    }
}
```

Register in `EventServiceProvider`:

```
use Katema\WhatsApp\Events\MessageReceived;
use App\Listeners\HandleWhatsAppMessage;

protected $listen = [
    MessageReceived::class => [
        HandleWhatsAppMessage::class,
    ],
];
```

### 4. Create WhatsApp Flows

[](#4-create-whatsapp-flows)

```
use Katema\WhatsApp\Services\FlowService;

$flow = app(FlowService::class);

// Build a registration form
$screens = [
    $flow->buildScreen('WELCOME', 'Registration', [
        $flow->buildForm([
            $flow->buildTextInput('name', 'Full Name', required: true),
            $flow->buildTextInput('email', 'Email', required: true, inputType: 'email'),
            $flow->buildTextInput('phone', 'Phone Number', required: true, inputType: 'phone'),
            $flow->buildDropdown('country', 'Country', [
                ['id' => 'ke', 'title' => 'Kenya'],
                ['id' => 'ug', 'title' => 'Uganda'],
                ['id' => 'tz', 'title' => 'Tanzania'],
            ], required: true),
            $flow->buildFooter('Submit', 'complete'),
        ]),
    ]),
];

$whatsappFlow = $flow->createFlow('Registration Form', $screens);

// Send flow to user
WhatsApp::sendFlow('1234567890', $whatsappFlow->flow_id);
```

### 5. AI-Powered Responses

[](#5-ai-powered-responses)

With AI enabled, the chatbot automatically handles unmatched messages. You can now define **Personas** (System Prompts):

```
// Define a specific persona for the chatbot
$chatbot->setPersona('You are a helpful travel agent specialized in African safaris. Respond in a professional and enthusiastic tone.');

// Or use tools (OpenAI Function Calling)
$chatbot->withTools([
    [
        'type' => 'function',
        'function' => [
            'name' => 'get_package_price',
            'description' => 'Get the price of a travel package',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'package' => ['type' => 'string']
                ]
            ]
        ]
    ]
]);
```

Advanced Usage
--------------

[](#advanced-usage)

### Session Management

[](#session-management)

```
use Katema\WhatsApp\Models\WhatsAppSession;

$session = WhatsAppSession::active()
    ->where('whatsapp_user_id', $userId)
    ->first();

// Store context
$session->setContext('step', 'awaiting_payment');
$session->setContext('amount', 100);

// Retrieve context
$step = $session->getContext('step');

// Extend session
$session->extend(30); // 30 minutes
```

### Working with Models

[](#working-with-models)

```
use Katema\WhatsApp\Models\WhatsAppUser;
use Katema\WhatsApp\Models\WhatsAppMessage;

// Find user
$user = WhatsAppUser::where('phone_number', '1234567890')->first();

// Get messages
$messages = $user->messages()
    ->incoming()
    ->latest()
    ->take(10)
    ->get();

// Block/unblock user
$user->block();
$user->unblock();
```

### Custom Flow Components

[](#custom-flow-components)

```
$flow->buildCheckboxGroup('interests', 'Select Interests', [
    ['id' => 'tech', 'title' => 'Technology'],
    ['id' => 'sports', 'title' => 'Sports'],
    ['id' => 'music', 'title' => 'Music'],
], required: true);

$flow->buildDatePicker('dob', 'Date of Birth', required: true);

$flow->buildRadioButtonsGroup('gender', 'Gender', [
    ['id' => 'male', 'title' => 'Male'],
    ['id' => 'female', 'title' => 'Female'],
]);
```

### Event Handling

[](#event-handling)

Available events:

```
use Katema\WhatsApp\Events\MessageReceived;
use Katema\WhatsApp\Events\MessageStatusUpdated;
use Katema\WhatsApp\Events\FlowResponseReceived;

### WhatsApp Flow Security

For Flow "Endpoints", common logic requires decryption of the incoming payload.

```php
use Katema\WhatsApp\Facades\Flow;

$decrypted = Flow::handleEndpointRequest($request->all());

// Perform logic...

$response = Flow::encryptResponse([
    'screen' => 'SUCCESS',
    'data' => ['message' => 'Processed!']
], $decrypted['aes_key'], $decrypted['iv']);

return response()->json([
    'encrypted_flow_data' => $response,
    'encrypted_aes_key' => $decrypted['aes_key'], // Usually returned as received
    'initial_vector' => $decrypted['iv']
]);
```

Webhook Setup
-------------

[](#webhook-setup)

Your webhook URL will be: `https://yourdomain.com/whatsapp/webhook`

Configure in Meta App Dashboard:

1. Go to WhatsApp > Configuration
2. Set Callback URL: `https://yourdomain.com/whatsapp/webhook`
3. Set Verify Token: (from your `.env` WHATSAPP\_VERIFY\_TOKEN)
4. Subscribe to: `messages`, `message_status`

Testing
-------

[](#testing)

Use `WhatsApp::fake()` to prevent actual API calls and assert that messages were sent.

```
public function test_it_sends_a_greeting()
{
    $fake = WhatsApp::fake();

    // Trigger your logic...
    WhatsApp::to('1234567890')->text('Hi!')->send();

    // Assertions
    $fake->assertSentTo('1234567890', function ($msg) {
        return $msg['message'] === 'Hi!';
    });
}
```

Security
--------

[](#security)

Never commit your `.env` file. Keep API keys secure.

License
-------

[](#license)

MIT License

Support
-------

[](#support)

For issues and questions, please use GitHub Issues.

###  Health Score

32

—

LowBetter than 69% of packages

Maintenance66

Regular maintenance activity

Popularity6

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity42

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

17

Last Release

198d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/992caca8822584db4d06639319dabf1c00a418afdf8a3be7d6d735f0fda07429?d=identicon)[aaronkatema](/maintainers/aaronkatema)

---

Top Contributors

[![Aeronk](https://avatars.githubusercontent.com/u/13133754?v=4)](https://github.com/Aeronk "Aeronk (25 commits)")

### Embed Badge

![Health badge](/badges/katema-laravel-whatsapp/health.svg)

```
[![Health](https://phpackages.com/badges/katema-laravel-whatsapp/health.svg)](https://phpackages.com/packages/katema-laravel-whatsapp)
```

###  Alternatives

[defstudio/telegraph

A laravel facade to interact with Telegram Bots

816334.1k3](/packages/defstudio-telegraph)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.0k](/packages/simplestats-io-laravel-client)[rapidez/core

Rapidez Core

1823.5k72](/packages/rapidez-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)