Download the PHP package zedmagdy/filament-chat without Composer

Filament Chat

A chat plugin for Filament v4 that supports configurable chat sources, one-to-one and group conversations, text and file attachments (via Spatie Media Library), read/unread tracking, search, and real-time updates via polling or broadcasting (Reverb/Pusher).

Requirements

• PHP ^8.3
• Laravel ^11.0 or ^12.0
• Filament ^4.3.1 or ^5.0
• Spatie Media Library (installed automatically)

Installation

Install via Composer:

Publish and run the migrations:

If you haven't already, publish the Spatie Media Library migration as well:

Optionally publish the config:

Optionally publish the views for customization:

Full Integration Example

1. Add the HasChats trait to your User model

This gives your User model these relationships:

• chatParticipations() - all chat participations
• conversations() - all conversations the user is part of
• sentMessages() - all messages sent by the user

2. Create a Chat Source

The quickest way is with the Artisan command:

This generates two files:

• app/Chat/StaffChatSource.php — the chat source class
• app/Filament/Pages/StaffChatPage.php — the Filament page

Then skip to step 4 to register it.

Manual setup

A chat source defines a category of chat (e.g. staff-to-staff, patient support). Create one class per source:

3. Create a Chat Page

Each chat source needs a thin Filament page class:

That's it. The page inherits its navigation label, icon, group, sort, and slug from the chat source.

4. Register the Plugin in your Panel

5. Multiple Chat Sources

You can register multiple sources for different chat contexts:

Register both in your panel:

6. Aggregate Chat Sources ("All Messages")

An aggregate page presents a single read + reply inbox spanning an explicit set of source keys. It does not support starting new conversations (use the per-source pages for that); each row shows a badge indicating which source the conversation belongs to.

Generate one with the make:chat-aggregate command:

This creates app/Chat/AllMessagesAggregateChatSource.php:

and app/Filament/Pages/AllMessagesChatPage.php:

Register it on the plugin alongside your sources:

The source keys listed in getSourceKeys() must match the getKey() of registered ChatSource classes. Unknown keys are ignored. New-conversation creation is intentionally unavailable on aggregate pages.

7. Creating Conversations from the UI

Users can start new conversations by clicking the + button in the chat sidebar. This opens a modal where they select a participant (or multiple for group chats).

Behavior:

• Direct chats: If a conversation already exists between the two users in the same source, it opens the existing one instead of creating a duplicate.
• Group chats: Only available if allowsGroupChats() returns true. Users provide a group name and select multiple participants.
• Participant list: Filtered by getAvailableParticipantsQuery() — the current user is excluded automatically.

Disabling conversation creation:

Override allowsNewConversations() in your chat source to hide the button:

This is useful for system-managed chats where conversations are created programmatically (e.g. a support ticket system that auto-creates a chat per ticket).

8. Creating Conversations Programmatically

9. Working with Attachments

The Message model uses Spatie Media Library. Attachments are stored in the chat-attachments media collection:

In the UI, the MessageInput Livewire component uses Filament's SpatieMediaLibraryFileUpload for seamless file uploads.

Real-time Updates

Polling (default)

Out of the box, the chat window polls for new messages. Configure the interval in your .env or config:

Broadcasting (Reverb / Pusher)

For real-time updates via WebSockets:

The package broadcasts MessageSent and MessagesRead events on private channels (chat.conversation.{id}). Channel authorization is handled automatically - only conversation participants can listen.

Make sure your Laravel broadcasting is configured (Reverb, Pusher, etc.) and that your frontend includes the Echo setup.

Configuration

Custom Models

You can extend the built-in models and register them in the config:

Events

The package dispatches the following events:

Listen to them in your EventServiceProvider or with Event::listen():

Testing

Changelog

Upgrade note: The internal Livewire components now use a source-keys array prop instead of source-key. If you overrode filament-chat::pages.chat-source or embedded chat-list/chat-window/ chat-search directly, pass :source-keys="$this->getSourceKeys()" instead of :source-key.

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• ZED-Magdy
• All Contributors

License

The MIT License (MIT). Please see License File for more information.