README

Refineder Filament CRM

A real-time CRM plugin for Filament v5 powered by WhatsApp messaging via WasenderAPI.

Features • Requirements • Installation • Configuration • Usage • Webhook Setup • Customization • Events • Translations • Roadmap • License

Overview

Refineder Filament CRM transforms your Filament admin panel into a full-featured customer relationship management system with real-time WhatsApp messaging. Connect one or more WhatsApp accounts via WasenderAPI, receive customer messages instantly, reply directly from your dashboard, and manage deals through a visual pipeline -- all without leaving Filament.

Features

WhatsApp Integration

• Multi-Session Support -- connect and manage multiple WhatsApp accounts simultaneously
• Real-Time Chat -- WhatsApp-style chat interface with Livewire polling
• All Message Types -- text, images, video, audio, documents, locations, contacts, stickers
• Delivery Receipts -- sent, delivered, and read status indicators
• Media Preview -- inline image previews and media type badges
• Webhook-Driven -- automatic message ingestion from WasenderAPI webhooks

Contact Management

• Auto-Creation -- contacts are created automatically from incoming messages
• Rich Profiles -- name, phone, email, company, notes, custom metadata
• Conversation History -- full message history per contact
• Search & Filter -- find contacts by name, phone, email, or company

Deal Pipeline

• Customizable Stages -- Lead, Qualified, Proposal, Negotiation, Won, Lost (configurable)
• Priority Levels -- Low, Medium, High, Urgent with color-coded badges
• Value Tracking -- monetary values with multi-currency support (USD, EUR, GBP, SAR, AED, EGP)
• Overdue Detection -- visual indicators for deals past their expected close date
• Contact Linking -- associate deals with contacts and conversations

Dashboard Widgets

• CRM Stats -- contacts, unread conversations, open deals, revenue, today's messages
• Recent Conversations -- live-updating table of latest conversations with unread badges

Developer Experience

• Filament v5 Native -- follows the latest resource architecture (Schemas/, Tables/, Pages/)
• Fully Translatable -- ships with English and Arabic; add any language
• Configurable -- toggle features on/off, override models, adjust polling intervals
• Event-Driven -- Laravel events dispatched for messages and session changes
• Encrypted Storage -- all API keys and secrets stored with Laravel's encryption

Requirements

Installation

1. Install the package

composer require refineder/filament-crm

2. Publish and run migrations

php artisan vendor:publish --tag="refineder-crm-migrations"
php artisan migrate

3. Register the plugin in your Panel Provider

use Refineder\FilamentCrm\RefinederCrmPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        // ...
        ->plugin(RefinederCrmPlugin::make());
}

4. (Optional) Publish the configuration file

php artisan vendor:publish --tag="refineder-crm-config"

Configuration

After publishing, the configuration file is located at config/refineder-crm.php.

Feature Toggles

Enable or disable individual CRM modules:

'features' => [
    'contacts'          => true,
    'conversations'     => true,
    'deals'             => true,
    'whatsapp_sessions' => true,
    'widgets'           => true,
],

Plugin Fluent API

You can also configure features directly on the plugin instance:

RefinederCrmPlugin::make()
    ->contacts(true)
    ->conversations(true)
    ->deals(true)
    ->whatsappSessions(true)
    ->widgets(true)
    ->navigationGroup('CRM')
    ->navigationSort(1)

Chat Polling Interval

Control how frequently the chat checks for new messages (in seconds):

'chat_poll_interval' => 5,

Currency

Set the default currency for deal values:

'currency' => 'USD',

Overriding Models

Replace any model with your own implementation:

'models' => [
    'contact'          => \App\Models\MyContact::class,
    'conversation'     => \App\Models\MyConversation::class,
    'message'          => \App\Models\MyMessage::class,
    'deal'             => \App\Models\MyDeal::class,
    'deal_stage'       => \App\Models\MyDealStage::class,
    'whatsapp_session' => \App\Models\MyWhatsappSession::class,
],

Usage

Setting Up a WhatsApp Session

1. Navigate to CRM > WhatsApp Sessions in your Filament panel
2. Click Create and fill in your session details:
   • Session Name -- a friendly label (e.g. "Sales Team")
   • WasenderAPI Session ID -- from your WasenderAPI dashboard
   • API Key -- the unique key for this session
   • Webhook Secret -- for verifying incoming webhooks
3. Save the session -- a Webhook URL will be generated automatically
4. Copy the Webhook URL into your WasenderAPI session settings
5. Use the Connect button to establish the WhatsApp connection

Sending Messages

Once a session is connected, navigate to any conversation and type your reply in the chat box. Press Enter or click the send button. The message is sent via WasenderAPI and stored in your database.

Managing Deals

Navigate to CRM > Deals to create and track deals. Each deal can be linked to a contact and moves through configurable pipeline stages.

Webhook Setup

The plugin registers a webhook endpoint at:

POST {your-domain}/refineder-crm/webhook/{session_id}

WasenderAPI Configuration

1. Open your session in the WasenderAPI dashboard
2. Set the Webhook URL to the URL shown in your session's edit page
3. Set the Webhook Secret to match the secret stored in the plugin
4. Enable the following events:
   • messages.received
   • messages.upsert
   • message.sent
   • messages.update
   • messages.delete
   • session.status

Webhook Verification

Every incoming request is verified by comparing the X-Webhook-Signature header against the stored webhook secret. If no secret is configured, all requests are accepted.

Supported Events

Customization

Extending Resources

All Filament resources follow the v5 pattern with separate Schemas/, Tables/, and Pages/ directories. You can extend any resource by publishing and modifying the files.

Custom Navigation Group

RefinederCrmPlugin::make()
    ->navigationGroup('My Custom CRM')

Disabling Specific Features

RefinederCrmPlugin::make()
    ->deals(false)         // hide the Deals resource
    ->widgets(false)       // remove dashboard widgets

Events

The plugin dispatches Laravel events that you can listen for in your application:

Example Listener

use Refineder\FilamentCrm\Events\MessageReceived;

class NotifyTeamOnNewMessage
{
    public function handle(MessageReceived $event): void
    {
        $message = $event->message;
        $contact = $message->conversation->contact;

        // Send a notification to your team
        Notification::route('slack', config('services.slack.webhook'))
            ->notify(new NewWhatsAppMessage($contact, $message));
    }
}

Translations

The plugin ships with full English and Arabic translations. To add a new language, publish the translations and create a new directory:

php artisan vendor:publish --tag="refineder-crm-translations"

Translation files are located in resources/lang/vendor/refineder-crm/:

lang/vendor/refineder-crm/
├── en/
│   ├── chat.php
│   ├── contacts.php
│   ├── conversations.php
│   ├── deals.php
│   ├── messages.php
│   ├── sessions.php
│   └── widgets.php
└── ar/
    └── ...

Database Schema

The plugin creates the following tables (all prefixed with crm_):

Security

• Encrypted at Rest -- API keys, personal access tokens, and webhook secrets are stored using Laravel's encrypted cast
• Webhook Signature Verification -- every webhook request is validated via X-Webhook-Signature
• CSRF Protection -- webhook routes are exempt from CSRF (required for external POSTs) but protected by signature verification
• Tenant Isolation -- all queries are scoped by user_id to prevent cross-user data access

Roadmap

Planned features for future releases:

• Broadcasting -- real-time updates via Laravel Reverb / Echo
• AI Auto-Replies -- GPT-powered automatic responses
• Chatbot Builder -- visual flow-based conversation automation
• Message Templates -- WhatsApp business template management
• Bulk Messaging -- campaign broadcasting to contact lists
• Kanban Board -- drag-and-drop deal pipeline view
• Team Assignment -- assign conversations to team members
• SLA Tracking -- response time monitoring and alerts
• Advanced Analytics -- charts, reports, and conversion metrics
• Custom Fields -- dynamic fields for contacts and deals
• REST API -- headless API for external integrations

Testing

composer test

Changelog

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

Contributing

Contributions are welcome! Please see CONTRIBUTING for details.

License

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

Built with care by Refineder • Powered by Filament • WhatsApp via WasenderAPI