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

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.

Basic Prompt Setup

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

Initial Test

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

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

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

5. 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:

• 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:

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

3. After creating segments, refresh your WordPress post editor
4. 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

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.

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

4. Scroll down, click Save, then Finish
5. 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?

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.

How do I send email or SMS from WordPress?

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.

Why aren't my prompts working after migration?

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

4. Refresh your website to see current configuration
5. Clear your WordPress cache plugin settings if applicable

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:

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.

Can I modify the notification parameters before sending?

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);