Filament Chatbot Laravel Package

Getting Started

darkclow4/filament-chatbot is a Filament plugin that drops a floating chat widget into a panel. The v1.0.2 release is a small ergonomics win — the trigger button is now draggable — and does not change the install path.

1. Install and register.

   composer require darkclow4/filament-chatbot
   

   Register the plugin on the panel(s) that should show the widget:

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

2. Publish configuration and set credentials.

   php artisan vendor:publish --tag="filament-chatbot-config"
   

   Put the provider key/endpoint in .env rather than the published config file, and confirm the exact key names against the package README — this package has a thin changelog, so the config surface is the source of truth.

3. Where to look first. The published config/filament-chatbot.php (provider, model, system prompt, button placement) and the ChatbotPlugin class (visibility, panel scoping). Those two files cover ~90% of day-to-day tweaking.

4. First use case. A support/onboarding assistant on an internal admin panel: register the plugin on the admin panel only, seed the system prompt with your domain context, and ship. Expect to spend the first hour on configuration, not code.

Implementation Patterns

Panel-scoped deployment. Register the plugin selectively rather than globally — admin panel gets the bot, customer-facing panels don't. This is the cheapest way to control who sees it and what it costs to run.

Conditional visibility. Gate the widget behind an authorization callback or a role check so it isn't rendered for users who shouldn't use it. Prefer this over CSS hiding; a hidden-but-mounted Livewire component still costs a render and can still talk to your provider endpoint.

Trigger button customization. Icon, label, color, and corner placement are typically config-driven. Keep placement in config and let the new drag behavior handle per-user overrides — don't fight the drag with hardcoded CSS bottom/right values, they'll conflict.

Draggable trigger (v1.0.2). Treat this as a user preference, not a layout feature:

• Persist the position client-side (the package likely stores it in localStorage; verify) so it survives navigation between Filament pages.
• If you need per-user persistence across devices, mirror it into a user column and re-apply it on mount — this is the natural extension point.
• Provide an obvious way to reset the position (or reset on panel layout change); a button dragged into a corner on a 4K monitor is invisible on a laptop.

Branding and prompt injection. Set the assistant name, avatar, greeting, and system prompt from config or a service provider so environment-specific context (staging vs production data) doesn't leak into the prompt. If the package exposes a hook for building the message payload, use it to append tenant or user context server-side — never trust client-supplied context.

Testing. Widgets like this are Livewire components; the highest-value tests are (a) the plugin renders when authorized and not when it isn't, and (b) your payload-building hook produces the expected system prompt. Mock the provider HTTP call with Http::fake() so tests don't burn tokens or hit the network.

Gotchas and Tips

Drag vs. click is the big one. A draggable trigger must distinguish a tap from a drag; if the threshold is loose, every reposition also opens the panel (or vice versa — click never fires because a 1px move registers as a drag). Test on a trackpad and a touch device before rolling out. If it's user-toggleable, expose a config flag to disable dragging entirely.

Position clamping and viewport changes. Pixel-based saved positions break on window resize, mobile orientation change, and Filament's collapsible sidebar shifting the layout. Clamp the saved coordinates to the current viewport on mount, and re-clamp on resize. Mobile is where this surfaces first.

z-index and stacking context. A fixed floating button fighting Filament modals, slide-overs, and notification toasts is a classic. Check the button against filament::modal, action modals, and the notification stack specifically — the drag feature doesn't change this, but it's the most likely thing you'll need to override with custom CSS.

Asset publishing after upgrade. Filament plugins usually need a re-publish or asset rebuild after a version bump: php artisan filament:assets and/or php artisan vendor:publish --force for the JS/CSS. If the drag simply "doesn't work" after updating to 1.0.2, a stale published asset is the first suspect — clear it, hard-refresh the browser, then debug.

Config and view caches. php artisan config:clear and php artisan view:clear after any config edit, especially in deployment pipelines where config:cache runs. Silent config changes are the most common "the plugin ignores my settings" cause.

Never expose the provider key client-side. All LLM calls must round-trip through your Laravel app. If the published config file contains a key field, move it to .env and confirm it isn't serialized into the panel's frontend payload.

Cost and abuse controls. Add rate limiting per user and a max-token/turn cap at the application layer. A public-facing chatbot with an unmetered provider key is a billing incident waiting to happen; the package will not do this for you.

Version pinning. The changelog here is terse (v1.0.2's note is one line), so pin ^1.0 and read the diff — not just the release note — before upgrading minor versions in production.

Extension points beat forks. Before editing vendor code, check for a published view, a config-driven prompt hook, and a plugin-level ->using()/callback-style setter. Filament plugins typically offer at least one of these, and forking guarantees you'll re-solve this on the next release.