Requires: Charitable Pro 1.8.16+
Charitable Ambassadors 3.0.0+

When something significant happens in your Ambassadors program, you shouldn’t have to open the dashboard to find out. Charitable Pro’s bell-icon notification panel in the WordPress admin bar is a small inbox for moments that matter.

Now, Ambassadors 3.0 wires four program-specific events to it:

• A growing moderation queue
• A parent campaign’s first fundraiser
• A fundraiser crossing its goal
• Your program reaching a new lifetime milestone

The four events are designed to be rare and meaningful. You should be able to glance at the bell and trust that anything there is worth your attention. No event fires more than once per fundraiser or parent campaign.

The Four Events

Event	Fires when	Bell-icon title
Moderation queue health	Pending count crosses a threshold (default 5) for the first time today.	“5 fundraisers awaiting review”
First fundraiser	The first fundraiser on a parent campaign goes live.	“First fundraiser on [Parent Title]”
Goal reached	A fundraiser crosses 100% of its goal for the first time.	“[Fundraiser Title] reached its goal”
Total raised tier	Site-wide total ambassador-raised crosses a tier threshold ($1K, $5K, $10K, $25K, $50K, $100K, $250K, $500K, $1M).	“Ambassadors program raised $10,000 lifetime”

Each event uses a per-event “latch” stored as post-meta or option, so re-firing doesn’t happen. If a fundraiser dips below its goal (refund) and crosses it again, the latch is cleared and re-armed, so you do get notified again.

Event 1: Moderation Queue Health

Fires when the count of Pending fundraisers crosses a threshold (default 5) for the first time on a given calendar day.

The check is gated on:

• A new fundraiser transitioning to pending (so it doesn’t fire on every page load).
• The pending count being >= threshold.
• The latch for today not yet being set.

The latch is a daily option: _charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>. Once set, no further moderation-queue notifications fire that day.

Override the threshold:

add_filter( 'charitable_ambassadors_notifications_moderation_queue_threshold', function () {
    return 10;  // fire only when 10+ pending
} );

Event 2: First Fundraiser

Fires the first time a parent campaign gets its first published fundraiser, the moment the program “comes alive” for that parent.

Latch: per-parent post-meta _charitable_ambassadors_notif_first_fundraiser_fired. Once set, never re-fires for that parent.

Event 3: Goal Reached

Fires when a fundraiser crosses 100% of its goal for the first time. The check runs at donation-completion time.

Latch: per-fundraiser post-meta _charitable_ambassadors_notif_goal_reached. The latch is cleared if a donation is later refunded and the fundraiser drops below goal, so if it crosses again later, you get notified again.

Event 4: Total Raised Tier

Fires when the site-wide ambassador-raised total crosses a tier threshold. Default tiers:

$1,000  |  $5,000  |  $10,000  |  $25,000  |  $50,000
$100,000  |  $250,000  |  $500,000  |  $1,000,000

Each tier is its own latch (option _charitable_ambassadors_notif_total_raised_tier_<amount>), so crossing $1K, then later $5K, then later $10K all trigger separately.

Customize the tier list:

add_filter( 'charitable_ambassadors_notifications_total_raised_tiers', function () {
    return [ 5000, 25000, 100000, 1000000 ];  // milestones we actually care about
} );

Backfill on Activation

On Ambassadors 3.0 activation, the plugin suppresses historical events by pre-setting every relevant latch. Otherwise on first activation you’d get a flood of “X reached goal” notifications for fundraisers that crossed years ago.

The backfill:

• Stamps _notif_first_fundraiser_fired on every parent that already has at least one published fundraiser.
• Stamps _notif_goal_reached on every fundraiser already at 100%+.
• Stamps the appropriate _notif_total_raised_tier_<amount> for every tier already crossed.

You won’t see any historical notifications, but new events from the moment of activation forward will fire normally.

Tips Worth Keeping in Mind

A few things that will help you get the most out of the notification panel without letting it become noise.

• Leave defaults alone for the first month. They’re tuned to feel rare. Suppress events only if you find one fires too often for your taste.
• The bell-icon is a digest, not a real-time stream. Notifications stay until dismissed; they don’t auto-expire.
• Use the master kill switch in development. No need to see bell-icon updates while iterating on a customization.
• Total raised tiers are a quiet “you’re growing” signal. Often the most rewarding notification, it’s literally a confirmation that the program is working.

Developer Reference

The rest of this page is for developers customizing or extending the Ambassadors notification system.

Master Kill Switch

If the bell-icon notifications aren’t useful for your program, disable them all in one line:

add_filter( 'charitable_ambassadors_notifications_enabled', '__return_false' );

This is global. It suppresses every event the Ambassadors triggers fire. Pro’s own notifications (donation received, etc.) are unaffected.

Per-Event Control

You can suppress individual events without killing the whole feature. Each event has a _should_fire_<event> filter:

add_filter( 'charitable_ambassadors_notifications_should_fire_moderation_queue', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_first_fundraiser', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_goal_reached', '__return_false' );
add_filter( 'charitable_ambassadors_notifications_should_fire_total_raised', '__return_false' );

Each is wrapped in an apply_filters call at trigger time, so returning false short-circuits the notification before it’s posted.

Customizing Event Content

Each event also has an _args_<event> filter that receives the args array before it’s passed to Pro’s notification API. Use this to change the title, link, body, or icon:

add_filter( 'charitable_ambassadors_notifications_args_goal_reached', function ( $args, $fundraiser_id ) {
    $args['title'] = '🎯 ' . $args['title'];
    $args['link']  = get_edit_post_link( $fundraiser_id );  // link to edit instead of view
    return $args;
}, 10, 2 );

Storage

Latch	Key	Scope
Moderation queue (daily)	_charitable_ambassadors_notif_moderation_queue_<YYYY-MM-DD>	option
First fundraiser (per parent)	_charitable_ambassadors_notif_first_fundraiser_fired	post-meta on parent
Goal reached (per fundraiser)	_charitable_ambassadors_notif_goal_reached	post-meta on fundraiser
Total raised tier (per tier)	_charitable_ambassadors_notif_total_raised_tier_<amount>	option

Pro API

Notifications are posted via Pro’s public API:

Charitable_Local_Notifications::add( $args );

The args shape and storage are Pro’s; Ambassadors just calls in.

Gotcha: Charitable_Local_Notifications::add() stores entries as a numerically-indexed list, not an ID-keyed map. If you query the underlying storage directly, treat it as a list.

Filters

Filter	Default	Purpose
charitable_ambassadors_notifications_enabled	true	Master kill switch.
charitable_ambassadors_notifications_should_fire_<event>	true	Per-event suppression.
charitable_ambassadors_notifications_args_<event>	computed	Per-event args modifier.
charitable_ambassadors_notifications_moderation_queue_threshold	5	Pending-count threshold.
charitable_ambassadors_notifications_total_raised_tiers	array of 9	Tier amounts in ascending order.

Actions

Action	Args	Fires when
charitable_ambassadors_notification_fired	$event_slug, $args	A notification was posted to Pro’s bell-icon.
charitable_ambassadors_notification_suppressed	$event_slug, $reason	A notification was suppressed (kill switch, per-event, or latch held).

Triggers Class

Charitable_Ambassadors_Notification_Triggers::get_instance();

Singleton. All event listeners are registered in its __construct(). You can remove_action() specific listeners by reference if you need surgical disabling.

Test-Mode Exclusion

The total-raised tier check excludes donations marked _postmeta('test_mode') = '1'. The exclusion lives in Charitable_Ambassadors_Overview_Data::get_donation_aggregates(), which the notifier reuses.

Capabilities

The bell-icon panel itself is gated by Pro’s standard capability. Ambassadors notifications inherit that gate.

Customization Examples

Common tweaks. Add any of these to your theme’s functions.php or a site-specific plugin.

Replace the “5 fundraisers awaiting review” copy with your team’s language:

add_filter( 'charitable_ambassadors_notifications_args_moderation_queue', function ( $args, $count ) {
    $args['title'] = sprintf( '%d fundraisers need your review (huddle time)', $count );
    return $args;
}, 10, 2 );

Mirror every Ambassadors notification to Slack:

add_action( 'charitable_ambassadors_notification_fired', function ( $event_slug, $args ) {
    wp_remote_post( 'https://hooks.slack.com/...', [
        'body'    => json_encode( [
            'text' => "*{$event_slug}*: " . ( $args['title'] ?? '' ),
        ] ),
        'headers' => [ 'Content-Type' => 'application/json' ],
    ] );
}, 10, 2 );

Reset the “first fundraiser” latch for testing (rerun the notification):

delete_post_meta( $parent_id, '_charitable_ambassadors_notif_first_fundraiser_fired' );
// Now the next published fundraiser on this parent will re-fire the event.

Different tiers for two different sites in a multisite:

add_filter( 'charitable_ambassadors_notifications_total_raised_tiers', function ( $tiers ) {
    if ( is_main_site() ) {
        return [ 25000, 100000, 500000, 1000000 ];
    }
    return [ 1000, 5000, 10000 ];
} );

Wrapping Up

That covers the Ambassadors notification events from how they fire to how to tune them. They work automatically from activation and require no configuration to be useful. If you want to adjust the moderation threshold, change the milestone tiers, or route notifications to Slack, the filters and customization examples above cover all of those cases.

If you have questions about any of the notification events or the Pro notification API, our support team is happy to help.

You May Also Want to Read

These docs cover the features most closely connected to the events that trigger Ambassadors notifications.

• Overview Dashboard – the total-raised tier event uses the Overview data class, and the dashboard is where you’ll see your program-level numbers.
• Moderation – where the moderation queue health notification takes you when the pending count crosses the threshold.
• Email Templates – the sibling transactional-email surface for ambassador-facing notifications.
• Hooks & Filters in Ambassadors – the full filter and action reference for the entire Ambassadors add-on.