​
Overview

This guide covers how to setup and configure OneSignal WordPress Web Push Plugin v3+.
For the older version 2.x.x WordPress docs, see WordPress Legacy plugin.

​
What’s New in Version 3+

This release marks a significant upgrade by streamlining the setup and configuration process. With Version 3+, you can handle all your prompt settings in one place—the OneSignal Dashboard.
  • 🚀 SDK Upgrade: Updates OneSignal Web SDK from version 15 to 16
  • 💬 Dashboard Prompts: Configure all permission prompts directly in the OneSignal dashboard—no custom code required
  • ⏩ One-Click Publishing: Check “Send notification when post is published” to automatically send push notifications
  • 🧑‍🤝‍🧑 Audience Targeting: Choose which segments receive notifications for each post
  • 📲 Mobile App Integration: Send to mobile app subscribers with optional deep linking

​
Setup

Before you begin, ensure you have:
  • OneSignal account (free to create)
  • WordPress admin access to install and configure plugins
  • HTTPS-enabled website (required for web push notifications)

​
1. Configure WordPress in OneSignal Dashboard

Navigate to Settings > Push & In-App > Web > WordPress Plugin or Website Builder

Select WordPress from the Website Builder options in your OneSignal dashboard

​
Site setup

  • Site Name: The name of your site and default notification title.
  • Site URL: Must match your WordPress site’s exact URL (follow Same-origin policy)
  • Auto Resubscribe: Enable this to automatically resubscribe users who clear their browser data when they return to your site (no new permission prompt required)
  • Default Icon URL: Square 256x256px PNG or JPG file for notifications and prompts – MacOS Safari will not show a notification prompt without an Icon.

Enter your exact Site URL. https://your-site.com is different from https://www.your-site.com—use only one format consistently

Testing locally? See Local Testing Guide for localhost development

​
Permission prompts

Set up your permission prompts for Push, Email, and SMS. The Push Slide Prompt is enabled by default, but you can customize or add additional prompts.
Pro Tip: Start with simple prompts and gradually add complexity. You can modify all prompt settings anytime through the OneSignal dashboard. Explore all available options in Web permission prompts.
1

Click on Push Slide Prompt to customize

Access and customize your push slide prompt settings

2

Configure timing and text:

  • Set Auto Prompt to 1 pageview and 1 second for initial testing
    • Customize prompt text and appearance
    • Adjust timing based on user behavior after launch

Configure auto-prompt timing and customize prompt appearance

3

Click Done when you've finished configuring the prompt.

Pro Tip: Start with simple prompts and gradually add complexity. You can modify all prompt settings anytime through the OneSignal dashboard. Explore all available options in Web permission prompts.

​
Welcome notification

Set up an immediate notification sent after users first subscribe. This:
  • Thanks users for subscribing
  • Demonstrates how notifications appear
  • Increases engagement and reduces unsubscribes
Configure your welcome message text and timing, then scroll down and click Save.
Skip the Advanced Push Settings section for now — these are for custom Web SDK setup. Click Save to continue.

​
2. Configure WordPress plugin

After saving your dashboard configuration, you’ll see your App ID and API Key. Copy these values to your WordPress plugin:

Copy your App ID and API Key from the OneSignal dashboard

Don’t see an API Key? Make sure you selected the WordPress option above. Then follow our Keys & IDs guide to create one.
1

In your WordPress admin, navigate to the OneSignal plugin settings

2

Paste the App ID and REST API Key exactly as shown in your dashboard

Ensure your WordPress plugin App ID and REST API Key match your OneSignal dashboard exactly

​
Advanced settings

Configure additional plugin options based on your needs:

Advanced settings for enhanced functionality and analytics tracking

URL parameter tracking Add analytics parameters to notification URLs for tracking. Important: Escape special characters—input is added as-is to URLs. Example for Google Analytics: 
utm_medium=push&utm_source=onesignal&utm_campaign=wordpress-plugin
Example with special characters: 
utm_medium=ppc&utm_source=adwords&utm_campaign=snow%20boots&utm_content=durable%20snow%20boots
Additional settings
  • Custom Post Types: Add post types from plugins to enable notification options
  • Automatically send notifications when a post is published: Automatically checks notification box when publishing posts so notifications are sent without having to check the box manually
  • Automatically send notifications when a post is updated: Automatically checks notification box when updating posts so notifications are sent without having to check the box manually
  • Automatically send notifications when a page is published: Automatically checks notification box when publishing pages so notifications are sent without having to check the box manually
  • Automatically send notifications when a page is updated: Automatically checks notification box when updating pages so notifications are sent without having to check the box manually
  • Automatically send a push notification when I publish a post from 3rd party plugins: Auto-send notifications from external publishing plugins
  • Mobile App Integration: Send notifications to your mobile app subscribers using the same OneSignal App ID

​
3. Complete migration (Upgrading Users Only)

New installations can skip this step. If you’re upgrading from v2+, follow along…
Time-Sensitive: Complete these steps ASAP to avoid users missing notifications during the transition.
1

After saving your OneSignal dashboard configuration, return to WordPress

2

Click Migration Completed in the plugin settings

3

Click Save Settings to finalize the upgrade

Click Migration Completed to finalize your plugin upgrade

Setup complete! Click Save Settings to finish plugin configuration.

​
Testing your setup

  1. Visit your website (avoid incognito/private browsing—users cannot subscribe in these modes)
  2. Look for the slidedown prompt you configured

Your configured slidedown prompt should appear based on your timing settings

  1. Click the subscribe button (labeled as “Subscribe” in this example)
  2. Accept the browser permission when prompted

Browser permission prompt (appearance varies by browser) is required for web push notifications

  1. Check for welcome notification (if configured)

Welcome notification appears immediately after successful subscription

Success! Your WordPress site is now configured for web push notifications. Users will start appearing in your Subscriptions as they subscribe.Next Steps:
Having Issues? Check our WordPress troubleshooting guide for common solutions.

​
Publishing notifications

When you schedule a post to be published, OneSignal will also schedule a push notification to be sent to your subscribers at the scheduled time. If you reschedule the post, the push notification will be canceled and a new push will be scheduled for the new time. You can view your scheduled and cancelled notifications in the OneSignal dashboard under Delivery > Scheduled Messages. See Push message reports for more details.

​
Basic post notifications

When creating or editing a WordPress post, locate the OneSignal Push Notifications metabox (usually at the bottom or sidebar of the post editor).

OneSignal Push Notifications metabox—drag to reposition if needed

To send a notification:
  • Check “Send notification when post is published or updated”
  • Uncheck to skip sending a notification for that post

​
Audience targeting

​
Send to all subscribers (default)

By default, notifications go to all push subscribers.

​
Send to specific segments

Target specific audiences using segments you create in OneSignal Dashboard > Audience > Segments. If you set up categories in Step 3, create corresponding segments:
  1. Go to Audience > Segments in your OneSignal dashboard
  2. Create segments using your tag keys, eg:
    • News Segment: Tag news is 1
    • Deals Segment: Tag deals is 1

Tags are case-sensitive! 'news' and 'News' are different tags

  1. After creating segments, refresh your WordPress post editor
  2. Select your target segment from the dropdown

Select specific segments to target relevant user groups

Advanced Segmentation: Create segments based on user behavior, location, device type, and more. Tags provide the most flexibility for custom user data and personalization.

​
Customizing notification content

​
Default behavior

  • Title: Uses your WordPress site title (Settings > General)
  • Message: Uses the post title
  • Image: Uses the post’s featured image (if set)
  • URL: Links to the published post

​
Custom content

Check “Customize notification content” to override defaults:

Customize notification title, content, and other elements

Example result:

Customized push notification as it appears to users

​
Mobile app integration

If you have a mobile app using the same OneSignal App ID:
  1. Enable “Send notification to Mobile app subscribers” in plugin settings
  2. In the post metabox, add a Mobile URL for deep linking
  3. Mobile users will be directed to your app instead of the web browser
Ready to Scale: Explore advanced push strategies and automated journeys for sophisticated notification campaigns.
Notifications Not Appearing? Check our Web push troubleshooting guide for solutions.

​
FAQ

Note: This method only works with slidedown and native permission prompts, not bell or custom link prompts.
  1. In your OneSignal dashboard, go to Settings > Push & In-App > Web Settings
  2. Select your prompt from the Permission Prompt Setup table
  3. Uncheck Auto Prompt and click Done

Disable Auto Prompt to manually control when prompts appear

  1. Scroll down, click Save, then Finish
  2. Add custom JavaScript code to specific pages where you want prompts to appear
This gives you complete control over prompt timing and placement. See Web permission prompts for implementation details. here
Yes! If your mobile app uses the same OneSignal App ID:
  1. Enable “Send notification to Mobile app subscribers” in the WordPress plugin settings
  2. When publishing posts, use the Mobile URL field in the OneSignal metabox to specify deep links
  3. Without a custom Mobile URL, users will be directed to your website
This feature enables cross-platform messaging from a single WordPress interface.
The WordPress plugin currently supports push notifications only. For email and SMS:
  1. Email: Follow our Email setup guide, then use Email messaging tools
  2. SMS: Follow our SMS setup guide, then use SMS messaging tools
Both channels can be managed from the same OneSignal dashboard alongside your push notifications.
Caching Issues: WordPress caching may delay migration changes.Solution:
  1. Right-click on your website and select Inspect
  2. Go to the Network tab
  3. Check “Disable cache”

Disable browser cache to force loading updated files after migration

  1. Refresh your website to see current configuration
  2. Clear your WordPress cache plugin settings if applicable
This error indicates incomplete migration:

404 error in browser console indicates incomplete migration process

Solution:
  1. Ensure you’ve saved your OneSignal dashboard configuration
  2. In WordPress, click “Migration Completed” in the plugin settings
  3. Click Save Settings to finalize the upgrade
This error only affects users upgrading from version 2.x.x.
Yes, you can use the onesignal_send_notification filter.
Place custom PHP code in wp-content/mu-plugins/onesignal-custom.php. This ensures its loads correctly and prevents it from being overwritten by updates.
<?php

add_filter('onesignal_send_notification', function($fields, $post_id) {

  // Include any properties mentioned in the Create Notification API Reference:
  // https://documentation.onesignal.com/reference/push-notification eg:

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

  // Return the modified fields array
  return $fields;

}, 10, 2);