ReachBellDocs

Concepts

ReachBell has four primary entities. Your SDK package and the dashboard both operate on these — and they split the work cleanly: the SDK is the client side, the dashboard is where you send.

The division of labour

Before the entities, the mental model that makes everything else click:

  • A client SDK (in the browser or the app) creates and labels subscribers. It can prompt and subscribe, identify, tag, and (on the web) show in-page widgets. The browser SDK powers web push; the native mobile SDKs (iOS, Android, Flutter, React Native) do the same job inside an app. That's the whole client surface.
  • The dashboard (app.reachbell.com) does everything else: composing and sending campaigns, building segments, designing templates, and wiring automations. You don't write code for any of it.
  • The Server API is a secondary path for the things a client can't do: server-side transactional sends, reporting events from your backend, and registering subscribers on platforms no SDK covers yet. Most integrations never touch it.

The package's job is to make a subscriber exist and be addressable (via an external id and tags). The dashboard's job is to reach them. Keep that split in mind and the rest of these docs map straight onto it.

Organization

An organization is a team or company account. It owns billing, member access, and a list of projects.

  • Created when you sign up. Every user belongs to at least one organization.
  • Members have roles: OWNER, ADMIN, MEMBER, VIEWER. Viewer is read-only.
  • The organization holds the billing plan (Free, Starter, Growth, Business, Enterprise) and its usage counters reset at the start of each billing period.

Project

A project corresponds to one website or app inside an organization. It's the unit of isolation — VAPID keys, API key, subscriber list, campaigns, and channel credentials all live on the project.

  • Has its own API key (rb_live_… or rb_test_… for sandbox projects). This is the public key your SDK package initialises with.
  • Has its own VAPID keypair (auto-generated on creation).
  • Channel credentials (FCM service account, APNs .p8, SES verified domain, WhatsApp token, SMS provider key) are encrypted at rest with the platform's ENCRYPTION_KEY and never returned in any GET response.
  • A subscriber belongs to exactly one project. Cross-project sharing is not supported by design.

Multi-site teams should create one project per site. Trying to share subscribers across sites breaks subscriber attribution and makes per-site quiet-hours or frequency-cap policies impossible to enforce.

Subscriber

A subscriber is one end user who has opted in on a project's website or app. The SDK package creates the record when the user accepts the prompt; you enrich it from the same package. Each subscriber record carries:

  • A token — the push subscription credential. For web push it's a VAPID subscription created by the browser SDK; for mobile it's the FCM/APNs device token registered by the native mobile SDK; for email it's a verified address.
  • An external id (optional) — your internal user id. Link it from the browser via ReachBell.identify(userId) after login so the dashboard can target the right person.
  • Tags — free-form labels for segmentation (premium, india, cart-abandoned), set from the browser via ReachBell.tag([...]).
  • Geo + UA enriched at subscription time (country, city, browser, OS, device type).
  • Preferences — per-channel + per-category opt-in state, plus a pauseUntil mute timestamp from the preference center.

The subscriber lifecycle is: active → unsubscribed (user opted out) or dead (provider rejected three consecutive sends). Dead tokens are kept for 30 days then purged by a nightly cron, so re-subscribers don't conflict with their stale record.

Campaign

A campaign is one targeted send — push, email, WhatsApp, or SMS. You create campaigns in the dashboard, not from the SDK. They can be:

  • Immediate — fired the moment you hit Send.
  • Scheduled — parked with sendAt and a timezone; a cron sweeps every minute and dispatches when due.
  • Triggered — fired from an automation step rather than the campaign list.

Campaigns carry their targeting (segment), content per channel, UTM parameters appended to click URLs, and an optional A/B test split — all configured in the dashboard's campaign builder.

How they fit together

Organization
├── Project A  ── API key, VAPID keys, channel credentials
│   ├── Subscribers     ← created + labelled by the SDK package (client)
│   ├── Campaigns       ← composed + sent in the dashboard
│   ├── Templates       ← built in the dashboard
│   ├── Segments        ← built in the dashboard (from SDK-set tags)
│   ├── Automations     ← built in the dashboard
│   └── Webhooks
├── Project B
└── Project C

Members (with role: OWNER / ADMIN / MEMBER / VIEWER)
Billing (plan, usage, invoices)

The dashboard and the Server API authenticate differently. Dashboard (browser) calls use a JWT plus an x-org-id header that says which organization is operating; the server validates that org owns the project before accepting the request. The Server API path uses a project-scoped API key (x-api-key) instead — the key already identifies the project, so these calls don't send x-org-id. See Authentication for both modes.

What's next?

  • Walk through the Quick start to install your package and put a project together end-to-end.
  • See SDK installation for the one-package-per-stack paths plus identify, tag, and in-page widgets.
  • Turn your SDK-set tags into audiences with Segments.
  • Building a mobile app? Install a native mobile SDK (iOS, Android, Flutter, React Native).
  • Need server-side transactional sends? Read Authentication in the secondary Server API section.
Previous

Quick start

Next

SDK installation