README

Real-time customer support chat plugin for FilamentPHP v5 and Livewire v4.

FilaChat adds a complete chat experience to Filament panels with role-aware conversations, attachment uploads, realtime updates (broadcast or polling), and maintenance tools for conversation cleanup.

Features

Filament-native chat page and components
Role-aware chat mode (agent <-> user) or open chat mode for everyone
Realtime support with broadcast mode and polling fallback
Attachment uploads with file type and size rules
Attachment preview modal with metadata and download support
Conversation completion workflow with send lock behavior
Permanent conversation deletion with attachment cleanup
Artisan maintenance commands for completed and stale conversations
Sidebar navigation customization from config or plugin fluent API

Important

FilaChat has two role modes:

With role restrictions enabled, agents cannot chat with agents, and users cannot chat with users.
With role restrictions disabled, all users can chat with each other.

Requirements

Dependency	Version
PHP	`^8.2`
Laravel	`^11.0` or `^12.0`
FilamentPHP	`^5.0`
Livewire	`^4.0`

Installation

Install the package:

composer require hamoi1/filachat

Publish package files (migrations, config, and resources as needed):

php artisan filachat:install

Generate Filament assets:

php artisan filament:assets

You can review all options in config/filachat.php.

Local Asset Build (Tailwind v4)

If you are developing this package locally:

npm install
npm run build

Watch mode:

npm run dev

Note

Tailwind v4 requires a modern Node.js runtime. Node.js 20+ is recommended.

Setup

1. Apply the Trait

Add the HasFilaChat trait to your user model (and your agent model if different):

<?php

namespace App\Models;

use Hamoi1\FilaChat\Traits\HasFilaChat;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasFilaChat;
}

2. Create Agents (Optional)

If you use role restrictions, create agent records:

php artisan filachat:agent-create

3. Add Plugin Paths To Your Theme

FilaChat styles/components must be included in your panel theme build.

If your app uses a tailwind.config.js content array:

content: [
    // ...
    './vendor/hamoi1/filachat/resources/views/**/*.blade.php',
    './vendor/hamoi1/filachat/src/Livewire/**/*.php',
    './vendor/hamoi1/filachat/src/Pages/**/*.php',
    // ...
]

If your app uses Tailwind v4 CSS-first setup, add @source directives in your panel stylesheet:

@source "../../vendor/hamoi1/filachat/resources/views/**/*.blade.php";
@source "../../vendor/hamoi1/filachat/src/Livewire/**/*.php";
@source "../../vendor/hamoi1/filachat/src/Pages/**/*.php";

4. Register the Plugin

Add FilaChat to your panel provider:

<?php

namespace App\Providers\Filament;

use Filament\Panel;
use Filament\PanelProvider;
use Hamoi1\FilaChat\FilaChatPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            // ...
            ->plugins([
                FilaChatPlugin::make(),
            ]);
    }
}

5. Customize Navigation (Optional)

You can customize sidebar behavior directly in the plugin registration:

->plugins([
    FilaChatPlugin::make()
        ->slug('chat')
        ->navigationLabel('Live Chat')
        ->navigationIcon('heroicon-o-chat-bubble-left-right')
        ->navigationSort(10)
        ->showInMenu(true)
        ->navigationDisplayUnreadMessagesCount(true),
]);

The same values can also be controlled from config/filachat.php.

6. Advanced Plugin Configuration (Optional)

FilaChatPlugin supports a full fluent parameter API (values or closures) so you can configure behavior per panel at runtime:

<?php

namespace App\Providers\Filament;

use Filament\Panel;
use Filament\PanelProvider;
use Filament\Support\Enums\Width;
use Hamoi1\FilaChat\FilaChatPlugin;

class AdminPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->plugins([
                FilaChatPlugin::make()
                    ->slug(fn (): string => 'chat')
                    ->navigationLabel(fn (): string => __('Support Chat'))
                    ->navigationIcon('heroicon-o-chat-bubble-left-right')
                    ->navigationSort(10)
                    ->showInMenu(true)
                    ->navigationDisplayUnreadMessagesCount(true)
                    ->realtimeMode('broadcast')
                    ->realtimePollInterval(5)
                    ->enableRoles(true)
                    ->timezone(config('app.timezone'))
                    ->maxContentWidth(Width::Full)
                    ->maxFileSize(12288)
                    ->disk('public')
                    ->userModel(\App\Models\User::class)
                    ->agentModel(\App\Models\User::class)
                    ->senderNameColumn('name')
                    ->receiverNameColumn('name'),
            ]);
    }
}

Available fluent methods:

slug()
navigationLabel()
navigationIcon()
navigationSort()
showInMenu()
navigationDisplayUnreadMessagesCount()
realtimeMode()
realtimePollInterval()
enableRoles()
timezone()
maxContentWidth()
maxFileSize()
disk()
userModel()
agentModel()
senderNameColumn()
receiverNameColumn()

7. Configure Realtime Mode

Important

FilaChat works with Laravel Reverb (or another broadcast driver), and also supports polling mode.

Run Reverb in local development if you use broadcast mode:

php artisan reverb:start

Set realtime behavior in config/filachat.php:

'realtime_mode' => 'broadcast', // 'broadcast' or 'poll'
'realtime_poll_interval' => 5,  // seconds

broadcast: Uses event broadcasting for chat updates.
poll: Uses Livewire polling for updates.

Configuration Highlights

Commonly used options in config/filachat.php:

enable_roles - Enable or disable role restrictions
show_in_menu - Show or hide the sidebar item
navigation_label - Sidebar/page title text
navigation_icon - Sidebar icon
navigation_sort - Sidebar sorting order
navigation_display_unread_messages_count - Show unread badge in sidebar
slug - Route slug for the page
realtime_mode - broadcast or poll
realtime_poll_interval - Poll interval in seconds
disk, mime_types, max_file_size, max_files - Upload behavior
max_content_width - Filament page width
timezone - Chat timestamp timezone

Conversation Lifecycle

FilaChat supports a full conversation lifecycle:

Either participant can mark a conversation as completed.
After a participant completes, that participant can no longer send new messages in that conversation.
When both participants complete, the conversation is fully completed.
Completed conversations can be deleted from the chat header.

Note

Conversation deletion is permanent. All related messages and uploaded attachments are removed.

Maintenance Commands

Use Artisan commands to clean up old chat data.

All cleanup commands run deletion in database transactions. If an exception occurs, the command exits with failure status and prints an error message.

Delete Completed Conversations

Delete conversations completed by both participants, including related messages and attachments:

php artisan filachat:delete-completed-conversations

Skip confirmation:

php artisan filachat:delete-completed-conversations --force

Exit codes:

0 success
1 failure

Delete Stale Conversations

Delete conversations not updated for a given number of days (default: 1), including related messages and attachments:

php artisan filachat:delete-stale-conversations

Custom threshold:

php artisan filachat:delete-stale-conversations --days=7

Skip confirmation:

php artisan filachat:delete-stale-conversations --days=7 --force

Exit codes:

0 success
1 failure

File Uploads

Livewire defaults to 12 MB max file size. To increase it:

Publish Livewire config:

php artisan livewire:publish --config

Update upload rules in config/livewire.php:

'temporary_file_upload' => [
    'rules' => 'max:20000', // 20 MB
],

Update php.ini:

post_max_size = 20M
upload_max_filesize = 20M

Also review package upload options in config/filachat.php:

mime_types
max_file_size
min_file_size
max_files
min_files
disk

Localization

Translation files are located at:

resources/lang/{locale}/filachat.php

Supported Languages

Language	Locale
English	`en`
Arabic	`ar`

Add A New Language

Create resources/lang/{locale}/filachat.php
Copy the structure from resources/lang/en/filachat.php
Translate all values

Publish translations for customization:

php artisan vendor:publish --tag=filachat-translations

Testing

composer test

Changelog

See CHANGELOG for recent changes.

Contributing

See CONTRIBUTING.

Security Vulnerabilities

Please review our security policy to report vulnerabilities.

Credits

Jay-Are Ocero - Original Author
Muhammad Esmail - Developer
All Contributors

License

The MIT License (MIT). See LICENSE.md for details.

hamoi1 / filachat

Maintainers

Package info

Fund package maintenance!

Statistics

Security