Quickstart

Add the chat to your app in about ten minutes. Every platform uses the same App ID and the same inbox.

1. Create the app. In the dashboard, open Settings › Apps › New app and copy its App ID (app_…). It's public, so it can live in your code.
2. Install the SDK for your platform below.
3. Open the chat from a help button, your settings screen or a "Need help?" bar.

iOS

iOS 16 or later. In Xcode, choose File › Add Package Dependencies… and add the Hailbell package from your welcome email. Add the Hailbell library to the app target.

// AppDelegate, at launch
import Hailbell

Hailbell.configure(appId: "app_XXXXXXXX")
Hailbell.setMetadata(["plan": "free"])

// From any help button
Hailbell.shared.open()

Prefer SwiftUI? Place HailbellChatView() yourself. Hailbell.shared.unreadCount is published, so you can show a badge.

Android

minSdk 26 with Jetpack Compose. Add the Hailbell module to your Gradle build, then configure it in Application.onCreate().

// settings.gradle.kts
include(":hailbell")

// app/build.gradle.kts
dependencies { implementation(project(":hailbell")) }

Hailbell.configure(context, "app_XXXXXXXX")
FirebaseMessaging.getInstance().token.addOnSuccessListener { Hailbell.setPushToken(it) }

// From any help button
Hailbell.open(activity)

Web

One script tag. The widget runs in a shadow root with no inline scripts or styles, so it works under a strict CSP.

<script src="https://api.hailbell.com/widget.js" data-app-id="app_XXXXXXXX" defer></script>

Use data-launcher="none" to open it from your own button with Hailbell.open(). Pass context such as data-meta-plan="pro". For CSP, allow https://api.hailbell.com in script-src, style-src and connect-src, plus wss://api.hailbell.com.

Signed-in users

Without sign-in, a chat belongs to the install. To follow a user across devices, your backend signs an HS256 JWT with the app's identity secret, with sub set to your user id.

Hailbell.identify(identityToken: token)        // iOS
Hailbell.identify({ identityToken: token })    // Web

Apps on Firebase Auth can skip the backend and pass the user's Firebase ID token instead. Call Hailbell.reset() on sign-out and Hailbell.deleteData() when a user deletes their account.

Push

Replies arrive as a push when the chat is closed. Campaigns go out from the dashboard, the API or an agent, with variables like {{first_name|there}}, {{city}} and the local weather, delivered at each person's local time.

// iOS: didRegisterForRemoteNotificationsWithDeviceToken
Hailbell.setPushToken(deviceToken)
// When a Hailbell notification is tapped
Hailbell.handleNotification(userInfo)

On the web, add hailbell-push.js next to the widget and serve /hailbell-sw.js containing importScripts('https://api.hailbell.com/push-sw.js');.

Offers and reviews

An offer is a message with a button that opens one of your paywalls. Tell Hailbell which placements exist and how to open them:

Hailbell.setPaywallPlacements(["winback", "support_offer"])
Hailbell.onPaywall = { placement, purchased in
    // open your Superwall or RevenueCat paywall, call purchased() if they buy
}

Review requests need only your App Store ID or Play package in the dashboard. The button opens the store's review sheet. Only ask happy users, and never offer anything for a review.

AI replies

Turn on AI replies per app and write a short knowledge note: prices, plans, refunds, known issues. When nobody answers within your wait time, the AI replies in the user's language using only that note and the conversation, and hands the chat to you when it can't help. Every AI reply is labelled, as App Review asks.

API and MCP

Everything the dashboard does is in the REST API and the MCP server. Create an API key on the Push page.

curl https://api.hailbell.com/v1/notifications \
  -H "Authorization: Bearer hbk_…"

Spec: openapi.json. Agents: add https://api.hailbell.com/mcp as a connector and sign in. Broadcasts need a preview first, so an agent can't send to everyone by accident.