Getting Started with Echo Notifications in MediaWiki

Imagine you just saved a page on your wiki and, a few minutes later, a tiny banner pops up saying “John mentioned you on Quantum Mechanics”. That is Echo in action – a notification system baked into MediaWiki that talks to users the way a friendly colleague would. It isn’t just a “nice‑to‑have” add‑on; it’s the glue that keeps editors aware of mentions, watchlist changes, and email digests without hunting through Special:RecentChanges.

Getting the Extension onto Your Wiki

First things first: Echo isn’t part of the core until MediaWiki 1.44, and even then you still need the extension for the UI. Grab it from the Extension Distributor or clone the repo:

git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/Echo.git
cd Echo
composer install

Drop the Echo folder into your extensions/ directory, then add a single line to LocalSettings.php:

wfLoadExtension( 'Echo' ); // Enables the notification framework

That’s it – the extension is now registered. You’ll see a new “Notifications” entry under “Special pages” after you reload.

Quick‑fire Configuration

Most wikis run fine with the defaults, but a few knobs are worth turning. Below is a cheat‑sheet you can paste into LocalSettings.php and tweak later.

# Show email notifications for watchlist changes
$wgEchoWatchlistEmailOncePerPage = true;

# Limit how many mentions are bundled in a single email
$wgEchoBundleEmailInterval = 3600; // one hour

# Enable push notifications (mobile apps, if you have them)
$wgEchoEnablePush = true;

# Turn off email for “page‑linked” events (optional)
$wgEchoNotificationCategories['page-linked'] = false;

Notice the comment style – it’s not required, but it helps future admins understand why a setting is there. Also, you can toggle each notification category individually; the full list lives in Extension:Echo#Notification categories on MediaWiki.org.

What about the “Mention” feature?

If you want users to be pinged whenever someone types @username in an edit summary or comment, enable it like this:

$wgEchoMentionOnChanges = true; // activates @‑mentions in edit summaries

It’s a tiny change, but it makes a big difference in collaborative environments.

Peeking Inside the Architecture (no PhD required)

Echo is essentially a job queue plus a tiny UI. When an event occurs – say, a page is edited – a hook fires, an echo_event row is written to the database, and a background job decides who should see the notification. The UI pulls from echo_notification and renders a list on Special:Notifications. If you’re curious, the tables are:

• echo_event – raw events (who, what, when)
• echo_notification – per‑user rows that are displayed
• echo_subscription – user preferences for each category

Knowing this helps when you need to troubleshoot “why isn’t my mention showing up?” – look at echo_event first, then see if a row exists in echo_notification for the target user.

Setting Up User Preferences

By default, users can manage their notifications from Special:Preferences → Notifications. You can hide the whole tab for certain groups if you prefer a leaner UI:

# Hide the notification tab for anonymous users
$wgGroupPermissions['*']['viewnotifications'] = false;

Or, if you want to push a custom “email‑only” category, add a new entry to $wgEchoNotificationCategories and then expose it via Special:Preferences. The extension’s manual has a full example of adding a my-custom-event type.

A quick note on “negative lists”

Some wikis run a “do‑not‑notify” list for bots or low‑traffic pages. It’s not a hard rule, but you can implement it with a hook:

$wgHooks['EchoGetNotificationTypes'][] = function ( $user, &$types ) {
    if ( $user->isBot() ) {
        $types = []; // no notifications for bots
    }
    return true;
};

This snippet is deliberately simple; you might want to check page titles or namespaces as well.

Testing the System – without breaking a sweat

After you’ve saved the config, try a manual test. Open two browser windows, log in as UserA and UserB. Have UserA edit a page and include @UserB in the edit summary. Then, look at the “Notifications” tab for UserB. If a banner appears, you’re golden.

Sometimes the job queue is slow (especially on shared hosts). You can force immediate processing with:

php maintenance/runJobs.php --type=echoEmail

Don’t run this on a production server during peak hours – it can hog CPU.

Common Gotchas (and how I’ve tripped over them)

• Cache issues: Echo caches unread counts. If you change a setting, clear the cache with php maintenance/rebuildLocalisationCache.php or simply add ?refresh=1 to the URL.
• Database schema mismatches: After a MediaWiki upgrade, run php maintenance/update.php to ensure the Echo tables are up‑to‑date.
• Email delivery: Echo respects $wgEnableEmail. If you see no emails, double‑check your wgSMTP config.

Going a Step Further: Custom Events

If you’re developing another extension – say, a “Poll” module – you can fire Echo notifications directly:

use EchoEvent;
$event = new EchoEvent( [
    'type' => 'poll-created',
    'title' => $title,
    'extra' => [ 'question' => $question ],
] );
$event->notify(); // pushes to all subscribers

Remember to register the new type in $wgEchoNotificationCategories and add a UI message like echo-notification-poll-created in your i18n file.

Performance Tips for Busy Wikis

Large wikis can generate thousands of events per minute. A few practical tricks:

1. Enable the job queue ($wgJobRunRate) so notifications are processed asynchronously.
2. Limit per‑user subscriptions with $wgEchoPushMaxSubscriptionsPerUser – prevents a single user from overloading the push service.
3. Turn on email batching ($wgEchoEnableEmailBatch) to avoid flooding inboxes.

These settings are optional but often the difference between “smooth” and “slow as molasses”.

Wrapping Up – a few final thoughts

Echo is not a magic wand; it’s a framework that needs a little shepherding. Once you have the basics down – install, enable, tweak a few preferences – you’ll see editors respond to the gentle nudges that keep the community humming. The beauty is that you can stop at the default configuration, or you can dive deep, craft custom events, and even tie in mobile push notifications.

In short, treat Echo like any other piece of infrastructure: start simple, monitor the logs, and iterate. If you ever feel lost, the official Extension:Echo page has a wealth of examples, and the MediaWiki community on Matrix is surprisingly quick to answer “why isn’t my @‑mention firing?”.

Happy notifying!