Laravel Whatsapp Widget

https://github.com/jeffersongoncalves/laravel-whatsapp-widget
Admin
Laravel Whatsapp Widget is a customizable Laravel package that provides a floating WhatsApp button...
Tokens:6,186
Snippets:68
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install package with Composer

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Run this command to install the jeffersongoncalves/laravel-whatsapp-widget package via Composer.

```bash
composer require jeffersongoncalves/laravel-whatsapp-widget
```

--------------------------------

### Service provider configuration

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Example of the package service provider that registers migrations, config, assets, views, translations, and routes.

```php
class WhatsappWidgetServiceProvider extends PackageServiceProvider
{
    public function configurePackage(Package $package): void
    {
        $package->name('whatsapp-widget')
            ->hasMigration('create_whatsapp_agents_table')
            ->hasConfigFile('whatsapp-widget')
            ->hasAssets()
            ->hasViews()
            ->hasTranslations()
            ->hasRoute('whatsapp-widget');
    }
}
```

--------------------------------

### Create and use WhatsappAgent model with image URL and redirect link

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Model usage with table columns and creation example. Retrieval of image URL uses configured disk and signed redirect URL generation.

```php
// Table: whatsapp_agents
// Columns: id, active (bool), name, phone, text (nullable), image (nullable), timestamps

use JeffersonGoncalves\WhatsappWidget\Models\WhatsappAgent;

// Create an agent
WhatsappAgent::create([
    'active' => true,
    'name' => 'Support Team',
    'phone' => '+5511999999999',
    'text' => 'Hello, I need help with...',
    'image' => 'agents/avatar.jpg',  // Path on configured storage disk
]);

// Get image URL (uses configured disk)
$agent->image_url; // Storage::disk(config('whatsapp-widget.disk'))->url($agent->image)

// Generate signed redirect URL
$agent->getLinkByWhatsappAgent($agent, config('whatsapp-widget.url'));
```

--------------------------------

### Create WhatsApp agent with WhatsappAgent model

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Example seeder that creates a WhatsApp agent record. The 'image' field is optional. Agents can also be added through the application's admin panel.

```php
use JeffersonGoncalves\WhatsappWidget\Models\WhatsappAgent;

WhatsappAgent::create([
    'active' => true,
    'name' => 'Customer Support',
    'phone' => '+1234567890',
    'text' => 'Hello! I have a question about your product.',
    'image' => 'path/to/agent-avatar.jpg', // Optional
]);
```

--------------------------------

### Publish and run migration

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Publish the migration file and run the migrate command to create the whatsapp_agents table.

```bash
php artisan vendor:publish --tag=whatsapp-widget-migrations
php artisan migrate
```

--------------------------------

### Run migrations for laravel-whatsapp-widget

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Runs the database migrations for the package, creating the necessary tables for WhatsApp agents.

```bash
php artisan migrate
```

--------------------------------

### Environment variables

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Set the WHATSAPP_KEY and FILESYSTEM_DISK environment variables for the package.

```env
WHATSAPP_KEY=your-secret-api-key
FILESYSTEM_DISK=public
```

--------------------------------

### Publish config (optional)

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Publish the package configuration file to customize settings.

```bash
php artisan vendor:publish --tag=whatsapp-widget-config
```

--------------------------------

### Publish views (optional)

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Publish the package views to customize the widget appearance.

```bash
php artisan vendor:publish --tag=whatsapp-widget-views
```

--------------------------------

### Run dev commands

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Development commands for the package: run Pest tests, run PHPStan static analysis, and format code with Pint.

```bash
# Run tests
vendor/bin/pest

# Run static analysis
vendor/bin/phpstan analyse

# Format code
vendor/bin/pint
```

--------------------------------

### Configure audio notification options

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Configuration options to enable or disable the audio and set playback to once per day.

```php
'audio' => true,            // Enable/disable audio
'play_audio_daily' => true, // true = once per day (cookie), false = every page load
```

--------------------------------

### Configure whatsapp-widget.php

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Configuration file for the Laravel WhatsApp widget package. Defines audio settings, storage disk, app URL, widget name, API key, and position. The 'key' is used for API authentication and must be set via the WHATSAPP_KEY environment variable.

```php
// config/whatsapp-widget.php
return [
    'audio' => true,                                    // Audio notification toggle
    'play_audio_daily' => true,                         // Once per day or every load
    'disk' => env('FILESYSTEM_DISK', 'local'),          // Storage disk for agent images
    'url' => env('APP_URL', 'http://localhost'),        // Used in redirect ref param
    'name' => env('APP_NAME', 'Laravel App'),           // Displayed in widget header
    'key' => env('WHATSAPP_KEY'),                       // API authentication key
    'position' => 'right',                              // 'left' or 'right'
];
```

--------------------------------

### Namespace structure

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Shows the directory structure of the package's namespace.

```text
JeffersonGoncalves\WhatsappWidget\
    WhatsappWidgetServiceProvider     # Registers config, views, migrations, routes, assets, translations
    Models\
        WhatsappAgent                 # Eloquent model for whatsapp_agents table
    Http\
        Controllers\
            WhatsappsController       # JSON API endpoint for listing active agents
            RedirectController        # Redirect page to wa.me link
```

--------------------------------

### Include whatsapp-widget head and body templates in layout

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Adds the widget's head template in the layout's <head> section and the body template before the closing </body> tag. Both includes are required for the widget to render correctly.

```php
@include('whatsapp-widget::whatsapp-widget-head')
```

```php
@include('whatsapp-widget::whatsapp-widget-body')
```

--------------------------------

### Publish laravel-whatsapp-widget assets with artisan vendor:publish

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Publishes the package's config, migration, asset, translation, and view files. Each command uses a specific tag to publish only the corresponding files.

```bash
php artisan vendor:publish --tag=whatsapp-widget-config
```

```bash
php artisan vendor:publish --tag=whatsapp-widget-migrations
```

```bash
php artisan vendor:publish --tag=whatsapp-widget-assets
```

```bash
php artisan vendor:publish --tag=whatsapp-widget-translations
```

```bash
php artisan vendor:publish --tag=whatsapp-widget-views
```

--------------------------------

### JSON API controller for active agents

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

WhatsappsController returns JSON list of active agents with signed links.

```php
// WhatsappsController - returns active agents as JSON
class WhatsappsController
{
    public function __invoke(Request $request): JsonResponse
    {
        abort_if($request->token !== config('whatsapp-widget.key'), 403);
        $whatsappAgents = WhatsappAgent::query()->where('active', true)->get();
        // Returns id, name, image_url, phone, signed link for each agent
    }
}
```

--------------------------------

### Include widget Blade partials in layout head and body

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Blade partials load Vite assets and render the widget. Only renders when active agents exist.

```html
<head>
    <!-- Loads Vite CSS and JS assets -->
    @include('whatsapp-widget::whatsapp-widget-head')
</head>
<body>
    <!-- Your content -->

    <!-- Renders the floating widget -->
    @include('whatsapp-widget::whatsapp-widget-body')
</body>
```

--------------------------------

### Test redirect with signed URL

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Pest test for the redirect route. Creates an agent and generates a signed URL using the 'whatsapp-widget.redirect' route with parameters including the agent ID, phone number, and the configured URL as the 'ref' parameter. Asserts the response is OK and contains the agent name.

```php
it('redirects to agent page with signed URL', function () {
    $agent = WhatsappAgent::create([
        'active' => true,
        'name' => 'Test Agent',
        'phone' => '+5511999999999',
        'text' => 'Hello',
    ]);

    $url = URL::signedRoute('whatsapp-widget.redirect', [
        'whatsapp_agent' => $agent->id,
        'agent' => $agent->id,
        'number' => $agent->phone,
        'ref' => config('whatsapp-widget.url'),
    ]);

    $this->get($url)->assertOk()->assertSee('Test Agent');
});
```

--------------------------------

### Configure redirect screen colors

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Configures the colors for the redirect (loading) screen. This palette is separate from the main widget colors.

```php
'redirect' => [
    'background' => '#f1f1f1',
    'text' => '#7e7e7e',
    'name' => '#333333',
    'accent' => '#25D366',
    'spinner' => '#92d1c3',
],
```

--------------------------------

### Customize widget icons

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Replaces the default icons with custom ones by pointing to a public URL or path. Leave a value as null to keep the bundled default.

```php
'icons' => [
    'trigger' => asset('images/my-whatsapp.svg'), // Floating button + modal header
    'avatar' => asset('images/my-avatar.png'),    // Fallback agent avatar
    'redirect' => asset('images/my-icon.png'),    // Redirect screen icon
],
```

--------------------------------

### Configure widget colors

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Configures the widget and modal colors via CSS custom properties. Changing these values does not require rebuilding assets.

```php
'colors' => [
    'primary' => '#25D366',      // Button, modal header and accents
    'primary_text' => '#ffffff', // Text/icon on top of the primary color
    'badge' => '#ff0000',        // Notification badge background
    'modal_bg' => '#ffffff',     // Modal background
    'modal_text' => '#111111',   // Agent name / main text
    'modal_muted' => '#9aa0a6',  // Secondary text
    'online' => '#25D366',       // Online status dot and label
],
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Runs the test suite for the package using Composer. This command is typically used during development to verify that all tests pass.

```bash
composer test
```

--------------------------------

### Widget routes: JSON API and redirect page

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Routes for the JSON API with token authentication and signed redirect page, plus named route.

```php
// routes/whatsapp-widget.php
// JSON API - requires WHATSAPP_KEY token for authentication
GET /api/whatsapps?token={key}
// Returns: [{id, name, image_url, phone, link}, ...]

// Redirect page - uses signed URLs for security
GET /whatsapp-widget/redirect/{whatsapp_agent}
// Named: whatsapp-widget.redirect
```

--------------------------------

### Test model image_url accessor

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Pest tests for the WhatsappAgent model's image_url accessor. The first test sets the disk to 'public' and verifies the generated URL contains the image path. The second test confirms that when no image is set, image_url returns null.

```php
it('generates image URL from storage disk', function () {
    config(['whatsapp-widget.disk' => 'public']);

    $agent = WhatsappAgent::create([
        'active' => true,
        'name' => 'Agent',
        'phone' => '+5511999999999',
        'image' => 'agents/photo.jpg',
    ]);

    expect($agent->image_url)->toContain('agents/photo.jpg');
});

it('returns null image URL when no image', function () {
    $agent = WhatsappAgent::create([
        'active' => true,
        'name' => 'Agent',
        'phone' => '+5511999999999',
    ]);

    expect($agent->image_url)->toBeNull();
});
```

--------------------------------

### Redirect controller with view response

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

RedirectController finds the agent from ID and returns the redirect view.

```php
class RedirectController
{
    public function __invoke(string $whatsapp_agent): View
    {
        $whatsappAgent = WhatsappAgent::query()->where('id', $whatsapp_agent)->firstOrFail();
        return view('whatsapp-widget::whatsapp-redirect', compact('whatsappAgent'));
    }
}
```

--------------------------------

### Define translation keys for widget

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Available translation keys with prefixes for the widget interface.

```php
// Available keys:
'redirecting_to'  => 'Redirecting to',
'close'           => 'Close',
'close_title'     => 'Close Support',
'we_are_available' => 'We are available',
'online'          => 'Online',
'icon_alt'        => 'WhatsApp icon',
```

--------------------------------

### JavaScript redirect variable

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

JavaScript variable set on page that auto redirects agent to WhatsApp.

```javascript
var ww_whatsapp_chat_redirect = "https://wa.me/{phone}?text={encoded_text}";
```

--------------------------------

### Test API endpoint with Pest

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/resources/boost/skills/whatsapp-widget-development/SKILL.md

Pest tests for the API endpoint. The first test sets the config key to 'test-key', creates an active agent, and verifies the response is OK with one JSON item containing the agent name. The second test expects a 403 Forbidden when an invalid token is provided.

```php
use JeffersonGoncalves\WhatsappWidget\Models\WhatsappAgent;

it('returns active agents as JSON', function () {
    config(['whatsapp-widget.key' => 'test-key']);

    WhatsappAgent::create([
        'active' => true,
        'name' => 'Agent 1',
        'phone' => '+5511999999999',
    ]);

    $this->get('/api/whatsapps?token=test-key')
        ->assertOk()
        ->assertJsonCount(1)
        ->assertJsonFragment(['name' => 'Agent 1']);
});

it('rejects requests without valid token', function () {
    $this->get('/api/whatsapps?token=wrong-key')
        ->assertForbidden();
});
```

--------------------------------

### Set widget position to left

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Sets the widget to appear on the left side of the page. Modify the 'position' value in config/whatsapp-widget.php.

```php
'position' => 'left',
```

--------------------------------

### Set widget position to right

Source: https://github.com/jeffersongoncalves/laravel-whatsapp-widget/blob/master/README.md

Sets the widget to appear on the right side of the page. This is the default position. Modify the 'position' value in config/whatsapp-widget.php.

```php
'position' => 'right',
```
Tokens:
Raw