Hailbell

npx add-mcp 'https://api.hailbell.com/mcp'

Quickstart

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

1. Sign in. Open app.hailbell.com and choose Continue with Google, or type your email and use the sign-in link it sends. Your first sign-in makes a Hailbell account with a 14 day free trial. No card needed. If a teammate invited you, you join their account instead.
2. Create the app. The first-run setup asks for a name for your account, then finds your app on the App Store (or takes the name of one that isn't there yet) and shows its App ID (app_…). The App ID is public, so it can live in your code. Add more apps later under Settings › Apps › New app, or let your agent make them (see Use Hailbell from your agent).
3. Install the SDK for your platform below.
4. Open the chat from a help button, your settings screen or a "Need help?" bar.

The dashboard then shows a checklist for the rest: install the SDK, upload push keys, connect Discord or Telegram, turn on AI replies and connect your agent.

iOS

iOS 16 or later. In Xcode, choose File › Add Package Dependencies… and enter https://github.com/vidursaini/hailbell-ios, and pick Up to Next Major Version from 1.1.1. 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. The library is on JitPack. Add the JitPack repository and the dependency, then configure it in Application.onCreate().

// settings.gradle.kts, inside dependencyResolutionManagement { repositories { … } }
maven { url = uri("https://jitpack.io") }

// app/build.gradle.kts
dependencies { implementation("com.github.vidursaini:hailbell-android:1.1.0") }

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

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

Flutter

iOS 16 and Android 8 (API 26) or later, Flutter 3.27 or later. The plugin wraps the iOS and Android SDKs, so your customers get the same native chat. Add it with flutter pub add hailbell, set minSdk = 26 in android/app/build.gradle.kts and the iOS deployment target to 16.0.

flutter pub add hailbell

import 'dart:io';

import 'package:hailbell/hailbell.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Hailbell.configure(appId: Platform.isIOS ? 'app_IOS_XXXXXXXX' : 'app_ANDROID_XXXXXXXX');
  runApp(const YourApp());
}

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

Hailbell.unreadCount is a ValueListenable<int> for a badge. For push, pass every firebase_messaging message to HailbellPush.handleMessage and the FCM token to Hailbell.setPushToken on Android; on iOS the plugin picks up the APNs token itself. The full guide, with push, signed-in users and store privacy answers, is in GUIDE.md. Package: pub.dev/packages/hailbell.

React Native

Expo SDK 54 or later with a development build or EAS Build (Expo Go can't load native code), or a bare React Native app after npx install-expo-modules@latest. iOS 16 and Android 8 or later. The package wraps the iOS and Android SDKs, so the chat is the same native screen.

npx expo install @hailbell/react-native

// app.json: configures Hailbell natively at launch and adds the push capability
"plugins": [
  ["@hailbell/react-native", {
    "ios": { "appId": "app_IOS_XXXXXXXX" },
    "android": { "appId": "app_ANDROID_XXXXXXXX" }
  }]
]

import { Hailbell, useHailbellUnread } from '@hailbell/react-native';

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

Run npx expo prebuild or an EAS build after adding the plugin. useHailbellUnread() gives the badge count. Push works with expo-notifications or React Native Firebase; the full guide is in GUIDE.md. Package: @hailbell/react-native.

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');.

One campaign can go to your app's iOS, Android and web platforms at once. In Push › New message, pick the platforms under Platforms. Every platform is picked by default. Sent shows the campaign once, with its numbers for the whole campaign and for each platform. Each platform still sends with its own keys, Firebase project, limits and quiet hours.

• One push per person. A signed-in user gets the campaign once, on the device they used most recently, even with an iPhone and a browser. Installs that never signed in can't be matched across platforms, so each counts as its own person. Test sends go to every test device.
• Daily cap per person. The promotional cap counts each person across all of your app's platforms, so a second platform can't push someone over it. Quiet hours follow the time zone of the device that gets the push.
• Segments and tags. A segment works on every platform, whichever one you made it on. A tag filter matches a signed-in user when the tag is set on any platform.

Push keys

Hailbell sends iOS and Android pushes with your own keys. Upload them in the dashboard under Settings › Push keys. Web push needs no key.

• iOS. An Apple .p8 key with its Key ID and Team ID. Make one in Apple Developer under Certificates, Identifiers & Profiles › Keys with Apple Push Notifications service turned on. If your apps are in different Apple teams, add one key per team. Each app uses the key of its team, matched by its bundle ID.
• Android. A Firebase service account JSON file, one per Firebase project. In the Firebase console, open Project settings › Service accounts and choose Generate new private key. Enter each Android app's Firebase project ID in Push › Setup too, so it uses the key of its project.

Hailbell tries each key with Apple or Google before saving it, stores it encrypted and never shows it again. To replace a key, upload the new one and remove the old one.

Discord and Telegram

Every message lands in the dashboard inbox. Discord and Telegram are optional extra places to answer from, and all three stay in sync.

• Discord. In Settings › Discord, press Connect Discord and pick your server on Discord's page. Then pick a forum channel for each app, or choose Create a forum for this app. Each customer gets their own post in that forum, and your replies in it reach the customer. The bot reads only the posts it creates.
• Telegram. Make a bot with @BotFather, paste its token in Settings › Telegram, then open the bot and press Start. Reply to a customer's message to answer them.

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 for push and AI replies is in the REST API and the MCP server, and so is making apps and platforms. Create an API key under Push › Setup.

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

A call works on the one platform of appId. To send one campaign to several platforms, add "platforms": "all" (or a list like ["ios", "web"]), or pass the app's productId. The campaign gets an id starting with ngr_, and its numbers come back for the whole campaign and per platform. Calls without platforms or productId work as before and send to every matching device of that one platform.

GET /v1/account (get_account over MCP) gives the plan and how many trial days are left. POST /v1/apps (create_app) makes an app with its first platform, from a name, a platform and an iOS bundle ID or Android package name. POST /v1/products/{productId}/platforms (add_platform) adds iOS, Android or web to an app. Making apps needs a key for every app with the manage scope, made by an admin or the owner. Neither returns the identity secret: if your backend signs users in, make one under Settings, the platform's Edit, New identity secret.

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

Use Hailbell from your agent

The Hailbell skill teaches a coding agent (Claude Code, Codex, OpenClaw and others) to set up Hailbell for you: make the app and its platforms, add the SDK, write the AI's how-to guide from your source code and run push campaigns. Install it with one line:

curl -fsSL https://hailbell.com/skills/install.sh | sh

Or tell your agent: Install the Hailbell skill from https://hailbell.com/skills/hailbell/SKILL.md

Then connect the MCP server, https://api.hailbell.com/mcp. It opens a Google sign-in, then asks which Hailbell account the agent may work in. That makes a "Connected agent" key in the account, which you can revoke under Push › Setup. Only admins and the owner of an account can connect an agent to it. It stops working if you leave the account or become an agent there.

The agent checks your plan and trial, makes the app in Hailbell if it isn't there yet, writes the code and the AI replies texts. You do the parts that need your accounts or your card: sign up, upload push keys, connect Discord or Telegram, and pick a plan when the trial ends. Never paste a push key, an API key or the identity secret into an agent chat.

Team and billing

Each Hailbell account has its own apps, team, push keys, Discord servers, Telegram bot and AI replies. Invite teammates by their Google email on the Team page, as an admin or an agent. They sign in with Google as that email and join. Everyone signs in with their own Google account, and replies they send carry their name. You can belong to several accounts and switch between them in the sidebar.

There are three roles. Agents work the inbox: they read and answer chats, send review requests and offers, and close chats. Admins also change everything else: apps, Push, API keys, push keys, Discord, Telegram, alerts and the team. The owner can do all that, picks the plan, and is the only one who can hand ownership to someone else. Removing someone signs them out of the account at once and removes the API keys and agents they made there.

The free trial lasts 14 days, with no card, and each person gets one. Accounts you create after your first start without a trial, so pick a plan there to turn Hailbell on. When the trial ends, the dashboard asks you to pick a plan, monthly or yearly. If you don't, the account pauses that day: the SDKs show customers that chat is offline and refuse new messages, replies from the dashboard, Discord, Telegram and agents aren't sent, email to the app's inbox bounces, and campaign pushes and AI replies stop. Nothing is deleted, and picking a plan turns it all back on. The account owner gets an email 3 days before the trial ends and another when it ends.

Stuck? Email hello@hailbell.com and a person will reply.