Getting Started with Echo Notifications in MediaWiki

The Notifications extension — historically and in configuration called Echo — provides the in-wiki notification system behind Wikipedia's bell icon: alerts about talk page mentions, reverts of your edits, thanks and other events. It is a stable extension bundled with MediaWiki since 1.40, and it is also the delivery surface for the notifications framework introduced in MediaWiki 1.44 core: the built-in framework lets other code produce notifications, but users still see them through this extension's UI. Thanks and DiscussionTools are two extensions that rely on it.

Installation

Echo ships bundled with MediaWiki 1.40 and later; on older wikis, download it via the Extension Distributor and place it in extensions/Echo. Load it in LocalSettings.php:

wfLoadExtension( 'Echo' );

The extension adds database tables, so run the update script once:

php maintenance/run.php update

Note that the database user needs the REFERENCES privilege for the database (a requirement of the schema change), which some one-click hosting panels grant automatically. After installation, a Notifications tab appears in Special:Preferences, and the bell icon shows up in the interface.

How delivery works

When an event occurs — a page is edited, a user's talk page is written to — a hook fires and the event is written to the echo_event table. Delivery to individual users goes through per-user rows in echo_notification, while mention targets are tracked in echo_target_page (push subscriptions have their own tables, echo_push_subscription and friends). By default notifications are delivered immediately during the request:

// Defer delivery (web + email) to the job queue for large wikis
$wgEchoUseJobQueue = true;

The false default is fine for most wikis; big installations flip it to true and run the job queue for scale.

Email: immediate or batched

Email sending is enabled by default ($wgEchoEnableEmailBatch = true). Users choose the frequency in their preferences; the default preference echo-email-frequency is 0, which emails every notification immediately. To make batched digests actually be delivered, schedule the batching script daily with cron:

php maintenance/run.php Echo:processEchoEmailBatch

Bundling several notifications into one message is configured via $wgEchoBundleEmailInterval (seconds between bundle emails; default 0, which leaves bundling off unless you have delay-queue support). The sender address and name come from $wgNotificationSender and $wgNotificationSenderName — set these explicitly, otherwise emails fall back to $wgPasswordSender.

Notification categories and preferences

All notification types belong to a category, and each category can be enabled or disabled per user for web and email separately (preference keys of the form echo-subscriptions-{web|email}-{category}). To set sensible defaults site-wide instead of per user:

// Default on: web mention alerts for everyone
$wgDefaultUserOptions['echo-subscriptions-web-mention'] = true;

Since MediaWiki 1.42, be aware that conditional user options can override these defaults for recent users — Echo declares its own defaults there, so a false default for new users may not stick the way you expect.

How mentions work

A mention notification is generated when someone links to your user page — but only if the post is signed (~~~~). By default mentioned users are also notified when a comment is edited and re-signed ($wgEchoMentionOnChanges = true), and mentions in edit summaries are governed by a separate setting:

// Notify up to 5 users linked from an edit summary (0 = off, the default)
$wgEchoMaxMentionsInEditSummary = 5;

$wgEchoMaxMentionsCount (default 50) caps how many users one edit can mention at once. Success and failure of mentions can produce their own notifications via $wgEchoMentionStatusNotifications.

Suppressing notification noise

Bots and repeated event sources are the usual noise generators. Echo has a three-level system for blocking them:

• $wgEchoAgentBlacklist — usernames that never trigger notifications (set in LocalSettings.php)
• MediaWiki:Echo-blacklist — an on-wiki list the community can maintain (one username per line)
• Special:MyPage/Echo-whitelist — a per-user list that overrides the blacklists

Debugging notifications

• Nothing arrives — check Special:DisplayNotificationsConfiguration, which shows all local settings, categories and event types
• Database-level checks — look for a row in echo_event, then confirm the target user has a row in echo_notification; a missing target row means the event fired but delivery failed
• Email not sent — verify $wgEnableEmail is true, $wgSMTP works, and that the batch script is being run if you opted into batched digests
• Everything is slow — if $wgEchoUseJobQueue is true, watch job queue lag; on shared hosting, delivery may be deferred for a while

Adding your own notification types

Other extensions can emit notifications directly. The pattern is to create an event and hand it to the notification controller:

$event = EchoEvent::create( [
    'type'  => 'poll-created',
    'title' => $title,
    'extra' => [ 'question' => $question ],
] );

The new type must be registered in $wgEchoNotifications (with a category, bundle settings and a presentation model extending EchoEventPresentationModel), an icon entry in $wgEchoNotificationIcons, and i18n messages for the notification text. The official how-to walks through both approaches.

Wrapping up

Echo/Notifications is one of the lower-maintenance extensions you will run: install it, verify the schema update, set a sender address and a couple of defaults, and the defaults will carry the rest. Where it rewards attention is in the details — mention polluting edit summaries, bot blacklists, and email digest scheduling — because those are the settings that decide whether the bell is helpful or just noise. Start simple, keep an eye on Special:DisplayNotificationsConfiguration, and iterate.