Overview

This release marks a significant upgrade by streamlining the setup & configuration process. With Version 3+, you can handle all your prompt settings in one place -- the OneSignal Dashboard. For the older version 2.x.x WordPress docs, see WordPress Legacy plugin.

New in WordPress Plugin version 3+:

• 🚀 Upgrades the OneSignal Web SDK from version 15 to 16.
• 💬 Setup more new prompts within the OneSignal dashboard, including the following. No custom code is required anymore to configure these.
• ⏩ When publishing a new post, check the "Send notification when post is published" box to send a push notification.
• 🧑‍🤝‍🧑 Choose which audience segment should receive notifications for each post.
• 📑 Web Topics are included by default.
• 📲 Send to mobile app subscribers, with an option to direct them to a different URL (Deep Link).

---

Requirements

• OneSignal account
• OneSignal App. See Quickstart guide.

Setup

1. Navigate to your OneSignal dashboard WordPress config

Login to onesignal.com and open your OneSignal dashboard. Navigate to Settings > Push & In-App > Web Settings > Wordpress Plugin or Website Builder and select WordPress.

2. Configure your WordPress site setup

Add your site details in Site Setup.

• Site Name: This is used as the default title of your web push notifications if no title is provided.
• Site URL: This must be the exact origin (URL) of your site. For example, if your site is https://mydomain.com, don’t use https://www.mydomain.com. Follow the Same-origin policy for more details.
• Local Testing: Developers, refer to our Local Testing Guide if you are testing on localhost.
• Auto Resubscribe (Recommended): Allows users who clear their browser data/cache to be automatically resubscribed when they return to your site. They will not be prompted again unless they turn off push permissions.
• Default Icon URL (Recommended): This icon is used for web push notifications and prompts. It should be a square 256x256 px PNG or JPG file.

3. Permission prompt setup

This is where you can configure your permission prompts for push, email, and sms. You should see the Push Slide Prompt already but you can add and update these prompts whenever you like through the dashboard.

For example, click the Push Slide Prompt

You can customize the text, auto-prompt times, and categories.

For now, set Auto Prompt to 1 pageview and 1 second. You can always change this later.

If you want to segment users and send messages based on specific categories they are interested in, then you can add those categories via the Category Slidedown prompt.

Select Categories and set the:

1. Label - this is what your users see in the prompt .
2. Tag Key - the Tag key used for segmentation.

In this example, we set 2 categories/tag keys. When the user has the category checked, the tag value is 1 and if unchecked, it is 0. You can always change these labels and tags later.

We will explain how to send messages to users with these tags later in Send to segment section below.

For now, click Done to continue.

📘

Push, email, and sms prompts.

You can now configure and update your prompts directly through the onesignal.com dashboard. There are many options available!

See Web permission prompts for full details.

4. Welcome notification (optional)

Send a push immediately after the user subscribes to the website the first time. This is a good opportunity to thank them for subscribing and gives the user an example of how web push notifications work.

Scroll to the bottom and press Save.

Advanced Push Settings

This is for setting up the Web SDK setup directly. You can skip this for now and click Save.

5. Configure WordPress Plugin

On the next page of the onesignal.com dashboard, copy-paste the APP ID and API Key into the OneSignal WordPress plugin so they match.

📘

Don't see your REST API key?

Create a new API key by following the Keys & IDs guide.

6. Advanced Settings in WordPress Plugin

The WordPress plugin has some additional settings that you can configure.

Additional Notification URL Parameters

Adds the specified string as extra URL parameters to your notification URL so that they can be tracked as an event by your analytics system. Please escape your parameter values; your input will be added as-is to the end of your notification URL. Example:

If you want:

• utm_medium to be ppc
• utm_source to be adwords
• utm_campaign to be snow boots
• utm_content to be durable snow boots

Then use the following string:

utm_medium=ppc&utm_source=adwords&utm_campaign=snow%20boots&utm_content=durable%20%snow%boots

Another common example would be to use:

utm_medium=push&utm_source=onesignal&utm_campaign=onesignal-wordpress-plugin

Additional Custom Post Types for Automatic Notifications Created From Plugins

If your site has additional custom post types, you can specify them in this field to be eligible to send push notifications when the custom post type is published.

Automatically send notifications when a post is published or updated

Select this option so that when you publish or update a post, the checkbox to send the push is automatically selected so you don't have to select it. See below Send notification when post is published for details.

Automatically send a push notification when I publish a post from a 3rd party plugin

Select this option so that when you publish or update a post from a 3rd party plugin specified, the checkbox to send the push is automatically selected so you don't have to select it. See below Send notification when post is published for details.

Send notification to Mobile app subscribers

If you setup OneSignal on a mobile app to accompany your website and it uses the same OneSignal App ID, then you can send push notifications to that mobile app when publishing a post using this option.

7. Complete migration in WordPress

If you upgraded from a previous version of our WordPress plugin, then follow this guide, otherwise, skip to the next section.

As soon as you save your configuration in the OneSignal.com dashboard, navigate back to WordPress to select "Migration Completed" and complete your plugin upgrade.

❗️

Ensure you select "Migration Completed"

Quickly complete these steps to avoid users missing any notifications.

👍

Basic WordPress setup complete

Click Save Settings to complete plugin setup!

---

Test

Visit your website. Make sure you do not use an incognito or private browser mode. Users cannot subscribe to your site in these modes.

You should see the slidedown prompt appear on your site. Select the "OK" button, in this example set to "Subscribe".

Next you will see the Native Permission Prompt. This prompt is required for users to select "Allow" to be subscribed to push notifications on your site. Click Allow.

You should also see the Welcome Notification appear if you have that setup.

Within the OneSignal dashboard, go to Audience > Subscriptions. You should see your web push Subscription marked as Subscribed.

Still within the OneSignal dashboard, navigate to Messages > Push and create a New Message. Test sending it to yourself. See Push for details.

👍

Testing complete!

You have successfully setup and tested your WordPress site! You will start to see Subscriptions for your users as they subscribe to your site.

Review our Web permission prompts guide for more ways to customize your prompts.

If you follow other Channel setup docs, you will also see Subscriptions for mobile push, email and SMS show up in the Subscriptions page.

📘

Not seeing the prompts or Subscriptions?

Head over to our WordPress troubleshooting docs to debug your setup.

---

Send notification when post is published

While creating a Post in WordPress, you should see a metabox for at the bottom or right-hand side of the post page OneSignal Push Notifications.

If you want to move this metabox to the right-hand side, simply drag it there.

To send a push when the post is published or updated, ensure Send notification when post is published or updated, is checked. If you do not want to send a push, then uncheck the box.

Send to segment

You can send to all push Subscriptions by default or choose a specific audience Segment to target. You can create and manage your segments in the OneSignal Dashboard > Audience > Segments.

If you followed the example Step 3. Permission prompt setup above, then you should have 2 tags:

• news : 1
• deals : 1

In your OneSignal dashboard Audience > Segments create 2 segments using "Tag news is 1" and the other segment "Tag deals is 1". Note that tags are case sensitive! news and News are 2 different tags.

Name the segment something you can identify later in your WordPress site.

After you Create Segment, return to your blog post and refresh the page. You should see the new Segment in the drop down.

👍

Update segments and tags.

You can create Segments with more options than tags. You will notice your site already has some default segments available. You can update these segments or add more.

Tags are the best way to set custom data on your users for segments and message personalization.

Customize notification content

By default, a notification will automatically use the post's title as the message and the "Site Title" found in your WordPress Settings > General tab as the push title. It will also include an image if there is a featured image.

You can customize the Title and Content of a notification by checking Customize notification content.

Mobile URL

If you have a mobile app that accompanies your website, you can send push to the mobile push Subscriptions and include a different URL. This is helpful if you want to implement Deep Linking in your app to navigate to a specific page of your app instead of opening the URL in a web browser, which is the default behavior.

👍

Sending push through WordPress complete!

You can now send push using other methods outlined in our Push and Journeys docs.

🚧

Not seeing notifications?

Check our Web push: Notifications not shown guide to troubleshoot.

---

FAQ

How do I disable push prompt on certain pages?

Currently this is only available if you use the slidedown prompt or native permission prompt. It will not work for the bell prompt or custom link prompt.

1. Within your OneSignal dashboard navigate to Settings > Push & In-App > Web Settings

2. Select the prompts listed in the table under Permission Prompt Setup

3. Deselect the Auto Prompt option and press Done.

   

4. Scroll down and press Save, then Finish. This disables the prompt from automatically showing.

5. Within your WordPress site's JavaScript code editor, add the Slidedown prompt code to the specific pages you want the prompts to show.

You can now control when to display the prompts through your custom JavaScript methods. See Web permission prompts for more details.

How do I send push notifications to my mobile app subscribers?

If you also have a mobile app set up in OneSignal that's separate from your Website, you can select Send notification to Mobile app subscribers in the plugin settings screen to include subscribers to your mobile app in your audience.

In the OneSignal Push Notifications metabox, you can choose a different URL for your Mobile app subscribers (Deep Link). If you do not include a different URL, it will direct them to your Website instead of a specific page of your app.

How do I send email or sms from the WordPress plugin?

Currently this is not an option. You will need to follow Email setup and/or SMS setup to get started. Then you can send these types of messages using our options described in Email and SMS docs.

Why do my prompts not appear to be working after the migration?

If you have caching rules set up on your WordPress site (e.g. .htaccess file), this may delay seeing the results of the migration when testing. Disable the browser cache to force updated files to be loaded.

To disable cache, right-click anywhere on your WordPress site to open "Inspect" > Network tab in your developer console.

"A bad HTTP response code (404) was received when fetching the script." / service worker failed

This occurs when you have saved your configurations in the dashboard but have not yet selected "Migration Completed" in the WordPress plugin. Make sure you've selected "Migration Completed" in the WordPress Plugin to complete your upgrade.