Filament N8n Chat Plugin

https://github.com/alkoumi/filament-n8n-chat
Admin
A seamless integration of n8n chat widget into your FilamentPHP applications with full multilingual...
Tokens:6,453
Snippets:45
Trust Score:7.6
License:MIT
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Filament N8n Chat as Local Package (Bash)

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/INSTALLATION.md

Steps to install the Filament N8n Chat plugin as a local package in a Laravel application. This involves creating a packages directory, cloning the plugin, updating composer.json, and installing the package.

```bash
mkdir packages
cd packages
git clone https://github.com/alkoumi/filament-n8n-chat.git
```

```bash
composer require alkoumi/filament-n8n-chat:@dev
```

```bash
php artisan config:clear
php artisan view:clear
```

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

### Configure Filament N8n Chat in composer.json (JSON)

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/INSTALLATION.md

Configuration snippet to be added to the main composer.json file of a Laravel application to enable local package installation of the Filament N8n Chat plugin.

```json
{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/filament-n8n-chat"
        }
    ]
}
```

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

### Install Filament N8n Chat Plugin via Composer

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Installs the Filament N8n Chat Plugin using Composer. This is the first step in integrating the chat widget into your FilamentPHP application.

```bash
composer require alkoumi/filament-n8n-chat
```

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

### Integrate Filament N8n Chat Plugin (PHP)

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/INSTALLATION.md

PHP code snippet to integrate the Filament N8n Chat plugin into an existing Filament panel by adding it to the Panel Providers. It allows setting the webhook URL and enabling the plugin.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

->plugins([
    FilamentN8nChatPlugin::make()
        ->webhookUrl('YOUR_WEBHOOK_URL')
        ->enabled(true)
])
```

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

### Configure Filament N8n Chat Environment Variables (Env)

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/INSTALLATION.md

Environment variables required for the Filament N8n Chat plugin. N8N_CHAT_ENABLED should be set to true, and N8N_CHAT_WEBHOOK_URL should contain the URL of your N8n instance's webhook.

```env
N8N_CHAT_ENABLED=true
N8N_CHAT_WEBHOOK_URL=https://your-n8n-instance.com/webhook/your-webhook-id
```

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

### Handle n8n Chat JavaScript Events and Control

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Provides examples of listening to n8n chat events and programmatically controlling the chat widget using JavaScript. This allows for advanced interactions and custom behavior.

```javascript
window.addEventListener('n8n-chat-ready', (event) => {
    console.log('N8n chat is ready!', event.detail.chat);
});

// Programmatically control the chat
window.openN8nChat();
window.closeN8nChat();
window.toggleN8nChat();
window.sendN8nMessage('Hello from code!');
```

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

### Dynamically Configure Chat Based on User

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Shows how to dynamically configure the chat widget's settings based on the current user's status or attributes. This enables personalized chat experiences.

```php
FilamentN8nChatPlugin::make()
    ->config(function () {
        return [
            'initialMessages' => auth()->check()
                ? 'Welcome back, ' . auth()->user()->name . '!'
                : 'Hello! How can I help you?',
        ];
    })
```

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

### Enable Deferred Chat Widget Loading (PHP)

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Enables deferred loading of the chat widget, initializing it only after user interaction to improve initial page load performance. This is useful for applications where immediate chat availability is not critical.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

// Defer loading until user interacts with the page
FilamentN8nChatPlugin::make()
    ->defer(true)

// Dynamic based on page type
FilamentN8nChatPlugin::make()
    ->defer(fn () => request()->routeIs('filament.admin.pages.dashboard'))
```

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

### Publish Configuration and Translations

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Publishes the plugin's configuration files and translation files to your Laravel project. This allows for customization of the chat widget's appearance and language.

```bash
php artisan vendor:publish --tag="filament-n8n-chat-config"
php artisan vendor:publish --tag="filament-n8n-chat-translations"
```

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

### Configure n8n Chat Widget Settings (PHP)

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Provides custom configuration options for the n8n chat widget, including initial messages, language settings, and i18n translations. This method allows for extensive customization of the chat's appearance and behavior.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

FilamentN8nChatPlugin::make()
    ->config(function () {
        $lang = app()->getLocale() ?? 'en';

        return [
            'defaultLanguage' => $lang,
            'initialMessages' => $lang === 'ar'
                ? [
                    'مرحبًا! أنا مساعد الذكاء الاصطناعي',
                    'كيف يمكنني مساعدتك اليوم؟',
                ]
                : [
                    'Hello! I am your AI assistant',
                    'How can I help you today?',
                ],
            'loadPreviousSession' => true,
            'allowFileUploads' => true,
            'allowedFileTypes' => '.jpg,.jpeg,.png,.pdf',
            'maxFileSize' => 5,
            'showFooter' => false,
            'showTimestamps' => true,
            'showTypingIndicator' => true,
            'enableSoundNotifications' => false,
            'autoOpen' => [
                'enabled' => false,
                'delay' => 3000,
                'showOnce' => true,
            ],
            'i18n' => [
                'en' => [
                    'title' => 'Hi there!',
                    'subtitle' => 'I am your AI assistant',
                    'footer' => '',
                    'getStarted' => 'New Conversation',
                    'inputPlaceholder' => 'Type your question...',
                ],
                'ar' => [
                    'title' => 'مرحبًا بك',
                    'subtitle' => 'أنا مساعدك الذكي',
                    'footer' => '',
                    'getStarted' => 'محادثة جديدة',
                    'inputPlaceholder' => 'اكتب سؤالك...',
                ],
            ],
        ];
    })
```

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

### Configure Filament n8n Chat Widget

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

This PHP configuration file allows extensive customization of the chat widget's appearance and behavior. It uses environment variables for sensitive settings and provides default values for various options.

```php
<?php
// config/filament-n8n-chat.php

return [
    'enabled' => env('N8N_CHAT_ENABLED', true),
    'webhook_url' => env('N8N_CHAT_WEBHOOK_URL', ''),
    'render_hook' => 'body-end',
    'defer' => false,
    'show_on_guest' => true,
    'show_on_auth' => true,
    'position' => 'right', // 'right' or 'left'

    'trigger_button' => [
        'background' => env('N8N_CHAT_TRIGGER_BG', '#764ba2'),
        'icon_color' => env('N8N_CHAT_TRIGGER_ICON', '#FFFFFF'),
        'hover_background' => env('N8N_CHAT_TRIGGER_HOVER_BG', '#667eea'),
        'pulse_color' => env('N8N_CHAT_TRIGGER_PULSE', 'rgba(102, 126, 234, 0.6)'),
    ],

    'notification_bubble' => [
        'gradient_start' => env('N8N_CHAT_BUBBLE_GRADIENT_START', '#667eea'),
        'gradient_end' => env('N8N_CHAT_BUBBLE_GRADIENT_END', '#764ba2'),
        'text_color' => env('N8N_CHAT_BUBBLE_TEXT', '#FFFFFF'),
        'shadow_color' => env('N8N_CHAT_BUBBLE_SHADOW', 'rgba(102, 126, 234, 0.4)'),
    ],

    'chat_header' => [
        'use_gradient' => env('N8N_CHAT_HEADER_GRADIENT', true),
        'gradient_start' => env('N8N_CHAT_HEADER_GRADIENT_START', '#667eea'),
        'gradient_end' => env('N8N_CHAT_HEADER_GRADIENT_END', '#764ba2'),
        'gradient_angle' => env('N8N_CHAT_HEADER_GRADIENT_ANGLE', 135),
        'text_color' => env('N8N_CHAT_HEADER_TEXT', '#FFFFFF'),
        'subtitle_color' => env('N8N_CHAT_HEADER_SUBTITLE', 'rgba(255, 255, 255, 0.8)'),
    ],

    'config' => [
        'initialMessages' => ['Hello! How can I help you today?'],
        'defaultLanguage' => 'en',
        'loadPreviousSession' => true,
        'allowFileUploads' => false,
        'allowedFileTypes' => '.jpg,.jpeg,.png,.pdf',
        'maxFileSize' => 5,
        'showFooter' => false,
        'showTimestamps' => true,
        'showTypingIndicator' => true,
        'enableSoundNotifications' => false,
        'autoOpen' => [
            'enabled' => false,
            'delay' => 3000,
            'showOnce' => true,
        ],
        'i18n' => [
            'en' => [
                'title' => 'Hi there!',
                'subtitle' => 'I am your AI assistant',
                'footer' => '',
                'getStarted' => 'New Conversation',
                'inputPlaceholder' => 'Type your question...',
            ],
        ],
    ],

    'custom_css' => '',
    'panels' => [],
];

```

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

### Integrate Filament n8n Chat Plugin in Admin Panel

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

This PHP code demonstrates a complete integration of the Filament n8n Chat plugin within a Filament admin panel provider. It configures the plugin using environment variables and dynamic settings based on the authenticated user and application locale.

```php
<?php
// app/Providers/Filament/AdminPanelProvider.php

namespace App\Providers\Filament;

use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->plugins([
                FilamentN8nChatPlugin::make()
                    ->webhookUrl(config('services.n8n.webhook_url'))
                    ->enabled(fn () => config('services.n8n.enabled', true))
                    ->showOnGuest(false)
                    ->showOnAuth(true)
                    ->panels(['admin'])
                    ->renderHook('body-end')
                    ->defer(false)
                    ->config(function () {
                        $user = auth()->user();
                        $lang = app()->getLocale();

                        return [
                            'defaultLanguage' => $lang,
                            'initialMessages' => $user
                                ? ["Welcome back, {$user->name}! How can I assist you?"]
                                : ['Hello! How can I help you today?'],
                            'loadPreviousSession' => true,
                            'showTypingIndicator' => true,
                            'i18n' => [
                                'en' => [
                                    'title' => 'Support Chat',
                                    'subtitle' => 'We typically reply within minutes',
                                    'getStarted' => 'Start Conversation',
                                    'inputPlaceholder' => 'Type your message...',
                                ],
                            ],
                        ];
                    }),
            ]);
    }
}

```

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

### Configure Environment Variables for n8n Chat

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Sets up essential environment variables for the Filament N8n Chat plugin. This includes enabling/disabling the widget, specifying the n8n webhook URL, and customizing trigger button and notification bubble colors.

```env
# Enable or disable the chat widget globally
N8N_CHAT_ENABLED=true

# Your n8n webhook URL (required)
N8N_CHAT_WEBHOOK_URL=https://your-n8n-instance.com/webhook/your-webhook-id

# Trigger button colors (optional)
N8N_CHAT_TRIGGER_BG=#764ba2
N8N_CHAT_TRIGGER_ICON=#FFFFFF
N8N_CHAT_TRIGGER_HOVER_BG=#667eea
N8N_CHAT_TRIGGER_PULSE=rgba(102, 126, 234, 0.6)

# Notification bubble gradient colors (optional)
N8N_CHAT_BUBBLE_GRADIENT_START=#667eea
N8N_CHAT_BUBBLE_GRADIENT_END=#764ba2
N8N_CHAT_BUBBLE_TEXT=#FFFFFF

# Chat header gradient colors (optional)
N8N_CHAT_HEADER_GRADIENT=true
N8N_CHAT_HEADER_GRADIENT_START=#667eea
N8N_CHAT_HEADER_GRADIENT_END=#764ba2
N8N_CHAT_HEADER_GRADIENT_ANGLE=135
N8N_CHAT_HEADER_TEXT=#FFFFFF
```

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

### Control Chat Widget Visibility with enabled() Method

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Dynamically enables or disables the chat widget using the `enabled()` method. This can accept a boolean value or a closure to conditionally display the widget based on user roles or other application logic.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

// Enable only for admin users
FilamentN8nChatPlugin::make()
    ->enabled(fn () => auth()->user()?->hasRole('admin'))

// Enable only during business hours
FilamentN8nChatPlugin::make()
    ->enabled(fn () => now()->hour >= 9 && now()->hour < 17)

// Simple boolean disable
FilamentN8nChatPlugin::make()
    ->enabled(false)
```

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

### Control Chat Widget Visibility (PHP)

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Controls the visibility of the chat widget based on user authentication status. Use `showOnGuest()` and `showOnAuth()` methods to independently show or hide the chat for guests and authenticated users.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

// Show only for authenticated users
FilamentN8nChatPlugin::make()
    ->showOnGuest(false)
    ->showOnAuth(true)

// Show only for guest users
FilamentN8nChatPlugin::make()
    ->showOnGuest(true)
    ->showOnAuth(false)

// Dynamic based on conditions
FilamentN8nChatPlugin::make()
    ->showOnAuth(fn () => auth()->user()?->email_verified_at !== null)
```

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

### Specify Chat Widget Render Hook (PHP)

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Specifies where in the HTML structure the chat widget should be injected. Supports various Filament render hook positions to control the placement of the chat widget on the page.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

// Available positions: 'head-start', 'head-end', 'body-start', 'body-end',
// 'footer', 'sidebar-start', 'sidebar-end', 'topbar-start', 'topbar-end',
// 'content-start', 'content-end'

FilamentN8nChatPlugin::make()
    ->renderHook('body-end') // Default position

FilamentN8nChatPlugin::make()
    ->renderHook('footer')
```

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

### Conditionally Enable Chat for Specific User Roles

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Demonstrates how to conditionally enable the chat widget based on user roles. This allows you to control who can access the chat functionality within your Filament application.

```php
FilamentN8nChatPlugin::make()
    ->enabled(fn () => auth()->user()?->hasRole('admin'))
```

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

### Control n8n Chat Widget with JavaScript API

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

The chat widget exposes global JavaScript methods for programmatic control. These methods become available after the `n8n-chat-ready` event fires, allowing for dynamic interaction with the chat from your frontend code.

```javascript
// Listen for chat initialization
window.addEventListener('n8n-chat-ready', (event) => {
    console.log('N8n chat is ready!', event.detail.chat);
});

// Open the chat window programmatically
window.openN8nChat();

// Close the chat window
window.closeN8nChat();

// Toggle the chat window open/closed
window.toggleN8nChat();

// Send a message programmatically
window.sendN8nMessage('Hello, I need help with my order #12345');

// Example: Open chat when user clicks a help button
document.getElementById('help-button').addEventListener('click', () => {
    window.openN8nChat();
    window.sendN8nMessage('I clicked the help button');
});
```

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

### Register Filament N8n Chat Plugin in Filament Panel

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Registers the FilamentN8nChatPlugin within your Filament panel configuration. This code snippet shows how to add the plugin to your `AdminPanelProvider` to make the chat widget available in your admin application.

```php
// app/Providers/Filament/AdminPanelProvider.php
<?php

namespace App\Providers\Filament;

use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;
use Filament\Panel;
use Filament\PanelProvider;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->default()
            ->id('admin')
            ->path('admin')
            ->plugins([
                FilamentN8nChatPlugin::make(),
            ]);
    }
}
```

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

### Register Filament N8n Chat Plugin in AdminPanelProvider

Source: https://github.com/alkoumi/filament-n8n-chat/blob/main/README.md

Registers the Filament N8n Chat Plugin within your Filament AdminPanelProvider. This method allows for advanced configuration, including setting default language, initial messages, and internationalization (i18n) settings.

```php
// app/Providers/Filament/AdminPanelProvider.php

use AlkoumiFilamentN8nChatFilamentN8nChatPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        // ... other configurations
        ->plugins([
            FilamentN8nChatPlugin::make()
                ->config(function () {
                        $lang = app()->getLocale() ?? 'ar';

                        return [
                            'defaultLanguage' => $lang,
                            'initialMessages' => $lang === 'ar'
                                ? [
                                    'أنا مساعد الذكاء الإصطناعي',
                                    'آمر، كيف أخدمك 💐',
                                ]
                                : [
                                    'Hello! I am your AI assistant',
                                    'How can I help you today?',
                                ],
                            'i18n' => [
                                'en' => [
                                    'title' => 'Hi there! 👋',
                                    'subtitle' => 'I am AI assistant',
                                    'footer' => '',
                                    'getStarted' => 'New Conversation',
                                    'inputPlaceholder' => 'How can I help you today?',
                                ],
                                'ar' => [
                                    'title' => 'مرحبًا بك 💐',
                                    'subtitle' => 'أنا مساعد الذكاء الإصطناعي',
                                    'footer' => '',
                                    'getStarted' => 'محادثة جديدة',
                                    'inputPlaceholder' => 'آمر، كيف أقدر أخدمك 💐',
                                ],
                            ],
                        ];
                    }),
        ]);
}
```

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

### Set n8n Webhook URL via Plugin Configuration

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Configures the n8n webhook URL directly within the plugin's instantiation. This method allows you to override the environment variable or configuration file setting for the webhook URL.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

FilamentN8nChatPlugin::make()
    ->webhookUrl('https://your-n8n-instance.com/webhook/chat-endpoint')
```

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

### Restrict Chat Widget to Specific Panels (PHP)

Source: https://context7.com/alkoumi/filament-n8n-chat/llms.txt

Restricts the chat widget to specific Filament panels when you have multiple panels in your application. This ensures the chat is only accessible in designated areas of your admin interface.

```php
use Alkoumi\FilamentN8nChat\FilamentN8nChatPlugin;

// Show only on admin and support panels
FilamentN8nChatPlugin::make()
    ->panels(['admin', 'support'])

// Dynamic panel selection
FilamentN8nChatPlugin::make()
    ->panels(fn () => auth()->user()?->isSupport() ? ['support'] : ['admin'])
```
Tokens:
Raw