Filament Ai Chatbot Laravel Package

Getting Started

Start with the package README and published config file, then confirm the plugin registration pattern for your Filament version. For v1.0.0 the first practical use case is adding an AI assistant to an admin or support panel so staff can ask questions without leaving Filament.

Minimal path:

1. Require the package with Composer and publish its config/assets as documented.
2. Set the Asyntai widget ID(s) in .env / config/asyntai.php, keeping separate IDs per environment and per panel where needed.
3. Register the plugin in each Filament panel provider where the assistant should appear.
4. Configure user context and visibility rules before enabling it broadly.
5. For public pages, add the provided Blade component to the relevant layout or page.

Typical panel registration shape:

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugin(
            AsyntaiPlugin::make()
                ->widgetId(config('asyntai.widgets.admin'))
                ->userContext(fn ($user) => [
                    'id' => $user?->id,
                    'name' => $user?->name,
                    'role' => $user?->getRoleNames()->first(),
                ])
                ->visible(fn () => auth()->user()?->can('use-asyntai'))
        );
}

Check the exact plugin class, method names, and Blade component tag in the package README; v1.0.0 is the first release, so the README is the source of truth.

Implementation Patterns

Use one widget ID per panel. In multi-panel apps, give admin, staff, and customer panels distinct Asyntai widget IDs. Keep them in config rather than hardcoding them in panel providers:

// config/asyntai.php
'widgets' => [
    'admin' => env('ASYNTai_ADMIN_WIDGET_ID'),
    'support' => env('ASYNTai_SUPPORT_WIDGET_ID'),
    'public' => env('ASYNTai_PUBLIC_WIDGET_ID'),
],

Then register each panel with its own ID and visibility rule. This prevents a customer-facing assistant from appearing in an internal panel, or vice versa.

Treat user context as a deliberate contract. Pass only what the assistant needs: stable user ID, display name, role, tenant/team ID, locale, or plan. Avoid dumping the entire user model, request payloads, tokens, or sensitive customer data. Use null-safe closures because guests may hit public pages:

->userContext(fn ($user) => $user ? [
    'id' => $user->id,
    'name' => $user->name,
    'role' => $user->getRoleNames()->first(),
    'tenant' => $user->tenant_id,
] : [])

Use visibility rules for rollout, not authorization. Combine auth checks, roles, feature flags, and environment checks:

->visible(fn () => app()->isProduction()
    ? auth()->user()?->can('use-asyntai')
    : auth()->check())

Still enforce real permissions in policies and controllers. The widget visibility is a UI convenience.

Public pages need route-level placement. Put the Blade component only on pages where public chat is intended, such as a help center or marketing contact page. If the package exposes a component tag, keep it in a shared layout partial so you can enable/disable it per route or config flag.

Share context builders. If several panels need similar context, extract a small resolver class or closure factory. That keeps role/tenant logic consistent and makes later changes easier.

Test as a Filament panel feature. Add a smoke test that boots the relevant panel and asserts the assistant is present or absent according to visibility rules. This catches provider registration mistakes and panel-specific ID mix-ups early.

Gotchas and Tips

• v1.0.0 is a first release. Pin the version in production, read the README carefully, and avoid assuming extension APIs exist beyond documented widget IDs, user context, visibility, and the Blade component.
• Filament 3, 4, and 5 are not identical. The package claims support across all three, but panel provider APIs and asset behavior can differ. Smoke-test on the exact Filament major/minor version you run.
• Widget IDs are easy to mix up. A wrong ID can silently connect a panel to the wrong assistant. Keep IDs in env/config and verify each panel in staging.
• User context may leave your app. Assume anything passed into the assistant is visible to the AI provider and possibly logs. Do not include secrets, API tokens, full addresses, or unnecessary PII.
• Visibility callbacks run during rendering. Make them cheap and null-safe. Avoid database-heavy checks in the callback unless cached.
• Do not rely on visibility for security. Public Blade components can be discovered and abused. Add rate limiting, bot protection, and server-side authorization where applicable.
• Clear caches after config changes. Run php artisan config:clear locally and ensure config:cache is rebuilt during deployment. Filament/panel caches may also need clearing if the widget does not appear.
• Debug by checking registration first. If the assistant is missing, confirm the plugin is registered on that panel, the widget ID is present, the visibility rule returns true, and the rendered HTML contains the component. Then check browser network requests and application logs.
• Keep public and internal IDs separate. Use distinct Asyntai widget IDs for public pages and authenticated panels, even if they point to similar assistants. This limits blast radius and simplifies rollout.
• Extension points are likely limited in v1.0.0. Prefer wrapping the Blade component in your own layout partial over editing vendor files. If deeper customization is needed, document it as a package gap rather than patching vendor code.