Getting started
What you need
Section titled “What you need”- PHP 8.3 or newer, Laravel 12 or 13, Filament 4 or 5.
- The aparté chat on your site, with
apartejs/laravel0.14 or newer (Composer installs it with the desk). Its README shows how, in “A person takes over”. - A queue worker, for the notifications (Filament sends them through your queue).
Installation
Section titled “Installation”1. Install the package
Section titled “1. Install the package”The desk is not on Packagist. After your purchase, connect your GitHub account to it on Polar: follow the link in Polar’s e-mail, or open https://polar.sh/paul-richez/portal. GitHub then invites that account to the desk’s private repository: accept the invitation (from GitHub’s e-mail, or at https://github.com/paulrichez-dev/filament-desk), then:
composer config repositories.aparte-desk vcs https://github.com/paulrichez-dev/filament-deskcomposer require paulrichez/filament-deskThe first time, Composer asks for a GitHub token to read a private repository: create one at
https://github.com/settings/tokens (a classic token with the repo scope) and paste it when asked. Composer keeps it
in its auth.json. On a server or in CI, give the same token with composer config github-oauth.github.com <token>.
2. Give the chat its people route
Section titled “2. Give the chat its people route”The desk needs the chat’s “people” route: it tells the chat who holds a conversation, and it brings
the visitor’s messages to the desk while someone does. In routes/web.php:
use Illuminate\Support\Facades\Route;
Route::aparte('/chat', App\Ai\Agents\Support::class);Route::apartePeople('/chat/people');And on the page with the chat, add the people attribute, and the visitor’s Talk to a person button (the desk
hears it):
<x-aparte::chat endpoint="/chat" people="/chat/people" :people-button="true" />For the visitor to see your team’s messages at once, the page needs Laravel Echo (Reverb or Pusher).
The apartejs/laravel README explains it in “A person takes over”.
3. Let the assistant hand over
Section titled “3. Let the assistant hand over”Give your agent the AskForSomeone tool. The assistant then hands a conversation to your team when
the visitor asks for a person, or when it cannot help:
use Aparte\Laravel\Tools\AskForSomeone;
public function tools(): iterable{ return [new AskForSomeone];}The visitor’s chat also shows a Talk to a person button: a click hands the conversation over without
the model. Either way, the visitor then reads “Someone of the team will answer you here, usually within a few minutes”, or,
outside your office hours, when the team is back (“The team is away right now. Someone will answer you
here on Monday at 9:00 AM”). Set the hours in config/aparte-desk.php:
'hours' => ['days' => [1, 2, 3, 4, 5], 'from' => '09:00', 'to' => '18:00', 'timezone' => 'Europe/Paris'],Keep the model’s reasoning out of the visitor’s chat. A support chat shows the answer, not what the model thought on the way, which can name your internal rules or what a tool read. Choose a model that does not reason, or leave the reasoning out of the response, so it never reaches the browser. With OpenRouter, on your agent:
use Laravel\Ai\Contracts\HasProviderOptions;use Laravel\Ai\Enums\Lab;
class Support implements Agent, Conversational, HasProviderOptions, HasTools{ public function providerOptions(Lab|string $provider): array { return ['reasoning' => ['exclude' => true]]; // it still thinks, and sends only the answer }}Say when to hand over, in your own words, if you want: new AskForSomeone(when: 'Use it for refunds and complaints.').
A chat with your team only, no assistant. Leave out endpoint and skip this step: there is no agent and no route
to the model. Every message goes to the desk, and the visitor’s first one puts the conversation in To take, with
that message as its reason; the visitor reads the same notice, with your office hours. The desk says “The visitor
wrote to the team” in the conversation and offers no “Hand back to the assistant”:
<x-aparte::launcher people="/chat/people" label="Questions?" />You can have both on one site: the assistant on one page, the team only on another.
4. Create the desk’s tables
Section titled “4. Create the desk’s tables”php artisan vendor:publish --tag=aparte-desk-migrationsphp artisan migrate5. Add the desk to your panel
Section titled “5. Add the desk to your panel”In your panel provider (for example app/Providers/Filament/AdminPanelProvider.php), add the plugin,
and turn on database notifications:
use Aparte\FilamentDesk\AparteDeskPlugin;
public function panel(Panel $panel): Panel{ return $panel // ... ->databaseNotifications() ->plugin(AparteDeskPlugin::make());}6. Let the desk notify your team
Section titled “6. Let the desk notify your team”The desk sends notifications in the panel: to the team when a conversation waits for someone, and to you when a visitor writes in a conversation you hold. It needs Laravel’s notifications table:
php artisan make:notifications-tableOn PostgreSQL, open the new migration and change $table->text('data') to $table->json('data').
Filament needs it. Then:
php artisan migrateFilament sends these notifications through your queue, so keep a worker running:
php artisan queue:workThat’s it. Open your panel: “Conversations” is in the menu.
An e-mail too? Set 'mail' => true in config/aparte-desk.php: each of them also gets an e-mail
when the assistant hands a conversation over, through your queue and your mail settings. An open desk
also shows what waits for someone in the tab’s title, and plays a short sound when it grows while the tab
is in the background ('sound' => false turns both off). Once a team member clicks Get notified on this computer
in the desk, they also get a notification of the system, in the corner of the screen, while the desk is open in
another tab or window ('browser_notifications' => false turns it off).
Push notifications, even with the desk closed. On a computer or a phone where a team member allowed them, with the desk not open at all:
composer require laravel-notification-channels/webpushphp artisan vendor:publish --provider="NotificationChannels\WebPush\WebPushServiceProvider" --tag="migrations"php artisan migratephp artisan webpush:vapidAdd the HasPushSubscriptions trait (from NotificationChannels\WebPush) to your user model, and set
'web_push' => true in config/aparte-desk.php. The team member clicks Get notified on this computer once, on each
device. Browsers allow push only over HTTPS (and on localhost), and the encryption needs PHP’s GMP or BCMath
extension on the server.
Who is “the team”? Whoever opened the desk in the last 30 days and may still use it. To name it yourself, in a
service provider’s boot():
use Aparte\FilamentDesk\Desk;
Desk::team(fn () => User::query()->where('is_support', true)->get());