What is a Heartbeat in WordPress?

The WordPress Heartbeat API is a built-in feature introduced in version 3.6 that enables real-time communication between the browser and the server using AJAX. It powers automated tasks such as autosaving content, preventing simultaneous post edits, and updating plugin or theme data without requiring a full page refresh.

How the Heartbeat API Works

The Heartbeat API sends periodic AJAX requests, known as “ticks,” from the client (browser) to the server at regular intervals ranging from 15 to 120 seconds. These intervals adjust based on activity, becoming more frequent when necessary, such as during post edits.

Client-Side Behavior

When a WordPress page loads, the Heartbeat API initializes and begins sending data. Developers can modify or add data to these requests using jQuery events:

javascript
jQuery( document ).on( 'heartbeat-send', function ( event, data ) {
  data.custom_value = 'example';
});

Server-Side Handling

The server processes incoming data through admin-ajax.php and can modify or respond to Heartbeat requests via WordPress filters:

php
function modify_heartbeat_response( $response, $data ) {
  if ( isset( $data['custom_value'] ) ) {
    $response['custom_response'] = 'processed';
  }
  return $response;
}
add_filter( 'heartbeat_received', 'modify_heartbeat_response', 10, 2 );

Receiving Data on the Client

The browser listens for the server response and processes it with another jQuery event:

javascript
jQuery( document ).on( 'heartbeat-tick', function ( event, data ) {
  if ( data.custom_response ) {
    console.log( 'Server Response:', data.custom_response );
  }
});

Functions Powered by the Heartbeat API

Autosave: Prevents data loss by periodically saving post or page drafts.
Post Locking: Ensures only one user can edit a post at a time.
Real-Time Updates: Enables live updates for plugins and themes that require background data synchronization.
Session Management: Keeps logged-in users active and detects when their session expires.

Performance Considerations

Frequent AJAX requests can increase server load, especially in high-traffic environments or on shared hosting plans. This can affect CPU and memory usage, making it necessary to control or limit Heartbeat activity.

Managing and Customizing the Heartbeat API

Users and developers can manage Heartbeat behavior in several ways:

Using Plugins

Plugins such as WP Rocket and Heartbeat Control allow users to modify Heartbeat frequency or disable it entirely in specific areas of the WordPress dashboard.

Manually Adjusting Heartbeat Frequency

Developers can control Heartbeat intervals using the heartbeat_settings filter:

php
function adjust_heartbeat_interval( $settings ) {
  $settings['interval'] = 60; // Set Heartbeat interval to 60 seconds
  return $settings;
}
add_filter( 'heartbeat_settings', 'adjust_heartbeat_interval' );

Disabling the Heartbeat API

If Heartbeat negatively affects performance, it can be disabled for certain areas of WordPress:

php
function disable_heartbeat( $locations ) {
  unset( $locations['post-editor'] ); // Keep Heartbeat for autosave but disable it elsewhere
  return $locations;
}
add_filter( 'heartbeat_locations', 'disable_heartbeat' );

Common Issues and Troubleshooting

High CPU Usage: Reducing Heartbeat frequency can prevent excessive AJAX requests.
Unexpected Heartbeat Activity: Some themes and plugins modify Heartbeat behavior, leading to delayed or excessive requests.
Heartbeat Not Applying Settings: If interval changes or restrictions do not take effect, conflicting plugins may need to be identified and adjusted.

The Heartbeat API is essential for autosaving, post-locking, and real-time updates in WordPress but may require optimization to balance performance and functionality.