Skip to content

Getting started

  • PHP 8.3 or newer, Laravel 12 or 13, Filament 4 or 5.
  • The aparté chat on your site, with apartejs/laravel 0.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).

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:

Terminal window
composer config repositories.aparte-desk vcs https://github.com/paulrichez-dev/filament-desk
Terminal window
composer require paulrichez/filament-desk

The 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>.

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”.

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.

Terminal window
php artisan vendor:publish --tag=aparte-desk-migrations
Terminal window
php artisan migrate

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());
}

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:

Terminal window
php artisan make:notifications-table

On PostgreSQL, open the new migration and change $table->text('data') to $table->json('data'). Filament needs it. Then:

Terminal window
php artisan migrate

Filament sends these notifications through your queue, so keep a worker running:

Terminal window
php artisan queue:work

That’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:

Terminal window
composer require laravel-notification-channels/webpush
Terminal window
php artisan vendor:publish --provider="NotificationChannels\WebPush\WebPushServiceProvider" --tag="migrations"
Terminal window
php artisan migrate
Terminal window
php artisan webpush:vapid

Add 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());