Appearance
Notifications
Orders, bookings, form messages and failed backups sent to Telegram, Slack or email.
kitloom/notifications · admins: kitloom/notifications-filament, kitloom/notifications-nova
Video lessons
Recorded in the Filament admin; the Nova admin works the same way.
Tells the site's owner what needs them — a comment waiting for approval, a sign-in locked out, and, from the modules that are installed, new orders, bookings, form messages, failed backups — in a Telegram chat, a Slack channel or by email. The admin is kitloom/notifications-filament or kitloom/notifications-nova.
Channels
A channel is one place to send to, with the news it is told:
| Type | What it needs |
|---|---|
| Telegram | A bot's token from @BotFather and the chat: a person who wrote to the bot, or a group the bot was added to (-100…), or a public channel's @name. |
| Slack | An incoming webhook URL: https://hooks.slack.com/services/…. |
| One address or several, separated by commas. |
The token and the webhook URL are kept encrypted with the application key and never shown again: a form left empty there keeps them. A new channel starts with the news worth acting on ticked; the rest is a tick away. Send a test from the channel to see a message arrive.
The Telegram chat need not be looked up: write anything to the bot, or add it to the group, then Find the chat lists the chats that wrote to it — next to the field in Filament, as an action on the saved channel in Nova.
A message is a heading, a few lines about the record and buttons to open it in the admin and on the site. On a site without a public address (localhost, *.test) the links are written out instead of buttons: Telegram refuses those.
A Telegram channel
- In Telegram, open @BotFather, send
/newbot, give the bot a name and a username ending inbot. BotFather answers with the token,123456789:AAE…. - To be told yourself, open the new bot and press Start. For a team, make a group, add the bot to it and write anything there.
- In the admin, Notifications → Channels → New channel: a name, Send to Telegram, the bot token.
- Find the chat next to the Chat field lists the chats that wrote to the bot in the last day; pick yours. (A bot that already sends its updates to a webhook of another service lists none: type the chat's id.)
- Tick the news, save, and Send test.
The bot only sends; it reads nothing the chat writes back.
A Slack channel
- At api.slack.com/apps, Create New App → From scratch, in your workspace.
- Incoming Webhooks: turn them on, Add New Webhook to Workspace, choose the channel. Slack shows the webhook URL,
https://hooks.slack.com/services/…. - In the admin, Notifications → Channels → New channel: a name, Send to Slack, the webhook URL; tick the news, save, and Send test.
A Slack Workflow's webhook is not one: it takes its own variables, not a message.
The news
| Group | Topic | Ticked on a new channel |
|---|---|---|
| Comments | comment.held — a comment waits for approval | yes |
| Security | user.locked_out — too many wrong passwords for a login | no |
| Security | user.role_raised — a user got a role that may do more | no |
| Security | module.switched — a module was switched on or off | no |
Other modules add theirs, each behind kitloom-<module>.notifications.register:
| Module | Topic | Ticked on a new channel |
|---|---|---|
| Shop | order.new — an order to fulfil, when the shop's "New order" email goes | yes |
| Shop | order.cancelled — an order on hold or in processing was cancelled | yes |
| Shop | order.failed — the payment of a waiting order failed | no |
| Shop | order.refunded — money went back, in full or in part | yes |
| Shop | product.low_stock — a product reached its low stock threshold or ran out | yes |
| Shop | product.backordered — sold past the stock, on backorder | no |
| Shop | customer.new — a customer created an account | no |
| Shop | product_review.held — a product review waits for approval | yes |
| Bookings | booking.requested — a new booking, saying whether it waits for confirmation | yes |
| Bookings | booking.cancelled — the client cancelled | yes |
| Listings | enquiry.received — a visitor asked about a listing | yes |
| Courses | course.enrolled — a student got a course | no |
| Courses | course_review.held — a course review waits for approval | yes |
| Contact forms | form.message — a message got through a form | yes |
| Privacy | privacy.confirmed — a request for personal data to answer, with the date | yes |
| Site Health | health.failed — a check fails or warns | yes |
| Backup | backup.failed — a backup or its cleanup failed | yes |
| Link checks | links.broken — links broke since the day before | no |
| Sign In As | user.impersonated — an admin signed in as another user | no |
The channel form lists the topics of the modules that are installed. The form offers a user only the news they could see themselves — a shop manager does not send failed backups to a chat — and leaves a channel's other topics as whoever ticked them chose.
Settings
Notifications → Settings:
- Tell repeats once in, minutes (60) — news that repeats, as a product's low stock or a failing check, reaches a channel once in this time. A new order is never held back.
- Send the record's details (on) — off sends only the heading and the links, so no customer's name lands in a chat that others read.
- Turn a channel off after failures (5) — a channel that fails this many times in a row is turned off and the site's admin is emailed.
Messages are sent from the queue and spoken in the site's language. The module keeps no copy of them: what was sent is in the chat, and deleted there.
AI agents and Site Health
With kitloom/ai, an agent of a user who may manage notifications lists the channels (notifications_list), changes their name, topics and on or off (notifications_update — "stop telling the shop chat about reviews") and sends a test (notifications_test). It never sees a token or a webhook URL, and it makes no channel: that, and where a channel sends, stay in the admin. describe_site lists the topics.
With kitloom/health, Site Health warns while a channel is turned off after failing too often (Notification channels).
For developers
A module tells the owner its own news with a Kitloom\WpSchema\Contracts\NotificationTopic tagged NotificationTopic::TAG (see AGENTS.md, "A notification for the site's owner"):
php
$this->app->tag([ReviewHeld::class], NotificationTopic::TAG);notice($event) returns a Kitloom\WpSchema\Notifications\Notice — a title, label => value lines, the record for the admin link, the page's address, a level and a key repeats share. Without this module nothing reads the tag.
| What | Where |
|---|---|
| Channels | table notification_channels (the site's table prefix in front), model Kitloom\Notifications\Models\NotificationChannel through the ModelRegistry |
| Writing channels | Kitloom\Notifications\Notifications — create(), update(), test(), telegramChats(), with the acting user |
| Sending | Laravel's notifications: one SiteNotice per channel from the SendNotice job, so NotificationSent and NotificationFailed are heard as usual |
| Configuration | config/kitloom-notifications.php — the queue, the tries, the cache store of the repeats, the module's own topics, the agents' tools, the Site Health check, the admin sections |
Tests
From the application that installs the package: php vendor/bin/phpunit --testsuite Notifications.