PHPackages                             irwan-runtuwene/driver-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. irwan-runtuwene/driver-whatsapp

ActiveLibrary[API Development](/categories/api)

irwan-runtuwene/driver-whatsapp
===============================

WABA On-Premise driver for BotMan

v1.0.0(3mo ago)71.6k7MITPHPPHP >=7.0

Since Jul 16Pushed 3mo ago2 watchersCompare

[ Source](https://github.com/irwan-runtuwene/driver-whatsapp)[ Packagist](https://packagist.org/packages/irwan-runtuwene/driver-whatsapp)[ Docs](http://github.com/irwan-runtuwene/driver-whatsapp)[ RSS](/packages/irwan-runtuwene-driver-whatsapp/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (5)Versions (4)Used By (0)

BotMan WhatsApp Business Cloud API Driver
=========================================

[](#botman-whatsapp-business-cloud-api-driver)

BotMan driver to connect WhatsApp Business Cloud API with [BotMan](https://github.com/botman/botman)

WhatsApp Business Cloud API
---------------------------

[](#whatsapp-business-cloud-api)

This driver integrates with the WhatsApp Business Platform via the Cloud API. For API documentation, visit [Meta for Developers - WhatsApp Business Platform](https://developers.facebook.com/docs/whatsapp/cloud-api)

**API Version**: This driver uses v21.0 by default (latest stable as of January 2026). You can configure a different version if needed via `WHATSAPP_API_VERSION` environment variable.

**Note**: This driver also maintains backward compatibility with WhatsApp Business On-Premise API.

Installation & Setup
------------------------

[](#installation--setup)

Install via Composer:

```
composer require irwan-runtuwene/driver-whatsapp
```

### Configuration

[](#configuration)

#### BotMan Studio (Laravel)

[](#botman-studio-laravel)

Add the following entries to your `.env` file:

```
# WhatsApp Business Cloud API
WHATSAPP_API_VERSION=v21.0
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_VERIFY_TOKEN=your_verify_token

# Optional: Business Account ID
WHATSAPP_BUSINESS_ACCOUNT_ID=your_business_account_id

# Error handling
WHATSAPP_THROW_EXCEPTIONS=true

# Media storage
WHATSAPP_MEDIA_TEMP_PATH=storage/app/whatsapp/media
```

#### Standalone BotMan

[](#standalone-botman)

Pass configuration array when creating BotMan instance:

```
$config = [
    'whatsapp' => [
        'api_version' => 'v21.0',
        'phone_number_id' => 'your_phone_number_id',
        'access_token' => 'your_access_token',
        'verify_token' => 'your_verify_token',
        'throw_http_exceptions' => true,
    ]
];

$botman = BotManFactory::create($config);
```

### Legacy On-Premise API Support

[](#legacy-on-premise-api-support)

For backward compatibility with On-Premise API:

```
WHATSAPP_PARTNER=https://your-waba-host
WHATSAPP_TOKEN=your-bearer-token
```

Breaking Changes from Previous Version
--------------------------------------

[](#breaking-changes-from-previous-version)

### Migration from On-Premise to Cloud API

[](#migration-from-on-premise-to-cloud-api)

If you're upgrading from the previous On-Premise-only version, you'll need to make the following changes:

#### 1. Environment Variables (Required)

[](#1-environment-variables-required)

**Old Configuration:**

```
WHATSAPP_PARTNER=https://your-waba-host
WHATSAPP_TOKEN=your-bearer-token
```

**New Configuration:**

```
WHATSAPP_API_VERSION=v21.0
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ACCESS_TOKEN=your_access_token
WHATSAPP_VERIFY_TOKEN=your_verify_token
```

#### 2. Webhook Payload Structure

[](#2-webhook-payload-structure)

The webhook payload structure has changed from On-Premise to Cloud API format:

**Old Format (On-Premise):**

```
{
  "messages": [{
    "from": "1234567890",
    "type": "text",
    "text": {"body": "Hello"}
  }],
  "contacts": [...]
}
```

**New Format (Cloud API):**

```
{
  "entry": [{
    "changes": [{
      "value": {
        "messages": [{
          "from": "1234567890",
          "type": "text",
          "text": {"body": "Hello"}
        }],
        "contacts": [...],
        "metadata": {...}
      }
    }]
  }]
}
```

> **Note:** The driver automatically handles both formats, so no code changes are needed on your end.

#### 3. Message ID Access

[](#3-message-id-access)

**Old Way:**

```
// This may not work consistently
$messageId = $message->getPayload()->get('id');
```

**New Way:**

```
// Reliable for Cloud API
$payload = $message->getPayload();
$messageId = $payload->get('messages')[0]['id'] ?? null;

// Or from the event directly
$messageId = $message->getPayload()->get('entry')[0]['changes'][0]['value']['messages'][0]['id'] ?? null;
```

#### 4. Media Handling

[](#4-media-handling)

Media handling has significantly improved but requires different approach:

**Old Way (On-Premise):**

```
// Media URLs were directly accessible
$mediaUrl = $message->getPayload()->get('image')['url'];
```

**New Way (Cloud API):**

```
// Media requires a two-step process
$media = $message->getPayload()->get('media');
if ($media) {
    $driver = $bot->getDriver();

    // Step 1: Get media URL
    $mediaInfo = $driver->getMediaUrl($media['id']);

    // Step 2: Download media
    $driver->downloadMedia($mediaInfo['url'], $savePath);
}
```

#### 5. Interactive Messages (New Feature)

[](#5-interactive-messages-new-feature)

The previous version had limited interactive message support. The new version includes full support:

**Buttons (Now Available):**

```
use BotMan\Drivers\Whatsapp\Extensions\ButtonTemplate;
use BotMan\Drivers\Whatsapp\Extensions\ElementButton;

$template = ButtonTemplate::create('Choose an option:')
    ->addButton(ElementButton::create('option_1', 'Option 1'))
    ->addButton(ElementButton::create('option_2', 'Option 2'));

$bot->reply($template);
```

**Lists (Now Available):**

```
use BotMan\Drivers\Whatsapp\Extensions\ListTemplate;
use BotMan\Drivers\Whatsapp\Extensions\ListSection;
use BotMan\Drivers\Whatsapp\Extensions\ListRow;

$section = ListSection::create('Products')
    ->addRow(ListRow::create('prod_1', 'Product 1', 'Description'));

$template = ListTemplate::create('Our Products', 'View Catalog')
    ->addSection($section);

$bot->reply($template);
```

#### 6. Template Messages

[](#6-template-messages)

Template message structure has changed:

**Old Way:**

```
// Limited or no template support
```

**New Way:**

```
use BotMan\Drivers\Whatsapp\Extensions\TemplateMessage;

$template = TemplateMessage::create('order_confirmation', 'en_US')
    ->addBodyParameters(['John Doe', 'ORD-12345', '$99.99']);

$bot->reply($template);
```

#### 7. New Features Not in Previous Version

[](#7-new-features-not-in-previous-version)

The following features are entirely new and have no equivalent in the On-Premise version:

- **Reactions** - React to messages with emojis
- **Reply Context** - Quote/reply to specific messages
- **Mark as Read** - Send read receipts
- **Contact Messages** - Share vCard contacts
- **Media Upload** - Upload media to WhatsApp CDN
- **Webhook Verification** - Automatic webhook challenge response

#### 8. Error Response Format

[](#8-error-response-format)

Error responses now use Cloud API format:

**Old Format:**

```
{
  "errors": {
    "code": "...",
    "title": "..."
  }
}
```

**New Format:**

```
{
  "error": {
    "message": "...",
    "type": "...",
    "code": 123,
    "fbtrace_id": "..."
  }
}
```

> **Note:** The driver's exception handling automatically adapts to both formats.

Features
--------

[](#features)

### ✅ Fully Supported

[](#-fully-supported)

- **Text Messages** - Send and receive text messages
- **Media Messages** - Images, videos, audio, documents, stickers
- **Interactive Messages**
    - Buttons (up to 3 buttons)
    - Lists (up to 10 items per section)
- **Template Messages** - Send pre-approved message templates
- **Location Messages** - Send and receive location data
- **Contact Messages** - Share contact cards
- **Reactions** - React to messages with emojis
- **Reply Context** - Reply to specific messages
- **Media Management** - Upload and download media files
- **Message Status** - Mark messages as read
- **Webhook Verification** - Automatic webhook verification
- **WhatsApp Flows** - Interactive multi-step experiences with forms and screens

Usage Examples
--------------

[](#usage-examples)

### Text Messages

[](#text-messages)

```
$botman->hears('hello', function ($bot) {
    $bot->reply('Hello! How can I help you?');
});
```

### Button Messages

[](#button-messages)

```
use BotMan\Drivers\Whatsapp\Extensions\ButtonTemplate;
use BotMan\Drivers\Whatsapp\Extensions\ElementButton;

$botman->hears('menu', function ($bot) {
    $template = ButtonTemplate::create('Choose an option:')
        ->addButton(ElementButton::create('option_1', 'Option 1'))
        ->addButton(ElementButton::create('option_2', 'Option 2'))
        ->addButton(ElementButton::create('option_3', 'Option 3'));

    $bot->reply($template);
});
```

### List Messages

[](#list-messages)

```
use BotMan\Drivers\Whatsapp\Extensions\ListTemplate;
use BotMan\Drivers\Whatsapp\Extensions\ListSection;
use BotMan\Drivers\Whatsapp\Extensions\ListRow;

$botman->hears('catalog', function ($bot) {
    $section = ListSection::create('Products')
        ->addRow(ListRow::create('prod_1', 'Product 1', 'Description 1'))
        ->addRow(ListRow::create('prod_2', 'Product 2', 'Description 2'));

    $template = ListTemplate::create('Our Products', 'View Catalog')
        ->addSection($section);

    $bot->reply($template);
});
```

### Template Messages

[](#template-messages)

```
use BotMan\Drivers\Whatsapp\Extensions\TemplateMessage;

$botman->hears('order confirmation', function ($bot) {
    $template = TemplateMessage::create('order_confirmation', 'en_US')
        ->addBodyParameters(['John Doe', 'ORD-12345', '$99.99']);

    $bot->reply($template);
});
```

### Media Messages

[](#media-messages)

```
use BotMan\Drivers\Whatsapp\Extensions\MediaTemplate;

// Send image
$botman->hears('send image', function ($bot) {
    $media = MediaTemplate::create(MediaTemplate::TYPE_IMAGE)
        ->link('https://example.com/image.jpg')
        ->caption('Check this out!');

    $bot->reply($media);
});

// Send document
$botman->hears('send pdf', function ($bot) {
    $media = MediaTemplate::create(MediaTemplate::TYPE_DOCUMENT)
        ->link('https://example.com/document.pdf')
        ->filename('Document.pdf')
        ->caption('Here is the document');

    $bot->reply($media);
});
```

### Location Messages

[](#location-messages)

```
use BotMan\Drivers\Whatsapp\Extensions\LocationMessage;

$botman->hears('location', function ($bot) {
    $location = LocationMessage::create(37.7749, -122.4194)
        ->name('San Francisco Office')
        ->address('123 Market St, San Francisco, CA');

    $bot->reply($location);
});
```

### Reactions

[](#reactions)

```
use BotMan\Drivers\Whatsapp\Extensions\ReactionMessage;

$botman->receivedMessage(function ($bot, $message) {
    // React to the message with a thumbs up
    $messageId = $message->getPayload()->get('messages')[0]['id'];
    $reaction = ReactionMessage::create($messageId, '👍');

    $bot->reply($reaction);
});
```

### WhatsApp Flows

[](#whatsapp-flows)

WhatsApp Flows allow you to create interactive, multi-step experiences within WhatsApp.

```
use BotMan\Drivers\Whatsapp\Extensions\FlowTemplate;

// Send a flow message
$botman->hears('start survey', function ($bot) {
    $flow = FlowTemplate::create(
        'your_flow_id',           // Flow ID from WhatsApp Manager
        'Start Survey',            // Button text
        'Please complete our customer satisfaction survey'
    )
    ->header('Customer Survey')
    ->footer('Takes only 2 minutes')
    ->navigate('welcome_screen', ['customer_id' => '12345'])
    ->mode('published');  // or 'draft' for testing

    $bot->reply($flow);
});

// Handle flow responses
$botman->receivedMessage(function ($bot, $message) {
    $payload = $message->getPayload();

    if ($flowResponse = $payload->get('flow_response')) {
        $responseData = json_decode($flowResponse['response_json'], true);

        // Process the flow response data
        $bot->reply('Thank you for completing the survey!');

        // Access flow data
        $name = $flowResponse['name'];
        $data = $responseData;  // Contains user's form submissions
    }
});

// Data exchange flow
$botman->hears('update profile', function ($bot) {
    $flow = FlowTemplate::create(
        'profile_flow_id',
        'Update Profile',
        'Update your account information'
    )
    ->dataExchange([
        'current_name' => 'John Doe',
        'current_email' => 'john@example.com',
    ])
    ->mode('published');

    $bot->reply($flow);
});
```

### Reply to Messages

[](#reply-to-messages)

```
$botman->hears('quote me', function ($bot, $message) {
    $messageId = $message->getPayload()->get('messages')[0]['id'];

    // Use the driver to set reply context
    $driver = $bot->getDriver();
    $driver->replyTo($messageId);

    $bot->reply('This is a reply to your message!');
});
```

### Media Download

[](#media-download)

```
$botman->receivedMessage(function ($bot, $message) {
    $payload = $message->getPayload();

    if ($media = $payload->get('media')) {
        $driver = $bot->getDriver();

        // Get media URL
        $mediaInfo = $driver->getMediaUrl($media['id']);

        // Download media
        $savePath = storage_path("app/whatsapp/media/{$media['id']}");
        $driver->downloadMedia($mediaInfo['url'], $savePath);

        $bot->reply('Media downloaded successfully!');
    }
});
```

### Mark as Read

[](#mark-as-read)

```
$botman->receivedMessage(function ($bot, $message) {
    $messageId = $message->getPayload()->get('messages')[0]['id'];
    $driver = $bot->getDriver();
    $driver->markAsRead($messageId);
});
```

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability, please send an e-mail to . All security vulnerabilities will be promptly addressed.

License
-------

[](#license)

This driver is open-source software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance80

Actively maintained with recent releases

Popularity23

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity44

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 ~645 days

Total

3

Last Release

106d ago

Major Versions

v0.0.2 → v1.0.02026-01-26

### Community

Maintainers

![](https://www.gravatar.com/avatar/8a8e269a8cea5f660aadda2fa2f2eaf5ec817642f68ec41516e00c79bb050f0d?d=identicon)[irwan-runtuwene](/maintainers/irwan-runtuwene)

---

Top Contributors

[![irwan-runtuwene](https://avatars.githubusercontent.com/u/1209559?v=4)](https://github.com/irwan-runtuwene "irwan-runtuwene (17 commits)")

---

Tags

botwhatsappBotmanWABA

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/irwan-runtuwene-driver-whatsapp/health.svg)

```
[![Health](https://phpackages.com/badges/irwan-runtuwene-driver-whatsapp/health.svg)](https://phpackages.com/packages/irwan-runtuwene-driver-whatsapp)
```

###  Alternatives

[botman/driver-telegram

Telegram driver for BotMan

92437.3k6](/packages/botman-driver-telegram)[botman/driver-slack

Slack driver for BotMan

51267.0k2](/packages/botman-driver-slack)

PHPackages © 2026

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