WordPress
Complete setup and migration guide for OneSignal WordPress Web Push Plugin v3+. Configure push notifications, prompts, and segmentation through the OneSignal dashboard with streamlined setup process.
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
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.
Click on Push Slide Prompt to customize
Access and customize your push slide prompt settings
Configure timing and text:
- Set Auto Prompt to
1
pageview and1
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
Click Done when you've finished configuring the prompt.
Click on Push Slide Prompt to customize
Access and customize your push slide prompt settings
Configure timing and text:
- Set Auto Prompt to
1
pageview and1
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
Click Done when you've finished configuring the prompt.
For targeted messaging based on user interests, set up categories:
Select Categories in your prompt settings
Configure each category with:
- Label: What users see in the prompt
- Tag Key: Internal tag key for segmentation
Click Done when you've finished configuring the prompt.
Example: Setting up News and Deals categories creates tags 'news: 1' and 'deals: 1' for users who check these options
Tag Logic: Checked categories set tag value to 1
, unchecked to 0
. These tags enable targeted messaging to specific user interests.
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.
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.
In your WordPress admin, navigate to the OneSignal plugin settings
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:
Example with special characters:
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)
After saving your OneSignal dashboard configuration, return to WordPress
Click Migration Completed in the plugin settings
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
- Visit your website (avoid incognito/private browsing—users cannot subscribe in these modes)
- Look for the slidedown prompt you configured
Your configured slidedown prompt should appear based on your timing settings
- Click the subscribe button (labeled as “Subscribe” in this example)
- Accept the browser permission when prompted
Browser permission prompt (appearance varies by browser) is required for web push notifications
- Check for welcome notification (if configured)
Welcome notification appears immediately after successful subscription
- Visit your website (avoid incognito/private browsing—users cannot subscribe in these modes)
- Look for the slidedown prompt you configured
Your configured slidedown prompt should appear based on your timing settings
- Click the subscribe button (labeled as “Subscribe” in this example)
- Accept the browser permission when prompted
Browser permission prompt (appearance varies by browser) is required for web push notifications
- Check for welcome notification (if configured)
Welcome notification appears immediately after successful subscription
- In your OneSignal dashboard, go to Audience > Subscriptions
- You should see your web push subscription marked as “Subscribed”
Successful subscriptions appear in your OneSignal dashboard audience
- Navigate to Messages > Push in your OneSignal dashboard
- Create a New Message
- Send a test notification to yourself
- Verify the notification appears correctly See our Push messaging guide for detailed instructions.
Success! Your WordPress site is now configured for web push notifications. Users will start appearing in your Subscriptions as they subscribe.
Next Steps:
- Review Web permission prompts for advanced customization
- Explore Channel setup for email and SMS integration
- Set up segmentation strategies for targeted messaging
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:
- Go to Audience > Segments in your OneSignal dashboard
- Create segments using your tag keys, eg:
- News Segment: Tag
news
is1
- Deals Segment: Tag
deals
is1
- News Segment: Tag
Tags are case-sensitive! 'news' and 'News' are different tags
- After creating segments, refresh your WordPress post editor
- 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:
- Enable “Send notification to Mobile app subscribers” in plugin settings
- In the post metabox, add a Mobile URL for deep linking
- 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
How do I disable prompts on specific pages?
How do I disable prompts on specific pages?
Note: This method only works with slidedown and native permission prompts, not bell or custom link prompts.
- In your OneSignal dashboard, go to Settings > Push & In-App > Web Settings
- Select your prompt from the Permission Prompt Setup table
- Uncheck Auto Prompt and click Done
Disable Auto Prompt to manually control when prompts appear
- Scroll down, click Save, then Finish
- 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
Can I send notifications to mobile app subscribers?
Can I send notifications to mobile app subscribers?
Yes! If your mobile app uses the same OneSignal App ID:
- Enable “Send notification to Mobile app subscribers” in the WordPress plugin settings
- When publishing posts, use the Mobile URL field in the OneSignal metabox to specify deep links
- Without a custom Mobile URL, users will be directed to your website
This feature enables cross-platform messaging from a single WordPress interface.
How do I send email or SMS from WordPress?
How do I send email or SMS from WordPress?
The WordPress plugin currently supports push notifications only. For email and SMS:
- Email: Follow our Email setup guide, then use Email messaging tools
- 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.
Why aren't my prompts working after migration?
Why aren't my prompts working after migration?
Caching Issues: WordPress caching may delay migration changes.
Solution:
- Right-click on your website and select Inspect
- Go to the Network tab
- Check “Disable cache”
Disable browser cache to force loading updated files after migration
- Refresh your website to see current configuration
- Clear your WordPress cache plugin settings if applicable
What does `A bad HTTP response code (404)` error mean?
What does `A bad HTTP response code (404)` error mean?
This error indicates incomplete migration:
404 error in browser console indicates incomplete migration process
Solution:
- Ensure you’ve saved your OneSignal dashboard configuration
- In WordPress, click “Migration Completed” in the plugin settings
- Click Save Settings to finalize the upgrade
This error only affects users upgrading from version 2.x.x.