WordPress

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.

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

Click Done when you've finished configuring the prompt.

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.

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:

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.

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

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 is 1
- Deals Segment: Tag deals is 1

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?

Can I send notifications to mobile app subscribers?

How do I send email or SMS from WordPress?

Why aren't my prompts working after migration?

What does `A bad HTTP response code (404)` error mean?

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

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

What’s New in Version 3+

Prerequisites

Setup

1. Configure WordPress in OneSignal Dashboard

Site setup

Permission prompts

Welcome notification

2. Configure WordPress plugin

Advanced settings

URL parameter tracking

Additional settings

3. Complete migration (Upgrading Users Only)

Testing your setup

Publishing notifications

Basic post notifications

Audience targeting

Send to all subscribers (default)

Send to specific segments

Customizing notification content

Default behavior

Custom content

Mobile app integration

FAQ

First steps & settings

Message channels

Journeys

Audience & custom events

Analytics & Integrations

Privacy & Security

​What’s New in Version 3+

​Prerequisites

​Setup

​1. Configure WordPress in OneSignal Dashboard

​Site setup

​Permission prompts

​Welcome notification

​2. Configure WordPress plugin

​Advanced settings

​URL parameter tracking

​Additional settings

​3. Complete migration (Upgrading Users Only)

​Testing your setup

​Publishing notifications

​Basic post notifications

​Audience targeting

​Send to all subscribers (default)

​Send to specific segments

​Customizing notification content

​Default behavior

​Custom content

​Mobile app integration

​FAQ

What’s New in Version 3+

Prerequisites

Setup

1. Configure WordPress in OneSignal Dashboard

Site setup

Permission prompts

Welcome notification

2. Configure WordPress plugin

Advanced settings

URL parameter tracking

Additional settings

3. Complete migration (Upgrading Users Only)

Testing your setup

Publishing notifications

Basic post notifications

Audience targeting

Send to all subscribers (default)

Send to specific segments

Customizing notification content

Default behavior

Custom content

Mobile app integration

FAQ