Quick start

The fastest path to a working web push integration. You install one package for your stack, get a subscriber registered from the browser, and send the test push from the dashboard. By the end you'll have an opt-in prompt on your site, a subscriber, and a notification delivered to your browser.

What you'll need

An HTTPS site (service workers refuse to register on plain HTTP).
A free ReachBell account — sign up here if you don't have one.
About five minutes.

1. Create a project

After signing in, the dashboard prompts you to create your first project. A project corresponds to one website or app — its VAPID keys, API key, and subscriber list are isolated from every other project in your organization.

Pick a name, paste your site's URL, and hit Create. You'll land on the project's integration guide.

2. Install one package for your stack

You only need one package — the one that matches your stack. Each wraps the same core SDK, so the capabilities (prompt, identify, tag, in-page widgets) are identical. You do not also install the Server API for this.

A. Vanilla JavaScript — `@reachbell/sdk`

Drop two lines into the <head> of every page:

<script src="https://app.reachbell.com/reachbell.js" defer></script>
<script>
  window.addEventListener("DOMContentLoaded", () => {
    ReachBell.init({
      apiKey: "rb_live_yourkey",
      autoPrompt: true,
    });
  });
</script>

Prefer a bundler? npm install @reachbell/sdk and import { ReachBell } from "@reachbell/sdk" instead. Either way, copy reachbell-sw.js from the dashboard integration page into the root of your site — it must be served from the root, not a subfolder, because a service worker's scope is bound to where it's served from.

B. React — `@reachbell/react`

npm install @reachbell/react @reachbell/sdk

import { ReachBellProvider } from "@reachbell/react";
 
export default function App({ children }) {
  return (
    <ReachBellProvider apiKey="rb_live_yourkey" autoPrompt>
      {children}
    </ReachBellProvider>
  );
}

The React guide goes deeper. Same reachbell-sw.js requirement.

C. Vue — `@reachbell/vue`

npm install @reachbell/vue @reachbell/sdk

import { createApp } from "vue";
import { ReachBellPlugin } from "@reachbell/vue";
import App from "./App.vue";
 
createApp(App)
  .use(ReachBellPlugin, { apiKey: "rb_live_yourkey", autoPrompt: true })
  .mount("#app");

The Vue guide covers the composables. Same reachbell-sw.js requirement.

D. Next.js — `@reachbell/nextjs`

npm install @reachbell/nextjs @reachbell/react @reachbell/sdk

Drop the provider in a "use client" component (the Next.js guide has the full layout wiring), and place reachbell-sw.js in public/.

E. WordPress

Install the ReachBell plugin from the WordPress.org plugin directory. Go to Settings → ReachBell, paste your API key, and save. The plugin handles the SDK enqueue and serves the service worker from the site root via a rewrite rule — no copying files yourself.

The one step everyone forgets (all stacks except WordPress): reachbell-sw.js must be served from your site's root — https://yoursite.com/reachbell-sw.js, not a subfolder. A service worker's scope is bound to where it's served from, so a misplaced file silently breaks subscriptions. Confirm the URL loads in your browser before moving on — this is the #1 reason a first push never arrives.

3. Configure the opt-in prompt

In the dashboard, head to Configure → Prompt designer. The default soft prompt asks "Stay in the loop?" with two CTAs — Allow and Not now. Customize the headline, body, accent colour, and position. Hit Save.

The SDK fetches this configuration on page load via GET /projects/context, so design changes appear on customer sites without a code redeploy.

Modern browsers require a user gesture to show the native permission dialog. The SDK handles this automatically when autoPrompt: true is set — it arms a one-shot click/key/touch listener so the prompt fires on the user's first interaction rather than at page load.

Open your site in a fresh browser window. Within a few seconds you should see the soft prompt. Click Allow — the SDK then triggers the browser's native dialog and registers your device.

Head back to the dashboard. The Subscribers page should show your subscription within a few seconds.

5. Send a test push (from the dashboard)

Sending is a dashboard action — you don't write any API calls for it. In the dashboard:

Go to Push → Compose.
Add a title and body.
In the targeting step, scope it to your subscription via the "Targeted devices" filter — or leave it empty to send to all.
Click Send now.

Your browser should receive the notification within a few seconds. If it doesn't, check the troubleshooting tips below.

What's next?

Read Concepts to understand how the SDK (client) and dashboard (sending) divide the work.
Wire up identification so subscribers are linked to your internal user IDs from the browser.
Add in-page widgets — toasts, banners, and a notification center — straight from the same package.
Build audiences and a welcome series in the dashboard with segments and the automation builder.

Troubleshooting

Nothing happened when I clicked Allow. Check the browser console for errors. The most common cause is that reachbell-sw.js isn't reachable at the site root — visit https://yoursite.com/reachbell-sw.js directly to confirm.

The native permission dialog never appeared. Chrome and Edge require a user gesture. With autoPrompt: true the SDK fires on the first click/key/tap — try clicking somewhere on the page.

The subscription registered but the push didn't deliver. Check Settings → Delivery policy for frequency caps or quiet hours that might be blocking the send. The Subscribers page shows each subscriber's last error reason in the detail drawer.

Introduction

Concepts