ReachBellDocs

WordPress integration

The official ReachBell WordPress plugin handles the entire integration for you — SDK enqueue, service worker hosting, and optional auto-notifications on publish. No template edits, no FTP, no copying files into the site root by hand.

Install

  1. In your WordPress admin, go to Plugins → Add New.
  2. Search for ReachBell in the plugin directory.
  3. Click Install Now, then Activate.

You can also download the plugin zip from the WordPress.org plugin directory and upload it via Plugins → Add New → Upload Plugin if your environment blocks direct installs.

Configure your API key

After activation a new menu entry appears under Settings → ReachBell. Open it and paste your project's API key from the dashboard integration page.

Settings → ReachBell → API key:  rb_live_yourkey

Save the page. The plugin now:

  • Enqueues reachbell.js on the front end of your site, wired to your key.
  • Serves reachbell-sw.js from the site root via a rewrite rule (more on this below).
  • Adds an admin notice if anything is misconfigured.

Prompt behaviour

By default the plugin enables autoPrompt. The SDK arms a one-shot user-gesture listener and shows the soft prompt configured in the ReachBell dashboard on the visitor's first click, tap, or keypress. To switch to manual triggering — for example, if you want to gate the prompt behind a custom CTA button on a marketing page — turn off Auto prompt on first interaction in the plugin settings.

With auto-prompt disabled you can fire the prompt yourself from any theme template or page-builder block:

<button id="rb-enable">Get notified</button>
<script>
  document.getElementById('rb-enable').addEventListener('click', () => {
    window.ReachBell?.prompt();
  });
</script>

The plugin enqueues the SDK with defer, so the global is guaranteed to exist by the time the user can click.

How the service worker is served

A service worker has to be served from the same scope it's meant to control. For a WordPress site the right scope is the whole site, which means the worker file needs to live at the site root — even though WordPress wants to route every request through index.php.

The plugin solves this by registering a rewrite rule that intercepts GET /reachbell-sw.js, returns the worker file's contents, and sets the right headers:

  • Content-Type: application/javascript
  • Service-Worker-Allowed: /
  • Cache-Control: public, max-age=3600

The Service-Worker-Allowed: / header is what lets the worker claim root scope even though it's technically being delivered through a non-root URL handler.

If the rewrite returns 404, your permalink rules are likely stale. Go to Settings → Permalinks and click Save Changes — you don't need to change anything, just the act of saving regenerates the rewrite cache. This is a standard WordPress quirk that hits any plugin that registers rewrites on activation.

Notify subscribers on publish

The plugin can send a push notification automatically whenever a post is published. Enable it under Settings → ReachBell → Auto-notify on publish.

When a post moves to the publish status, the plugin schedules a wp-cron event to deliver the push. The send is asynchronous — the editor returns immediately, the cron task fires within a minute or two and calls the ReachBell API. This keeps the publish flow snappy and avoids the editor hanging if the ReachBell API is temporarily slow.

You can customize the notification title and body templates in the plugin settings. The defaults are the post title and an excerpt of the post body, but both fields accept any combination of {post_title}, {post_excerpt}, {site_name}, and {author_name} tokens.

Restricting which posts trigger a push

Out of the box, every published post in the post post type triggers a notification. You usually want tighter rules — for example, only public posts in your news category, never password-protected ones. The settings page exposes:

  • Post types — a checklist of every registered public post type. The plugin only notifies for the ones you tick.
  • Categories — restrict to one or more categories. Leaving the list empty means "all categories".
  • Skip password-protected — when ticked, posts with a password set are silently ignored.
  • Skip private — when ticked, posts with private visibility are silently ignored.

These rules are evaluated at the moment the cron task runs, so flipping a post back to draft inside the cron window cancels the notification.

Re-publishing a post does not re-notify. The plugin records the post IDs it has already notified for in a reachbell_notified_ids option. If you update an existing published post, no new push goes out. To force a re-notify, delete that post's row from the option and re-publish.

Uninstall behaviour

Deactivating the plugin pauses everything but leaves data alone. Uninstalling the plugin (the Delete action from the Plugins page) is destructive — it:

  • Deletes all reachbell_* options from wp_options.
  • Clears any scheduled wp-cron events the plugin registered.
  • Flushes rewrite rules so the /reachbell-sw.js route stops being served.

It does not delete your subscriber list — that lives on the ReachBell side and survives uninstall. If you reinstall the plugin and reconnect with the same API key, your subscribers are still there.

Internationalization

The plugin is fully translatable. All user-facing strings use the reachbell text domain, and the plugin loads its .mo files via load_plugin_textdomain() on the plugins_loaded hook.

Translations from the WordPress.org translate platform are picked up automatically. To ship a custom translation, drop reachbell-{locale}.mo into wp-content/languages/plugins/.

Multi-site

The plugin works for single-site activations on any sub-site of a WordPress Multisite network. Each sub-site holds its own API key and its own subscriber list, isolated through ReachBell's project model.

Network-wide activation is on the roadmap. For now, activate the plugin per sub-site rather than network-wide — network-wide activation will install the plugin but will not centralize configuration across sub-sites. If you need that, drop us a note via the dashboard's support widget.

Linking WordPress users to subscribers

When a logged-in WordPress user grants permission, the plugin calls ReachBell.identify() with that user's ID — so the subscription gets linked back to the WordPress account automatically. The default external ID is wp_user_{ID}, but you can override it via a filter if you'd rather use the user's email, login, or a custom field.

add_filter('reachbell_external_id', function ($default, $user) {
    return $user->user_email;
}, 10, 2);

The filter runs on every page load for logged-in users, so the link survives session changes and password resets.

Verifying the integration

After saving your API key, run through these checks in order:

  1. Visit https://yoursite.com/reachbell-sw.js directly. You should get a JavaScript file, not a 404 or your homepage. If you get a 404, re-save permalinks as noted above.
  2. Open your homepage in a fresh browser window. Within a few seconds the soft prompt should appear (or fire on first interaction, depending on the dashboard's prompt config).
  3. Click Allow through the prompt and the native browser dialog. Check Subscribers in the ReachBell dashboard — your device should be listed.
  4. If you enabled auto-notify, publish a draft post. You should receive a push within a couple of minutes.

Troubleshooting

The soft prompt never appears. Check that reachbell.js is actually being enqueued — view source on any front-end page and look for the script tag. If it's missing, your theme or another plugin may be calling wp_dequeue_script() on it. The plugin's enqueue handle is reachbell-sdk.

The service worker file 404s. Re-save Settings → Permalinks. If that doesn't fix it, check that your .htaccess (or Nginx config) is delegating to WordPress's front controller — some hardened hosting setups intercept root-level .js requests before WordPress sees them. The plugin settings page surfaces a diagnostics card that runs this check for you.

Pushes aren't going out on publish. wp-cron only runs when somebody visits the site. On low-traffic sites the cron queue can sit idle for hours. The fix is to run wp-cron from a real cron job — most hosts expose this as a one-click toggle. See the WordPress handbook's wp-cron page for the curl-based pattern.

What's next?

  • Read the Quick start for an overview of the dashboard's prompt designer and compose flow.
  • Use the Subscribers API if you want to sync WordPress user IDs into the ReachBell subscriber record.
  • Set up an automation to follow a publish push with a re-engagement series.
Previous

Next.js

Next

Domain setup