PHPackages                             eseperio/yii2-whatsapp-web-rest-client - 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. eseperio/yii2-whatsapp-web-rest-client

ActiveYii2-extension[API Development](/categories/api)

eseperio/yii2-whatsapp-web-rest-client
======================================

A Yii2 client to handle connection with WhatsApp Web REST API (avoylenko/wwebjs-api)

1.0.0(7mo ago)03MITPHPPHP >=7.4

Since Sep 15Pushed 3mo agoCompare

[ Source](https://github.com/Eseperio/yii2-whatsapp-web-rest-client)[ Packagist](https://packagist.org/packages/eseperio/yii2-whatsapp-web-rest-client)[ RSS](/packages/eseperio-yii2-whatsapp-web-rest-client/feed)WikiDiscussions main Synced 1mo ago

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

Yii2 WhatsApp Web REST Client
=============================

[](#yii2-whatsapp-web-rest-client)

A Yii2 client library to handle connections with WhatsApp Web REST API through the [avoylenko/wwebjs-api](https://github.com/avoylenko/wwebjs-api) Docker container.

This library provides a comprehensive Yii2 module and component for interacting with WhatsApp Web through a REST API wrapper for the whatsapp-web.js library.

Features
--------

[](#features)

- **Session Management**: Start, stop, restart, and monitor WhatsApp Web sessions
- **Messaging**: Send text, media, location, contact, and poll messages
- **Group Management**: Create groups, manage participants, modify settings
- **Contact Management**: Block/unblock contacts, get contact information
- **Message Operations**: Reply, react, delete, and download message media
- **Chat Features**: Typing indicators, read receipts, chat management
- **Room Management**: List and filter chats/rooms with advanced filtering options
- **Media Support**: Send images, videos, audio, documents from URLs or base64 data
- **Caching Support**: Configurable caching for improved performance
- **Configurable**: Enable/disable specific features through module configuration
- **Error Handling**: Comprehensive exception handling and response models

Requirements
------------

[](#requirements)

- PHP >= 7.4
- Yii2 >= 2.0.14
- [avoylenko/wwebjs-api](https://github.com/avoylenko/wwebjs-api) Docker container running

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

[](#installation)

Install via Composer:

```
composer require eseperio/yii2-whatsapp-web-rest-client
```

Setup
-----

[](#setup)

### 1. Configure the Component

[](#1-configure-the-component)

Add the WhatsAppClient as a main application component to your Yii2 application config:

```
'components' => [
    'whatsapp' => [
        'class' => 'eseperio\whatsapp\components\WhatsAppClient',
        'baseUrl' => 'http://localhost:3000', // Your wwebjs-api URL
        'apiKey' => 'your-api-key', // Optional API key
        'defaultSessionId' => 'default',
        'timeout' => 30,
        // Caching configuration (optional)
        'enableCache' => true, // Enable caching for better performance
        'cacheComponent' => 'cache', // Cache component name
        'cacheDuration' => 300, // Cache duration in seconds (5 minutes)
    ],
],
```

### Alternative: Module Configuration (deprecated)

[](#alternative-module-configuration-deprecated)

You can still use the module configuration for backward compatibility, but it's recommended to use the main component configuration above:

```
'modules' => [
    'whatsapp' => [
        'class' => 'eseperio\whatsapp\WhatsAppModule',
        // Enable/disable features
        'enableSessionManagement' => true,
        'enableMessaging' => true,
        'enableContactManagement' => true,
        'enableGroupChat' => true,
        'enableChannels' => true,
        'enableMedia' => true,
        // Component configuration
        'whatsappClientConfig' => [
            'baseUrl' => 'http://localhost:3000', // Your wwebjs-api URL
            'apiKey' => 'your-api-key', // Optional API key
            'defaultSessionId' => 'default',
            'timeout' => 30,
        ],
        // Caching configuration (optional)
        'enableCache' => true, // Enable caching for better performance
        'cacheComponent' => 'cache', // Cache component name
        'cacheDuration' => 300, // Cache duration in seconds (5 minutes)
    ],
],
```

### 2. Start the wwebjs-api Container

[](#2-start-the-wwebjs-api-container)

Make sure you have the WhatsApp Web REST API container running:

```
docker run -d \
  --name wwebjs-api \
  -p 3000:3000 \
  -v $(pwd)/sessions:/app/sessions \
  avoylenko/wwebjs-api
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
// Get the WhatsApp client component
$whatsapp = Yii::$app->whatsapp;

// Start a session
$response = $whatsapp->startSession('my-session');
if ($response->isSuccessful()) {
    echo "Session started successfully\n";
}

// Get QR code for authentication
$qrResponse = $whatsapp->getSessionQr('my-session');
echo "Scan this QR code: " . $qrResponse->get('qr') . "\n";

// Check session status
$status = $whatsapp->getSessionStatus('my-session');
echo "Session state: " . $status->get('state') . "\n";
```

### Sending Messages

[](#sending-messages)

```
$whatsapp = Yii::$app->whatsapp;

// Send text message
$response = $whatsapp->sendTextMessage(
    '1234567890@c.us', // Chat ID
    'Hello from Yii2!',
    [], // Options
    'my-session' // Session ID
);

// Send media from URL
$response = $whatsapp->sendMediaFromUrl(
    '1234567890@c.us',
    'https://example.com/image.jpg',
    ['caption' => 'Check out this image!']
);

// Send location
$response = $whatsapp->sendLocationMessage(
    '1234567890@c.us',
    -6.2, // Latitude
    106.8, // Longitude
    'Jakarta, Indonesia'
);

// Send poll
$response = $whatsapp->sendPollMessage(
    '1234567890@c.us',
    'What is your favorite color?',
    ['Red', 'Blue', 'Green'],
    ['allowMultipleAnswers' => false]
);
```

### Group Management

[](#group-management)

```
$whatsapp = Yii::$app->whatsapp;

// Create a group
$response = $whatsapp->createGroup(
    'My Group',
    ['1234567890@c.us', '0987654321@c.us'], // Participants
    [] // Options
);

$groupId = $response->get('id');

// Add participants
$whatsapp->addGroupParticipants($groupId, ['1111111111@c.us']);

// Promote to admin
$whatsapp->promoteGroupParticipants($groupId, ['1234567890@c.us']);

// Set group description
$whatsapp->setGroupDescription($groupId, 'This is our group chat');

// Get invite code
$inviteResponse = $whatsapp->getGroupInviteCode($groupId);
echo "Invite link: https://chat.whatsapp.com/" . $inviteResponse->getResult();
```

### Contact Management

[](#contact-management)

```
$whatsapp = Yii::$app->whatsapp;

// Get all contacts
$contacts = $whatsapp->getContacts();
foreach ($contacts->getResult() as $contact) {
    echo $contact['name'] . ": " . $contact['number'] . "\n";
}

// Check if number is registered on WhatsApp
$isRegistered = $whatsapp->isRegisteredUser('1234567890');
if ($isRegistered->getResult()) {
    echo "Number is registered on WhatsApp\n";
}

// Block a contact
$whatsapp->blockContact('1234567890@c.us');

// Get contact profile picture
$profilePic = $whatsapp->getProfilePicUrl('1234567890@c.us');
echo "Profile picture URL: " . $profilePic->getResult();
```

### Message Operations

[](#message-operations)

```
$whatsapp = Yii::$app->whatsapp;

// Reply to a message
$response = $whatsapp->replyToMessage(
    '1234567890@c.us',
    'message-id-to-reply-to',
    'string',
    'This is my reply'
);

// React to a message
$whatsapp->reactToMessage(
    '1234567890@c.us',
    'message-id',
    '👍' // Emoji reaction
);

// Delete a message
$whatsapp->deleteMessage(
    '1234567890@c.us',
    'message-id',
    true, // Delete for everyone
    true  // Clear media
);

// Download message media
$media = $whatsapp->downloadMessageMedia('1234567890@c.us', 'message-id');
if ($media->isSuccessful()) {
    $mediaData = $media->getResult();
    file_put_contents('downloaded_media.' . $mediaData['mimetype'], base64_decode($mediaData['data']));
}
```

### Chat Features

[](#chat-features)

```
$whatsapp = Yii::$app->whatsapp;

// Send typing indicator
$whatsapp->sendTyping('1234567890@c.us');

// Send recording indicator
$whatsapp->sendRecording('1234567890@c.us');

// Stop indicators
$whatsapp->clearChatState('1234567890@c.us');

// Mark chat as seen
$whatsapp->markChatAsSeen('1234567890@c.us');

// Get all chats
$chats = $whatsapp->getChats();
foreach ($chats->getResult() as $chat) {
    echo $chat['name'] . " - " . $chat['lastMessage']['body'] . "\n";
}
```

### Room Management

[](#room-management)

```
$whatsapp = Yii::$app->whatsapp;

// Get all chats with filtering support
$chats = $whatsapp->getChats();
foreach ($chats->getResult() as $chat) {
    echo $chat['name'] . " - " . $chat['lastMessage']['body'] . "\n";
}

// Use the Room Controller for advanced filtering (when using module configuration)
use eseperio\whatsapp\controllers\RoomController;

$module = Yii::$app->getModule('whatsapp');
$controller = new RoomController('room', $module);

// Get all rooms
$allRooms = $controller->actionList('my-session');

// Get only group chats with new messages
Yii::$app->request->setQueryParams([
    'isGroup' => 1,
    'hasNewMessages' => 1
]);
$filteredRooms = $controller->actionIndex('my-session');

// Search rooms by name
Yii::$app->request->setQueryParams(['name' => 'family']);
$searchResults = $controller->actionIndex('my-session');
}
```

### Error Handling

[](#error-handling)

```
use eseperio\whatsapp\exceptions\WhatsAppException;

$whatsapp = Yii::$app->whatsapp;

try {
    $response = $whatsapp->sendTextMessage('invalid-chat-id', 'Hello');

    if (!$response->isSuccessful()) {
        echo "Error: " . $response->getErrorMessage() . "\n";
        echo "Status Code: " . $response->statusCode . "\n";
    }
} catch (WhatsAppException $e) {
    echo "WhatsApp API Error: " . $e->getMessage() . "\n";
}
```

Configuration Options
---------------------

[](#configuration-options)

### Main Component Configuration (Recommended)

[](#main-component-configuration-recommended)

```
'components' => [
    'whatsapp' => [
        'class' => 'eseperio\whatsapp\components\WhatsAppClient',

        // Base URL of your wwebjs-api container
        'baseUrl' => 'http://localhost:3000',

        // API key for authentication (optional, set in wwebjs-api container)
        'apiKey' => null, // or 'your-api-key'

        // Default session ID to use when none specified
        'defaultSessionId' => 'default',

        // Request timeout in seconds
        'timeout' => 30,

        // Caching configuration (optional)
        'enableCache' => true,        // Enable caching for better performance
        'cacheComponent' => 'cache',  // Cache component name
        'cacheDuration' => 300,       // Cache duration in seconds (5 minutes)
    ],
],
```

### Module Configuration (Backward Compatibility)

[](#module-configuration-backward-compatibility)

```
'modules' => [
    'whatsapp' => [
        'class' => 'eseperio\whatsapp\WhatsAppModule',

        // Feature toggles
        'enableSessionManagement' => true,  // Enable session operations
        'enableMessaging' => true,          // Enable message sending
        'enableContactManagement' => true,  // Enable contact operations
        'enableGroupChat' => true,          // Enable group management
        'enableChannels' => true,           // Enable channel features
        'enableMedia' => true,              // Enable media handling

        // Client component configuration
        'whatsappClientConfig' => [
            'baseUrl' => 'http://localhost:3000',  // API base URL
            'apiKey' => null,                      // Optional API key
            'defaultSessionId' => 'default',       // Default session ID
            'timeout' => 30,                       // Request timeout in seconds
        ],
    ],
],
```

### Component Configuration

[](#component-configuration)

You can also configure the component directly:

```
'components' => [
    'whatsapp' => [
        'class' => 'eseperio\whatsapp\components\WhatsAppClient',
        'baseUrl' => 'http://localhost:3000',
        'apiKey' => 'your-api-key',
        'defaultSessionId' => 'main',
        'timeout' => 60,
    ],
],
```

Session Management
------------------

[](#session-management)

The library provides comprehensive session management:

```
$whatsapp = Yii::$app->whatsapp;

// Start session
$whatsapp->startSession('session-1');

// Get session status
$status = $whatsapp->getSessionStatus('session-1');
echo $status->get('state'); // CONNECTED, UNPAIRED, etc.

// Restart session
$whatsapp->restartSession('session-1');

// Stop session
$whatsapp->stopSession('session-1');

// Terminate session completely
$whatsapp->terminateSession('session-1');

// Get all active sessions
$sessions = $whatsapp->getSessions();
```

API Response Handling
---------------------

[](#api-response-handling)

All API methods return an `ApiResponse` object:

```
$response = $whatsapp->sendTextMessage('1234567890@c.us', 'Hello');

// Check if successful
if ($response->isSuccessful()) {
    // Get result data
    $result = $response->getResult();

    // Get specific field
    $messageId = $response->get('id');

    // Convert to array
    $array = $response->toArray();
} else {
    // Handle error
    echo $response->getErrorMessage();
    echo $response->statusCode;
}
```

Documentation
-------------

[](#documentation)

- [Room Management and Caching Guide](ROOM_MANAGEMENT.md) - Detailed guide for the new room management features and caching capabilities
- [avoylenko/wwebjs-api documentation](https://github.com/avoylenko/wwebjs-api) - API details
- [whatsapp-web.js documentation](https://docs.wwebjs.dev/) - WhatsApp Web concepts

License
-------

[](#license)

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

Contributing
------------

[](#contributing)

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

Support
-------

[](#support)

- Create an issue for bug reports or feature requests
- Check the [avoylenko/wwebjs-api documentation](https://github.com/avoylenko/wwebjs-api) for API details
- Review the [whatsapp-web.js documentation](https://docs.wwebjs.dev/) for WhatsApp Web concepts

Disclaimer
----------

[](#disclaimer)

This project is not affiliated with WhatsApp or Meta. Use at your own risk and ensure compliance with WhatsApp's Terms of Service.

###  Health Score

32

—

LowBetter than 72% of packages

Maintenance72

Regular maintenance activity

Popularity3

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity38

Early-stage or recently created project

 Bus Factor1

Top contributor holds 53.3% 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

Unknown

Total

1

Last Release

237d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b1e173755eb4a5abae378ed4c8a8e8066f578c3192105c5e3f9b8ea3ef0086e7?d=identicon)[Eseperio](/maintainers/Eseperio)

---

Top Contributors

[![Eseperio](https://avatars.githubusercontent.com/u/5459366?v=4)](https://github.com/Eseperio "Eseperio (8 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (7 commits)")

---

Tags

clientyii2REST APIwhatsappwhatsapp-webwwebjs

### Embed Badge

![Health badge](/badges/eseperio-yii2-whatsapp-web-rest-client/health.svg)

```
[![Health](https://phpackages.com/badges/eseperio-yii2-whatsapp-web-rest-client/health.svg)](https://phpackages.com/packages/eseperio-yii2-whatsapp-web-rest-client)
```

###  Alternatives

[skeeks/yii2-google-api

Component for work with google api based on google/apiclient

1243.1k1](/packages/skeeks-yii2-google-api)

PHPackages © 2026

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