Notifal REST API Reference (notifal/v1)

Notifal registers REST routes under the namespace notifal/v1. Base URL:

/wp-json/notifal/v1/

Unless noted, public frontend routes use permission_callback => __return_true and rely on server-side eligibility checks rather than WordPress login.

Implementation: ApiRegistrar.php (on-page), TagsApiRegistrar.php, DynamicKeysApiRegistrar.php.

On-page notifications

`GET /onpage/eligible`

Returns notifications eligible for the current visitor context.

Query parameters (context):

Parameter	Type	Description
`page_id`	int	Current post ID
`url`	string	Current page URL
`user_id`	int	Logged-in user ID
`device_type`	string	`desktop`, `mobile`, or `tablet`
`post_type`	string	Singular/archive context post type
`archive_taxonomy`	string	Taxonomy on archive views
`categories`	string	Comma-separated category IDs
`product_categories`	string	WooCommerce product category IDs
`user_roles`	string	Comma-separated role slugs
`is_front_page`, `is_shop_page`, `is_cart_page`, etc.	string	Boolean flags from frontend context
`refresh_notification_id`	int	Re-fetch one notification (retrigger)
`client_seen_sources`	string	JSON for content-source rotation
`cache_bust`	string	Cache bypass token

Filters: notifal/onpage/eligibility/data, actions notifal/onpage/eligibility/before_process / after_process.

Used by: frontend notification-manager.js (apiEndpoint in localized config).

`GET /onpage/preview`

Admin preview of a single notification (same shape as eligible items).

Parameter	Required	Description
`id`	yes	Notification post ID
`_preview_token`	no	Preview security token
`device_type`	no	`desktop`, `mobile`, `tablet`

`POST /onpage/track`

Records impression, click, close, or dismiss events.

Body field	Required	Description
`notification_id`	yes	Notification post ID
`event_type`	yes	`impression`, `click`, `close`, `dismiss`
`timestamp`	no	Unix timestamp (default: now)
`user_agent`	no	Client user agent
`referrer`	no	Referrer URL
`page_url`	no	Page where event occurred

Filters: notifal/onpage/tracking/data, notifal/onpage/tracking/use_queue, notifal/onpage/tracking/validation/rules.

Actions: notifal/onpage/tracking/before_process, notifal/onpage/tracking/event_stored.

`GET /onpage/preferences`

Returns stored visitor notification preferences (consent / frequency).

`POST /onpage/preferences`

Updates preferences.

Body field	Type	Description
`preferences.enabled`	bool	Master preference toggle
`preferences.frequency`	string	`low`, `medium`, `high`
`preferences.categories`	string[]	Opt-in categories

`GET /onpage/cart-context`

WooCommerce cart snapshot for client-side cart display rules (when WooCommerce is active).

Returns normalized cart data used by frontend rule evaluation. Filter: notifal/onpage/woocommerce/cart_context.

Tags and dynamic keys

`GET /tags`

Returns all registered tags grouped by category for builders and admin pickers.

Filter: notifal/tag/api/modify_response.

Permission: public read.

`GET /dynamic-keys`

Search/list meta keys for dynamic tag configuration in admin.

Permission: edit_posts.

Filters: notifal/dynamic_keys/most_used, notifal/dynamic_keys/search_results.

Templates (additional routes)

Route	Method	Purpose
`/templates/preview`	GET	Template preview iframe/API
`/featured-image-preview`	GET	Featured image preview helper

Registered under app/Modules/Templates/Infrastructure/WordPress/Registration/.

Rate limiting and security

Eligibility and track endpoints support configurable rate limits via notifal/onpage/api/rate_limit_settings.
Always validate and sanitize data in filters; do not expose privileged meta in API responses.
Admin-only routes should keep strict permission_callback checks (see dynamic-keys).

Example: read eligible notifications in PHP

add_action( 'rest_api_init', function () {
    // Prefer hooks over duplicating eligibility logic.
} );

add_filter( 'notifal/onpage/eligibility/data', function ( $data, $context ) {
    // $data: notifications array prepared for frontend.
    // $context: resolved page context.
    return $data;
}, 10, 2 );

For changing a single notification payload, use notifal/onpage/notification/content instead (see cookbook).

Hub

Resources

REST API Reference