> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WordPress Legacy Setup

> Complete guide to setting up and customizing OneSignal Web Push notifications on WordPress sites using plugin versions 2.x.x, including advanced customizations, prompts, and troubleshooting

This comprehensive guide walks you through setting up and customizing web push notifications using OneSignal WordPress plugin versions 2.x.x. If you're using version 3 or higher, see our [WordPress v3+ guide](./wordpress).

<Warning>
  This guide is specifically for OneSignal WordPress plugin version 2.x.x. For version 3+, please refer to our updated [WordPress documentation](./wordpress).
</Warning>

## Prerequisites

* WordPress website with admin access
* HTTPS enabled (required for web push notifications)
* OneSignal account (free at onesignal.com)

***

## Step 1: Choose Integration

Create your OneSignal account at onesignal.com. If this isn't your first app, select **New App/Website**, name your app, select **Web**, and click "Next".

<Frame caption="Platform selection interface showing Web option">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7d3f2f0-Screen_Shot_2021-07-05_at_11.40.52_AM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=571b00b4e1940952a9fd8e71a21b712b" width="2140" height="1068" data-path="images/docs/7d3f2f0-Screen_Shot_2021-07-05_at_11.40.52_AM.png" />
</Frame>

Select **WordPress Plugin or Website Builder** to continue:

<Frame caption="Web push integration options with WordPress Plugin highlighted">
  <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/ccf9939-Screen_Shot_2021-07-05_at_10.32.06_AM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=4f71785d2f435a01e88d22e4129416f7" width="2002" height="1188" data-path="images/docs/ccf9939-Screen_Shot_2021-07-05_at_10.32.06_AM.png" />
</Frame>

## Step 2: Site Setup

Configure your site information carefully as these settings affect all notifications:

<Frame caption="Site Setup configuration form with required fields">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/662221c-site-setup.jpg?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=69d48a03d1017b54075ad710fcd6297f" width="1379" height="1019" data-path="images/docs/662221c-site-setup.jpg" />
</Frame>

| Field                | Description                                             | Requirements                                                          |
| -------------------- | ------------------------------------------------------- | --------------------------------------------------------------------- |
| **Site Name**        | Default name displayed in push notifications            | Keep concise for better display                                       |
| **Site URL**         | Your complete website URL                               | Must include `http://` or `https://` and match your actual URL format |
| **Auto Resubscribe** | Automatically resubscribes returning users (HTTPS only) | **Recommended** - Reduces friction for users who cleared browser data |
| **Default Icon URL** | Icon for prompts and notifications                      | Must be HTTPS, square 256x256 pixels, PNG/JPG/GIF format              |

<Info>
  **URL Format Important:** Ensure your Site URL exactly matches how users access your site. Mismatched URLs (www vs non-www, http vs https) can cause subscription issues.
</Info>

## Step 3: Advanced Push Settings (Optional)

OneSignal provides Safari Web Push certificates at no cost. Only upload custom certificates if you have specific requirements.

<Frame caption="Advanced push settings showing Safari certificate upload options">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/f21e43f-configure-3.jpg?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=0a2f7a2e408114044ef5d28316d13515" width="1204" height="660" data-path="images/docs/f21e43f-configure-3.jpg" />
</Frame>

**When to Use Custom Certificates:**

* You have existing Safari certificates
* Your organization requires specific certificate management
* You need custom certificate branding

## Step 4: Configure WordPress Plugin

### Install the Plugin

Add the [OneSignal WordPress Plugin](https://wordpress.org/plugins/onesignal-free-web-push-notifications/) from your WordPress admin or by searching "OneSignal" in the plugin directory.

### Configure API Keys

Copy your App ID and API Key from the OneSignal dashboard:

<Frame caption="OneSignal dashboard showing App ID and API Key locations">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6b4aa29-Screen_Shot_2021-07-05_at_11.01.07_AM.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=89fe32e989732751692914160cffa080" width="1748" height="862" data-path="images/docs/6b4aa29-Screen_Shot_2021-07-05_at_11.01.07_AM.png" />
</Frame>

Navigate to your WordPress admin → **OneSignal Push** → **Configure** tab and paste the keys:

<Frame caption="WordPress plugin configuration showing API key input fields">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/9d3d86a-Screen_Shot_2021-07-05_at_11.05.05_AM.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=f225d715a688a6efc6b50f26cafca73a" width="2008" height="1270" data-path="images/docs/9d3d86a-Screen_Shot_2021-07-05_at_11.05.05_AM.png" />
</Frame>

### Enable Push Prompts

Activate the Slide Prompt and Subscription Bell to request permission from visitors:

<Frame caption="Prompt settings showing Slide Prompt and Subscription Bell options">
  <img src="https://mintcdn.com/onesignal/Xl2NHJvxakrK4JbL/images/docs/edc7cb2-Screen_Shot_2021-07-05_at_11.16.22_AM.png?fit=max&auto=format&n=Xl2NHJvxakrK4JbL&q=85&s=45914ab2ed670a56015a4b62f33e4d3b" width="2382" height="1082" data-path="images/docs/edc7cb2-Screen_Shot_2021-07-05_at_11.16.22_AM.png" />
</Frame>

**Save your configuration** - this is critical for the plugin to function properly.

<Frame caption="Save button location at bottom of configuration page">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/289d5d6-Screen_Shot_2021-07-05_at_11.11.18_AM.png?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=5929ec4f86fa8e60d174d6b688b1dd1d" width="2008" height="660" data-path="images/docs/289d5d6-Screen_Shot_2021-07-05_at_11.11.18_AM.png" />
</Frame>

## Step 5: Test Your Setup

### Verify Installation

1. Visit your website (you may need to clear cache plugins)
2. Look for the OneSignal Slide Prompt and Subscription Bell
3. Subscribe to test the flow
4. Check **OneSignal Dashboard → Audience → Users** to confirm your subscription

### Send Test Notification

Navigate to **OneSignal Dashboard → Messages → New Push** to send your first notification and verify everything works.

<Info>
  **Troubleshooting:** If prompts don't appear, check that [push notifications are enabled in your device settings](./notifications-not-shown-web-push#notifications-are-blocked-in-settings) and try clearing your browser cache.
</Info>

## Step 6: Configure Notification Prompts

Set up how and when users see subscription prompts in the **Configure** section:

### Subscription Bell

A persistent icon (usually in the corner) that users can click anytime to manage their subscription status.

### Slide Prompt

A modal dialog that appears based on your timing settings to request permission.

**Next Steps:** Users typically want to customize prompt timing and appearance. See the [Advanced Customizations](#advanced-customizations) section below.

## Step 7: Automatic Post Notifications

### Basic Setup

When creating posts, you'll see a OneSignal section. Check **Send notification on post publish** to notify subscribers:

<Frame caption="Post editor showing OneSignal notification checkbox">
  <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/69f208a-Screen_Shot_2021-08-09_at_6.10.41_PM.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=3be4ccf2e8e3631de57b44f4e4039d39" width="1990" height="1248" data-path="images/docs/69f208a-Screen_Shot_2021-08-09_at_6.10.41_PM.png" />
</Frame>

### Auto-Enable Notifications

To automatically check this box for all new posts:

1. Go to **OneSignal Push** → **Automatic Notification Settings**
2. Enable **Automatically send a push notification when I create a post**
3. Save settings

<Frame caption="Automatic notification settings showing auto-send option">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4af55ad-Screen_Shot_2021-08-09_at_6.18.37_PM.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=15a266483293e49d5e133b3c95960bc6" width="1966" height="368" data-path="images/docs/4af55ad-Screen_Shot_2021-08-09_at_6.18.37_PM.png" />
</Frame>

### Welcome Notifications

Configure optional welcome messages sent immediately after users subscribe. Edit or disable these in the **Configure** section of your plugin.

<Info>
  **Rate Limiting:** Multiple notifications for the same post are limited to one per minute to prevent spam.
</Info>

***

## Advanced Customizations

The OneSignal WordPress plugin loads our Web Push SDK with your configured options. You can use any [Web Push SDK JavaScript APIs](./web-sdk-reference) to customize the experience further.

<Info>
  **Developer Note:** This section requires JavaScript and PHP knowledge. If you need help adding code to your site, consider using plugins like [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/) or [Custom CSS & JS](https://wordpress.org/plugins/custom-css-js/).
</Info>

### Customizing Subscription Prompts

#### Advanced Prompt Setup

For sophisticated prompt customization including delays, categories, and email collection:

##### Step 1: Disable Default Prompts

In **OneSignal WordPress Plugin → Prompt Settings**, turn OFF the Slide and Native Prompt (you can keep the Bell enabled).

<Frame caption="Prompt settings showing disabled Slide and Native prompts">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/ff12526-Screen_Shot_2021-09-01_at_11.03.54_AM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=4a4aea38a75939cd1845d9a4f9ec6b0c" width="2676" height="1054" data-path="images/docs/ff12526-Screen_Shot_2021-09-01_at_11.03.54_AM.png" />
</Frame>

##### Step 2: Enable Manual Initialization

Scroll to **Advanced Settings** and toggle ON "Disable OneSignal initialization", then **Save**.

<Frame caption="Advanced settings showing manual initialization toggle">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7ba0ca1-Screen_Shot_2021-08-09_at_8.32.28_PM.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=773629edeb5a2099250b9d171dea6c13" width="1798" height="606" data-path="images/docs/7ba0ca1-Screen_Shot_2021-08-09_at_8.32.28_PM.png" />
</Frame>

##### Step 3: Add Custom JavaScript

Add this code to your site (after the 3-second delay shown in examples):

```javascript theme={null}
// Basic Delayed Prompt
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "push",
          autoPrompt: true,
          text: {
            actionMessage: "Get notified of new posts and updates!",
            acceptButton: "Yes",
            cancelButton: "No thanks",
          },
          delay: {
            timeDelay: 10, // Wait 10 seconds
            pageViews: 2,  // Show after 2 page views
          }
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);
```

```javascript theme={null}
// Category-Based Prompt
setTimeout(function(){
  window._oneSignalInitOptions.promptOptions = {
    slidedown: {
      prompts: [
        {
          type: "category",
          autoPrompt: true,
          text: {
            actionMessage: "Choose what notifications you'd like to receive:",
            acceptButtonText: "Subscribe",
            cancelButtonText: "Not now",
            positiveUpdateButton: "Save Preferences",
            negativeUpdateButton: "Cancel",
            updateMessage: "Update your notification preferences.",
          },
          categories: [
            {
              tag: "news",
              label: "Breaking News",
            },
            {
              tag: "sports",
              label: "Sports Updates",
            },
            {
              tag: "tech",
              label: "Technology News",
            }
          ]
        }
      ]
    }
  }
  window.OneSignal = window.OneSignal || [];
  window.OneSignal.push(function() {
    window.OneSignal.init(window._oneSignalInitOptions);
  });
}, 3000);
```

#### Page-Specific Prompts

##### Server-Side PHP Method

Use the [`onesignal_initialize_sdk` filter](#onesignal_initialize_sdk-filter) to control initialization based on page properties.

##### Client-Side JavaScript Method

Enable "Disable OneSignal initialization" and add conditional JavaScript to initialize OneSignal only on specific pages.

#### Multi-Language Prompts

For single language sites, simply translate the text in the prompt configuration.

For multi-language sites, use the manual initialization method above and detect the page language to display appropriate text.

### User Segmentation and Targeting

#### Tagging Users

Categorize users with [Tags](./add-user-data-tags) to send targeted notifications:

```javascript theme={null}
// Tag users based on their interests
OneSignal.push(function() {
  OneSignal.sendTag("interest", "technology");
  OneSignal.sendTag("location", "california");
});
```

#### Targeting Segments

Create [Segments](./segmentation) in your OneSignal dashboard using **User Tag** filters, then target them with the `onesignal_send_notification` filter:

```php theme={null}
<?php
add_filter('onesignal_send_notification', 'target_tech_users', 10, 4);

function target_tech_users($fields, $new_status, $old_status, $post) {
  // Only send to users interested in technology
  $fields['included_segments'] = array('Technology Enthusiasts');
  return $fields;
}
```

### Featured Images in Notifications

#### Enable Featured Image Support

Ensure your theme supports featured images. Check your theme's `functions.php` for:

```php theme={null}
add_theme_support('post-thumbnails');
```

#### Configure Image Settings

In **OneSignal Push → Sent Notification Settings**, toggle on the desired featured image options:

<Frame caption="Featured image settings showing icon and large image options">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/fafaeea-Screen_Shot_2021-08-09_at_8.24.33_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=58f3d8299d0ca28087661a2dacf63a2d" width="1752" height="266" data-path="images/docs/fafaeea-Screen_Shot_2021-08-09_at_8.24.33_PM.png" />
</Frame>

### Third-Party Plugin Integration

#### Standard Post Types

Enable **Automatically send a push notification when I publish a post from 3rd party plugins** for standard post types.

<Frame caption="Third-party plugin integration settings">
  <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/gxAslQH.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=95163a1e8e50ed70b7197dda49d82ac6" width="1172" height="836" data-path="images/docs/gxAslQH.png" />
</Frame>

#### Custom Post Types

Add custom post types (comma-separated) to the Additional Custom Post Types field:

<Frame caption="Custom post types configuration field">
  <img src="https://mintcdn.com/onesignal/6tscVAtiSqz353kV/images/docs/TQ2LsBu.png?fit=max&auto=format&n=6tscVAtiSqz353kV&q=85&s=1cea147dc5fcc005e8580c226997859f" width="1172" height="836" data-path="images/docs/TQ2LsBu.png" />
</Frame>

**Finding Custom Post Types:**
Look at your browser's URL when creating the custom post type:
`https://yoursite.com/wp-admin/post-new.php?post_type=your_custom_type`

The `post_type` parameter shows the name to add.

### Mobile App Integration

#### Method 1: Simple Web Browser Opening

Enable **Send notifications additionally to iOS & Android platforms** in your WordPress plugin settings.

<Frame caption="Mobile platform integration toggle">
  <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1d64470-c33ad19-cr3uBcL.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=40948b57a6a8755ad0956d08120ef01e" width="580" height="64" data-path="images/docs/1d64470-c33ad19-cr3uBcL.png" />
</Frame>

#### Method 2: Deep Linking

For custom mobile app behavior, disable the above setting and use this PHP code:

```php theme={null}
<?php
add_filter('onesignal_send_notification', 'send_to_mobile_apps', 10, 4);

function send_to_mobile_apps($fields, $new_status, $old_status, $post) {
  $fields['isAndroid'] = true;
  $fields['isIos'] = true;
  $fields['isAnyWeb'] = true;
  $fields['data'] = array("customkey" => $fields['url']);
  $fields['web_url'] = $fields['url'];
  unset($fields['url']); // Prevents browser opening on mobile

  return $fields;
}
```

### WordPress Plugin Hooks and Filters

#### Code Placement

<Info>Place custom PHP code in `wp-content/mu-plugins/` to prevent it from being overwritten by updates.</Info>

Create `wp-content/mu-plugins/onesignal-custom.php` with your custom code.

#### onesignal\_send\_notification

Modify notification parameters before sending:

```php theme={null}
<?php
add_filter('onesignal_send_notification', 'customize_notification', 10, 4);

function customize_notification($fields, $new_status, $old_status, $post) {
  // Customize title and message
  $fields['headings'] = array("en" => "Breaking News!");
  $fields['contents'] = array("en" => "Check out our latest post");

  // Schedule for later
  $fields['send_after'] = "2024-12-25 09:00:00 GMT-0800";

  // Add action buttons
  $fields['web_buttons'] = array(
    array(
      "id" => "read-more",
      "text" => "Read More",
      "url" => get_permalink($post->ID)
    )
  );

  return $fields;
}
```

#### onesignal\_initialize\_sdk

Control when OneSignal initializes:

```php theme={null}
<?php
add_filter('onesignal_initialize_sdk', 'control_initialization', 10, 1);

function control_initialization($settings) {
  // Only initialize on blog posts
  if (is_single() && get_post_type() == 'post') {
    return true;
  }
  return false;
}
```

#### onesignal\_include\_post

Force notifications for specific post types:

```php theme={null}
<?php
add_filter('onesignal_include_post', 'include_pages', 10, 3);

function include_pages($new_status, $old_status, $post) {
  // Send notifications when pages are published
  if ($post->post_type == "page" && $new_status == "publish") {
    return true;
  }
  return false;
}
```

#### onesignal\_meta\_box\_send\_notification\_checkbox\_state

Control the default state of the notification checkbox:

```php theme={null}
<?php
add_filter('onesignal_meta_box_send_notification_checkbox_state', 'auto_check_checkbox', 10, 2);

function auto_check_checkbox($post, $settings) {
  // Always check the box for news category posts
  if (has_category('news', $post)) {
    return true;
  }
  return false;
}
```

### Mixed WordPress/Non-WordPress Sites

For sites with both WordPress and non-WordPress pages:

1. Use [Custom Code Setup](./web-push-custom-code-setup) in OneSignal dashboard
2. Add this code to non-WordPress pages:

```html theme={null}
<script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
<script>
var OneSignal = window.OneSignal || [];
var initConfig = {
  appId: "YOUR_APP_ID_FROM_WORDPRESS_PLUGIN",
  notifyButton: {
    enable: true
  },
};
OneSignal.push(function () {
  OneSignal.SERVICE_WORKER_PARAM = {
    scope: '/wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/'
  };
  OneSignal.SERVICE_WORKER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.SERVICE_WORKER_UPDATER_PATH = 'wp-content/plugins/onesignal-free-web-push-notifications/sdk_files/OneSignalSDKWorker.js'
  OneSignal.init(initConfig);
});
</script>
```

***

## Troubleshooting

### Common Issues

#### "No Recipients" Error

* **Cause:** Trying to send multiple notifications for the same post too quickly
* **Solution:** Wait at least one minute between notifications for the same post

#### Prompts Not Appearing

* **Cause:** Cache plugins, browser settings, or initialization issues
* **Solutions:**
  * Clear all cache plugins
  * Check browser notification permissions
  * Verify HTTPS is enabled
  * Confirm plugin configuration is saved

#### "Couldn't load wp.data" Warning

* **WordPress 5+ with Gutenberg:** May indicate setup issues - contact support
* **WordPress 4.x:** Safe to ignore - this warning doesn't affect functionality

#### Custom Post Types Not Working

* **Cause:** Missing required meta data
* **Solution:** Use the `onesignal_include_post` filter to explicitly include your post type

#### Notifications Not Scheduling

* **Cause:** WordPress cron or theme conflicts
* **Solutions:**
  1. Use OneSignal Dashboard or API for scheduling
  2. Implement custom scheduling with `onesignal_send_notification` filter
  3. Use [Zapier integration](./zapier) for automation

## Database Entries

OneSignal creates these entries in your `wp_postmeta` table:

| Entry                         | Description                                           |
| ----------------------------- | ----------------------------------------------------- |
| `onesignal_meta_box_present`  | Confirms OneSignal was active when post was published |
| `onesignal_send_notification` | Tracks notification sending                           |
| `status`                      | HTTP status of notification (200 = success)           |
| `response_body`               | API response with notification ID and recipient count |
| `recipients`                  | Number of users who received the notification         |

## Getting Help

* **Plugin Issues:** Check [Troubleshooting WordPress Web Push](./troubleshooting-wordpress-web-push)
* **General Support:** Contact `support@onesignal.com`
* **Plugin Source:** Available on [GitHub](https://github.com/OneSignal/OneSignal-WordPress-Plugin)

***

## Next Steps

After completing this setup:

1. **Monitor Performance:** Check your OneSignal dashboard regularly for subscriber growth and engagement metrics
2. **Optimize Prompts:** Experiment with different prompt timing and messaging
3. **Segment Users:** Implement tagging to send more targeted notifications
4. **Test Thoroughly:** Send test notifications to different devices and browsers
5. **Plan Content Strategy:** Develop a notification strategy that adds value without overwhelming users

For advanced features like A/B testing, advanced segmentation, and detailed analytics, consider upgrading to a paid OneSignal plan.