Phabricator project: #Echo


Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png

Release status: stable

Implementation Notify
Description Implements Echo, MediaWiki's next-generation notification subsystem.
Author(s) Andrew Garrett, Ryan Kaldari, Benny Situ
Latest version continuous updates
MediaWiki 1.22+
Database changes Yes
Tables echo_email_batch
License MIT License
Hooks used


Translate the Echo extension if it is available at

Check usage and version matrix; code metrics


Open tasks · Report a bug

The Echo extensions provide a notification subsystem for usage by other extensions, e.g. the Thanks or the Flow extension. See Echo (Notifications) for a full description of what this extension does.

Installing[edit | edit source]

  • Download and place the file(s) in a directory called Echo in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
require_once "$IP/extensions/Echo/Echo.php";

Configuration[edit | edit source]

Configuration settings in Echo.php
parameter default comment
$wgEchoEnableEmailBatch true Whether to turn on email batch function
$wgEchoShowFullNotificationsLink false Show a 'Notifications' link with badge in the user toolbar at the top of the page when enabled. Otherwise show only a badge next to the username.
$wgEchoHelpPage URL for more information about the Echo notification system
$wgEchoFeedbackPage URL for a feedback/survey page
$wgEchoUseJobQueue false
  • true: Defer web and email notification delivery via job queue.
  • false: Deliver notifications immediately
$wgEchoEmailFooterAddress The organization address. Should be defined in LocalSettings.php
$wgNotificationSender $wgPasswordSender The email address for both "from" and "reply to" on email notifications. Should be defined in LocalSettings.php
$wgNotificationSenderName $wgPasswordSenderName Name for "from" on email notifications. Should be defined in LocalSettings.php
$wgNotificationReplyName No Reply Name for "reply to" on email notifications. Should be defined in LocalSettings.php
$wgEchoCluster false Use the main db if this is set to false, to use a specific external db, just use any key defined in $wgExternalServers
$wgEchoMaxNotificationCount 99 The max notification count shown in badge. The max number shown in bundled message, e.g., <user> and 99+ others <action>
$wgEchoMaxUpdateCount 2000 The max number of notifications allowed for a user to do a live update, this is also the number of max notifications allowed for a user to have.
$wgEchoBundleEmailInterval 0 The time interval between each bundle email in seconds set a small number for test wikis. This should be set to 0 to disable email bundling if there is no delay queue support
$wgEchoNewMsgAlert true Whether or not to enable a new talk page message alert for logged in users.
    'all' => array(
        'web' => true,
        'email' => true,
   // Only send web notification for welcome event
    'welcome' => array(
        'email' => false,
    // No need to get a email when another user sends to me
    'emailuser' => array(
        'web' => true,
        'email' => false,
Define which output formats are available for each notification category
    'web' => array( 'EchoNotifier', 'notifyWithNotification' ),
    'email' => array( 'EchoNotifier', 'notifyWithEmail' ),
Definitions of the different types of notification delivery that are possible. Each definition consists of a class name and a function name. See also: EchoNotificationController class.
$wgEchoNotificationCategories See Echo.php Define the categories that notifications can belong to. Categories can be assigned the following parameters. All parameters are optional:
  • priority: Controls the order in which notifications are displayed in preferences and batch emails. Priority ranges from 1 to 10. If the priority is not specified, it defaults to 10, which is the lowest.
  • no-dismiss: disables the dismissability of notifications in the category. It can either be set to an array of output formats (see $wgEchoNotifiers) or an array containing 'all'.
  • usergroups: Specifies an array of usergroups eligible to receive the notifications in the category. If no usergroups parameter is specified, all groups are eligible.

If a notifications type doesn't have a category parameter, it is automatically assigned to the other category which is lowest priority and has no preferences or dismissibility.

$echoIconPath Echo/modules/icons
$wgEchoNotificationIcons See Echo.php Defines icons, which are 30x30 images. This is passed to BeforeCreateEchoEvent so extensions can define their own icons with the same structure. It is recommended that extensions prefix their icon key. An example is myextension-name. This will help avoid namespace conflicts.

You can use either a path or a url, but not both. The value of 'path' is relative to $wgExtensionAssetsPath.

The value of 'url' should be a URL.

You should customize the site icon URL, which is: $wgEchoNotificationIcons['site']['url']

$wgEchoNotifications See Echo.php Define the event types for echo. Event definitions are in the form of 'event-name' => array( ... ).
  • category: Defines the category the event belongs to. Defaults to 'other'.
  • group: Defaults to 'neutral'.
  • bundle: Define which output formats are available for bundling.
  • formatter-class: Define which class is used to format the various notification messages. Defaults to EchoBasicFormatter

The following parameters are specific to EchoBasicFormatter and all formatters which extend from it.

  • title-<message/params>: Required parameter specifying title and title parameters for the Notification page
  • bundle-<message/params>: Title displayed on the flyout
  • email-subject-<message/params>: Bundle title for the archive page and flyout.
  • email-body-<message/params>: Notification email body.
  • email-body-batch-<message/params>: Notifications email body when sent in batch mode.
  • email-body-batch-bundle-<message/params>: Notification body when sent as part of a bundled notification.
  • payload: Notification payload data, E.g., Summary.
  • icon: Notification icon for the event type.
$wgEchoAgentBlacklist array() List of usernames which will not trigger notifications
$wgEchoOnWikiBlacklist Echo-blacklist Page location of community maintained blacklist within NS_MEDIAWIKI containing one username per line which will not trigger notifications. Set to null to disable.
$wgEchoPerUserWhitelistFormat  %s/Echo-whitelist An sprintf format of the location of the per-user notification agent whitelist within the NS_USER namespace. %s will be replaced with the users name. The whitelists must contain one username per line which will always trigger notifications regardless of their existence in the blacklists. Set to null to disable.

Architecture[edit | edit source]

See the architecture section of the feature page.

Usage[edit | edit source]

Notification blacklist/whitelist

There are occasionally specific users, typically bots, which perform maintenance tasks that should not generate notifications. To handle these cases, users can be globally blacklisted from the LocalSettings.php file (or InitialiseSettings.php in the case of WMF wikis):

 $wgEchoAgentBlacklist = array( 'GonzoBot', 'CrazyGuy' );

There is also an on-wiki blacklist that can be maintained by the wiki's community. The location of the global on-wiki blacklist defaults to MediaWiki:Echo-blacklist. Individual users can override the blacklist by creating a whitelist. The whitelist location defaults to Special:MyPage/Echo-whitelist. All on-wiki lists expect to receive one case-specific username per line with no special markup or prefixes. For example:


Terminology[edit | edit source]

  • notification - Any individual notice that is delivered by Echo
  • message - A notification about activity in a Flow discussion
  • alert - Any notification other than a message

See also[edit | edit source]