Using WordPress ‘heartbeat_received’ PHP filter

The heartbeat_received WordPress PHP Filter allows you to modify the Heartbeat API response data in real-time.

Usage

add_filter( 'heartbeat_received', 'your_custom_function', 10, 3 );

function your_custom_function( $response, $data, $screen_id ) {
    // your custom code here
    return $response;
}

Parameters

$response (array): The Heartbeat response data.
$data (array): The $_POST data sent with the Heartbeat request.
$screen_id (string): The screen ID of the current admin page.

More information

See WordPress Developer Resources: heartbeat_received

Examples

Add custom data to Heartbeat response

Add a custom key-value pair to the Heartbeat response.

add_filter( 'heartbeat_received', 'add_custom_data_to_heartbeat', 10, 3 );

function add_custom_data_to_heartbeat( $response, $data, $screen_id ) {
    $response['my_custom_key'] = 'My custom value';
    return $response;
}

Modify Heartbeat interval based on screen ID

Change the Heartbeat interval for specific screen IDs.

add_filter( 'heartbeat_received', 'modify_heartbeat_interval', 10, 3 );

function modify_heartbeat_interval( $response, $data, $screen_id ) {
    if ( 'post' === $screen_id ) {
        $response['heartbeat_interval'] = 60; // 60 seconds for post edit screen
    }
    return $response;
}

Send notification via Heartbeat

Send a custom notification to the user when a specific condition is met.

add_filter( 'heartbeat_received', 'send_custom_notification', 10, 3 );

function send_custom_notification( $response, $data, $screen_id ) {
    if ( some_condition_is_met() ) {
        $response['custom_notification'] = 'This is your custom notification!';
    }
    return $response;
}

Track user activity using Heartbeat

Log user activity in the admin area by tracking Heartbeat requests.

add_filter( 'heartbeat_received', 'log_user_activity', 10, 3 );

function log_user_activity( $response, $data, $screen_id ) {
    $user_id = get_current_user_id();
    $activity_log = "User {$user_id} was active on screen {$screen_id}";
    error_log( $activity_log );
    return $response;
}

Use the Heartbeat API to refresh the data in a custom dashboard widget.

add_filter( 'heartbeat_received', 'refresh_custom_dashboard_widget', 10, 3 );

function refresh_custom_dashboard_widget( $response, $data, $screen_id ) {
    if ( 'dashboard' === $screen_id && isset( $data['custom_widget_nonce'] ) ) {
        $response['custom_widget_data'] = fetch_new_widget_data();
    }
    return $response;
}