Actions Reference

Actions let you run your own code at specific points in the suggestion and notification lifecycle. None of these actions return a value; use filters when you need to change data.

---

Suggestion engine actions

bp_suggestions_before_exclusion_fetch

Fires before the plugin builds the exclusion list (friends already connected, follow targets already followed, dismissed suggestions).

do_action( 'bp_suggestions_before_exclusion_fetch', $user_id, $suggest );

Parameter	Type	Description
$user_id	int	ID of the member receiving suggestions
$suggest	string	Mode: 'friends' or 'follow'

Use this to pre-warm caches or log that a suggestion run has started.

---

bp_suggestions_before_potential_users_query

Fires after exclusions are assembled, just before the plugin fetches the pool of potential matches from get_users().

do_action( 'bp_suggestions_before_potential_users_query', $user_id, $exclude_user, $suggest );

Parameter	Type	Description
$user_id	int	ID of the member receiving suggestions
$exclude_user	array	User IDs that will be excluded from the pool
$suggest	string	Mode: 'friends' or 'follow'

---

bp_suggestions_batch_processed

Fires periodically as the engine scores batches of potential users. Useful for monitoring long-running suggestion runs.

do_action( 'bp_suggestions_batch_processed', $user_id, $processed_count, $batch_size );

Parameter	Type	Description
$user_id	int	Member being scored against
$processed_count	int	Total candidates evaluated so far
$batch_size	int	Configured batch size

---

bp_suggestions_user_matched

Fires each time a candidate clears the percentage threshold and is added to the suggestion list.

do_action( 'bp_suggestions_user_matched', $matched_user_id, $user_id, $match_score, $suggest );

Parameter	Type	Description
$matched_user_id	int	The candidate who passed
$user_id	int	The member receiving the suggestion
$match_score	int	Score (0–100) for this pair
$suggest	string	Mode: 'friends' or 'follow'

---

bp_suggestions_cache_cleared

Fires after bp_suggestions_clear_cache() finishes deleting transients and flushing the object-cache groups.

do_action( 'bp_suggestions_cache_cleared' );

No parameters. Use this to trigger downstream cache invalidation in other plugins.

---

bp_suggestions_database_optimized

Fires after the plugin runs its activation-time database optimization routine.

do_action( 'bp_suggestions_database_optimized' );

No parameters.

---

bp_suggestions_stop_match_due_to_no_overlap

Fires when a required field (marked “stop match” in the admin) has no overlapping values between two users, causing the entire pair to score 0.

do_action( 'bp_suggestions_stop_match_due_to_no_overlap', $field_id, $user_id1, $user_id2 );

Parameter	Type	Description
$field_id	int	xProfile field ID that caused the stop
$user_id1	int	First user
$user_id2	int	Second user

---

bp_suggestions_stop_match_due_to_empty_fields

Same as bp_suggestions_stop_match_due_to_no_overlap but fires when one or both users have no value stored for the required field.

do_action( 'bp_suggestions_stop_match_due_to_empty_fields', $field_id, $user_id1, $user_id2 );

Same parameters as above.

---

bp_suggestions_stop_match_due_to_mismatch

Fires when a required single-value field does not match between two users.

do_action( 'bp_suggestions_stop_match_due_to_mismatch', $field_id, $user_id1, $user_id2 );

Same parameters as above.

---

Template actions

These actions fire inside the built-in layout templates (list-layout.php, horizontal-layout.php, horizontal-slider-layout.php). All three layouts fire the same set of actions, so code hooked here applies to every layout automatically.

Layout wrapper actions

Hook	When it fires
bffs_before_list_layout_wrapper	Before the <ul> in list layout
bffs_after_list_layout_wrapper	After the </ul> in list layout
bffs_before_horizontal_layout_wrapper	Before the outer <div> in horizontal layout
bffs_after_horizontal_layout_wrapper	After the outer </div> in horizontal layout
bffs_before_horizontal_slider_wrapper	Before the Swiper wrapper in slider layout
bffs_after_horizontal_slider_wrapper	After the Swiper wrapper in slider layout

All wrapper actions pass $settings as their only parameter — an array of widget or shortcode settings for the current render.

Member loop actions

Hook	Parameters	When it fires
bffs_before_members_loop	$settings	Before the while ( bp_members() ) loop
bffs_after_members_loop	$settings	After the loop ends
bffs_before_member_item	$member_id, $settings	Before each member’s outer element
bffs_after_member_item	$member_id, $settings	After each member’s outer element
bffs_before_member_avatar	$member_id, $settings	Before the avatar <div>
bffs_after_member_avatar	$member_id, $settings	After the avatar <div>
bffs_before_member_name	$member_id, $settings	Before the member name (slider layout)
bffs_after_member_name	$member_id, $settings	After the member name (horizontal + slider)
bffs_before_member_online_status	$member_id, $settings	Before the online badge (slider layout)
bffs_after_member_online_status	$member_id, $settings	After the online badge (slider layout)
bffs_before_member_buttons	$member_id, $settings	Before friend/follow buttons (slider layout)
bffs_after_member_buttons	$member_id, $settings	After friend/follow buttons (slider layout)
bffs_before_member_actions	$member_id, $settings	Before action buttons section (slider layout)
bffs_after_member_actions	$member_id, $settings	After action buttons section (slider layout)

Example — add a custom badge after every avatar:

add_action( 'bffs_after_member_avatar', function( $member_id, $settings ) {
    if ( get_user_meta( $member_id, 'is_verified', true ) ) {
        echo '<span class="my-verified-badge">Verified</span>';
    }
}, 10, 2 );

---

UX / dismissal actions

bffs_suggestion_dismissed

Fires when a member clicks “Not Interested” on a suggestion card.

do_action( 'bffs_suggestion_dismissed', $user_id, $dismissed_user_id, $reason );

Parameter	Type	Description
$user_id	int	Member who dismissed
$dismissed_user_id	int	Suggestion that was dismissed
$reason	string	'not_interested' or another reason string

---

bffs_auto_dismissed_friend

Fires when a friendship is accepted and the plugin auto-removes both users from each other’s suggestion lists.

do_action( 'bffs_auto_dismissed_friend', $initiator_user_id, $friend_user_id );

---

bffs_auto_dismissed_follow

Fires when a follow relationship is created and the plugin removes the followed member from the viewer’s suggestion list.

do_action( 'bffs_auto_dismissed_follow', $follower_id, $leader_id );

---

bffs_suggestions_refreshed_all

Fires after a site-wide cache clear that refreshes suggestions for all users.

do_action( 'bffs_suggestions_refreshed_all' );

No parameters.

---

bffs_suggestions_refreshed_user

Fires after the cache is cleared for a single user.

do_action( 'bffs_suggestions_refreshed_user', $user_id );

---

Analytics actions

bffs_suggestion_served

Fires when a suggestion is recorded as having been displayed to a user.

do_action( 'bffs_suggestion_served', $user_id, $suggested_user_id );

---

bffs_friend_connection_tracked

Fires when the analytics layer records a new friend connection originating from a suggestion.

do_action( 'bffs_friend_connection_tracked', $user_id, $friend_id );

---

bffs_follow_connection_tracked

Fires when the analytics layer records a new follow originating from a suggestion.

do_action( 'bffs_follow_connection_tracked', $follower_id, $leader_id );

---

bffs_widget_impression_tracked

Fires when the widget or shortcode is rendered and an impression is counted.

do_action( 'bffs_widget_impression_tracked', $user_id );

---

bffs_suggestion_click_tracked

Fires when a member clicks a suggestion card and the click is recorded.

do_action( 'bffs_suggestion_click_tracked', $user_id, $suggested_user_id, $analytics_data );

Parameter	Type	Description
$analytics_data	array	Contextual data stored with the event

---

bffs_suggestion_dismissed_tracked

Fires when a dismissal is recorded in the analytics store.

do_action( 'bffs_suggestion_dismissed_tracked', $user_id, $suggested_user_id, $analytics_data );

---

bffs_analytics_reset

Fires after the analytics data is wiped from the database.

do_action( 'bffs_analytics_reset', $keep_install_date );

Parameter	Type	Description
$keep_install_date	bool	Whether the install date option was preserved

---

Notification actions

bffs_email_templates_installed

Fires after the plugin’s email templates are created in the BuddyPress email post type on activation or upgrade.

do_action( 'bffs_email_templates_installed' );

---

bffs_email_sent

Fires after each individual email is dispatched.

do_action( 'bffs_email_sent', $to, $subject, $sent );

Parameter	Type	Description
$to	string	Recipient email address
$subject	string	Email subject
$sent	bool	Whether wp_mail() returned true

---

bffs_instant_notification_sent

Fires after a new-suggestion instant notification batch completes.

do_action( 'bffs_instant_notification_sent', $user_id, $suggestions, $sent );

Parameter	Type	Description
$suggestions	array	Suggestion user IDs included in the email
$sent	bool	Whether the mail was accepted

---

bffs_daily_digest_sent

Fires after the daily digest job processes all eligible users.

do_action( 'bffs_daily_digest_sent', $users );

Parameter	Type	Description
$users	array	WP_User objects that received the digest

---

bffs_weekly_digest_sent

Fires after the weekly digest job processes all eligible users.

do_action( 'bffs_weekly_digest_sent', $users );

Same signature as bffs_daily_digest_sent.

---

bffs_welcome_email_sent

Fires after a welcome-with-suggestions email is dispatched to a newly registered member.

do_action( 'bffs_welcome_email_sent', $user_id, $suggestions, $sent, $used_bp_email );

Parameter	Type	Description
$used_bp_email	bool	true if the BP Email API was used; false if wp_mail() was used as fallback

---

bffs_hot_matches_checked

Fires after the plugin finishes checking a new registrant’s hot matches.

do_action( 'bffs_hot_matches_checked', $user_id, $notifications_sent );

Parameter	Type	Description
$notifications_sent	int	Number of notifications dispatched

---

bffs_hot_match_notification_sent

Fires each time a hot-match notification is sent to a specific existing member.

do_action( 'bffs_hot_match_notification_sent', $user_id, $match_user_id, $score, $sent );

Parameter	Type	Description
$score	int	Match score (0–100)
$sent	bool	Whether the notification was accepted

---

bffs_settings_after_email_frequency

Fires at the end of the member-facing email-preference form, after the frequency radio group. Use this to add custom preference fields.

do_action( 'bffs_settings_after_email_frequency' );

No parameters. The current user context is available via get_current_user_id().

---

bffs_settings_email_frequency_saved

Fires after a member saves their email frequency preference.

do_action( 'bffs_settings_email_frequency_saved', $user_id, $frequency );

Parameter	Type	Description
$frequency	string	'instant', 'daily', 'weekly', or 'none'

---

Admin actions

bffs_cache_cleared

Fires after the admin manually clears the cache from the dashboard.

do_action( 'bffs_cache_cleared', $cleared );

Parameter	Type	Description
$cleared	bool	Whether cache entries were deleted

---

Logger actions

bffs_log_entry

Fires every time the internal logger records an entry. Useful for routing plugin log output to an external system.

do_action( 'bffs_log_entry', $level, $message, $context );

Parameter	Type	Description
$level	string	Severity: 'debug', 'info', 'warning', 'error'
$message	string	Log message
$context	array	Additional key/value context

---

Cleanup actions

bffs_cleanup_completed

Fires after the scheduled analytics data cleanup runs.

do_action( 'bffs_cleanup_completed', $deleted_count, $retention_days );

Parameter	Type	Description
$deleted_count	int	Rows removed
$retention_days	int	The configured retention window