​
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
For the older version 2.x.x WordPress docs, see WordPress Legacy plugin.

​
Prerequisites

Before you begin, ensure you have:

  • OneSignal account (free to create)
  • OneSignal App configured (see Quickstart guide)
  • WordPress admin access to install and configure plugins
  • HTTPS-enabled website (required for web push notifications)

​
Setup

​
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? 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 notifications
  • Auto-send on Publish: Automatically checks notification box when publishing posts
  • Third-party Plugin Integration: 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

​
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