Voxel OneSignal Addon
The {CODICTS} Voxel OneSignal Addon plugin bridges the Voxel Theme and OneSignal to deliver web and mobile push notifications triggered by Voxel’s built-in app events. When something happens on your site — a new message, a booking, a post creation — the plugin automatically sends a push notification to the right user through OneSignal. No custom code required.
Installation & Activation
Start by downloading the plugin from the Downloads page on your dashboard on the CoDicts website.
After downloading, install and activate the plugin in WordPress by navigating to “Plugins” > “Add New” > “Upload Plugin” and selecting the downloaded zip file. Click “Install Now” and then “Activate”.
Once activated, navigate to “OneSignal Addon” in the WordPress admin sidebar to configure your settings.
Important: Before using this plugin, make sure the OneSignal plugin is installed and configured with your OneSignal App ID and REST API Key. The CoDicts plugin reads these credentials from the OneSignal plugin — it does not store them separately.
How It Works
The plugin connects Voxel’s app event system to OneSignal’s push notification API. It supports two notification paths:
| Notification Type | Trigger | Recipients | Use Case |
|---|---|---|---|
| Individual | Any Voxel app event with in-app notifications enabled | The specific user who should receive the notification | New message received, booking confirmed, post approved, etc. |
| Broadcast (All) | A new post is created and published for an enabled post type | All OneSignal subscribers | New listing added, new event posted, new article published |
Individual notifications work automatically — every Voxel event that has in-app notifications enabled will also trigger a push notification to the recipient.
Broadcast notifications must be enabled per post type in the plugin settings (see below).
User Identification
For individual notifications to reach the right person, the plugin automatically identifies logged-in users with OneSignal using their WordPress user ID as a OneSignal External User ID. This happens in the background on every page load — no setup required from you or your users.
When a user visits your site while logged in, the plugin registers their device with OneSignal. When they log out, the association is cleared. This means users must have visited your site at least once while logged in for individual push notifications to reach them.
Settings
Navigate to “OneSignal Addon” in the WordPress admin sidebar to configure the plugin.
Deep Link URL
If you have a mobile app, enter your app’s deep link schema (e.g., myapp://example.com). When set, notification URLs are converted from web URLs to app deep links, so tapping a notification opens the content directly in your native app.
Leave this blank if you don’t have a mobile app — notifications will open in the browser.
| Setting | Description |
|---|---|
| Deeplink URL | Your app’s deep link schema prefix (e.g., myapp://example.com). |
| Simple URL for APP URL | When enabled, web URLs are converted to a structured format using post type and post ID instead of the page slug. |
| Custom Query Parameters | Define the deep link structure using placeholders: {post_type} and {post_id}. Example: ?post_type={post_type}&post_id={post_id} |
Tip: If you have specific URLs that should always open in a browser instead of the app, add
is_web=trueas a URL parameter. The plugin will skip deep link conversion for those URLs.
Broadcast Notifications per Post Type
For each Voxel post type, you can enable broadcast notifications that go to all subscribers whenever a new post of that type is created and published.
| Setting | Description |
|---|---|
| Enable Toggle | Turn on/off broadcast notifications for this post type. |
| Subject | Notification heading template. Supports Voxel Dynamic Tags. Default: A new post has been created - @post(title) |
| Message | Notification body template. Supports Voxel Dynamic Tags. |
The subject and message fields support Voxel Dynamic Tags for personalized content. Common tags include:
| Tag | Output Example |
|---|---|
@post(title) | Joe’s Coffee Shop |
@post(:category) | Restaurants |
@author(display_name) | Jane Smith |
@site(title) | My Directory |
If the post has a featured image, it is automatically attached to the notification.
Segment Name
| Setting | Default | Description |
|---|---|---|
| Segment Name | All | The OneSignal segment used for broadcast notifications. Change this if you want to target a specific segment instead of all subscribers. |
Deferred Notifications
Stagger notification delivery with a random delay to prevent notification storms — especially useful for broadcast notifications.
| Setting | Description |
|---|---|
| From | Minimum delay in seconds before sending. |
| To | Maximum delay in seconds before sending. Must be equal to or greater than “From”. |
Each notification is delayed by a random value between these two numbers. Set both to 0 for near-immediate delivery (1-second minimum).
Individual Notifications (Automatic)
Individual push notifications work automatically for every Voxel app event that has in-app notifications enabled. You don’t need to configure anything specific — if Voxel sends an in-app notification, this plugin sends a matching push notification.
Examples of events that trigger individual push notifications:
| Event | Recipient |
|---|---|
| New direct message received | The message recipient |
| Booking confirmed/declined | The customer |
| Post approved/declined | The post author |
| New review received | The listing owner |
| New order placed | The vendor |
The notification uses the same subject and details as Voxel’s in-app notification. The site icon is used as the notification icon, unless the event provides its own icon.
Broadcast Notifications (New Posts)
When enabled for a post type, broadcast notifications are sent to all OneSignal subscribers whenever a new post of that type is created and published — whether from the Voxel frontend submission form or from the WordPress admin.
Broadcast notifications only fire once per post — on the first publish. Updating an already-published post does not trigger another broadcast. This is tracked with an internal flag on each post.
Note: If you need to send a broadcast for an already-published post, use the manual “Notify All Users” button (see below).
Manual “Notify All Users”
A “{C} Notify All Users” meta box appears on the sidebar of every post edit screen in the WordPress admin. Clicking the “Notify All Users” button sends a push notification to all subscribers for that specific post.
This is useful for:
Sending a notification for a post that was published before the plugin was installed. Re-notifying all users about an updated or featured post. Sending notifications for posts that were published without the broadcast toggle enabled.
Warning: This is a force push — it sends to all subscribers immediately without the deferred delay or the condition filter. Make sure to save the post before clicking the button. You will be asked to confirm before sending.
Duplicate Prevention
The plugin includes multiple layers of protection against duplicate notifications:
| Mechanism | What It Prevents |
|---|---|
| Idempotency keys | UUID-based keys sent to OneSignal prevent the same notification from being delivered twice. |
| First-publish flag | A post meta flag ensures broadcast notifications only fire on the first publish, not on updates. |
| Schedule check | Before scheduling a notification via WP-Cron, the plugin checks if an identical event is already scheduled. |
Notification Condition Filter (For Developers)
Developers can conditionally block broadcast notifications using a PHP filter. This is useful for business logic like “only notify for featured posts” or “only notify for posts in certain categories.”
add_filter('codicts-voxel-onesignal-addon::create_notification_condition', function($condition, $post_id) {
// Only send notifications for posts tagged as 'featured'
if (!has_term('featured', 'category', $post_id)) {
return false; // Block the notification
}
return $condition;
}, 10, 2);When a notification is blocked by this filter, the post is flagged internally and the notification is silently skipped.
Developers can also customize the post type priority for deep link slug resolution:
add_filter('codicts-voxel-onesignal-addon::priority_url_map', function($types) {
return ['places', 'events', 'post']; // Check these post types first when resolving slugs
});Troubleshooting
“Voxel Theme Not Detected” Error
Ensure the Voxel Theme is installed and set as the active theme (or parent theme if using a child theme).
“OneSignal Push Notifications Plugin Not Detected” Error
Install and activate the OneSignal Free Web Push Notifications plugin from the WordPress plugin directory. Make sure it is configured with your OneSignal App ID and REST API Key.
Notifications Not Being Sent
Check the following common causes:
| Cause | Solution |
|---|---|
| OneSignal credentials missing | Verify your App ID and REST API Key are set in the OneSignal plugin settings. |
| Post type not enabled | For broadcast notifications, enable the post type in the plugin settings. |
| Post not published | Broadcast notifications only fire for posts with “publish” status. |
| Post already published once | The first-publish flag prevents re-triggering. Use the manual “Notify All” button instead. |
| Condition filter blocking | Check if any custom create_notification_condition filter is returning false. |
| WP-Cron not running | Notifications are scheduled via WP-Cron. If your site has very low traffic, consider setting up a server-side cron job. |
Notifications Going to Wrong Users
Push notifications target users by their OneSignal External User ID, which is set when users visit your site while logged in. If a user has never visited while logged in, their device isn’t linked to their account. Check the browser console for OneSignal login errors.
Deep Links Not Working
| Cause | Solution |
|---|---|
| Deep link URL not set | Enter your app’s deep link schema in the plugin settings. |
is_web=true in the URL | This parameter intentionally bypasses deep linking. Remove it if you want deep links. |
| Post not found from slug | Ensure the post exists and has a valid permalink. Try enabling “Simple URL” mode with custom query parameters. |
“Notify All Users” Button Not Working
Make sure the post is saved before clicking the button. Check the browser console for JavaScript errors. If the page has been open for a long time, refresh it first — the security token may have expired.
Duplicate Notifications
The plugin has multiple deduplication mechanisms (idempotency keys, first-publish flag, schedule checks). If you’re still seeing duplicates, check for other plugins that might be firing Voxel events multiple times, or browser extensions that might be re-triggering page requests.
For further support, visit codicts.com or contact us at support@codicts.com.