---
name: hailbell
description: Set up and run Hailbell (hailbell.com), in-app support chat and push notifications for iOS, Android, Flutter, React Native and web apps. Covers the setup an agent can do over the Hailbell MCP server: making the app and its platforms, adding the SDK, writing the AI replies texts and sending pushes. Use when the user wants to add support chat, in-app chat, a help or "Chat with us" button, or push notifications to an app; mentions Hailbell; wants customer messages in a Discord or Telegram support inbox; wants AI support replies; or asks you to write a how-to guide, knowledge notes or saved replies for a support AI. Also use to plan, preview, send or schedule push campaigns through the Hailbell MCP server or API.
---

# Hailbell

Hailbell adds two things to an app:

- **Support chat.** Customers write from inside the app (iOS, Android, Flutter, React Native or a web widget). The team answers from the Hailbell dashboard, a Discord forum thread per customer, or Telegram. A reply reaches the customer live if the chat is open, or as a push notification if it isn't. When nobody answers within a wait time, an AI can reply first from notes and a how-to guide the team writes, and hands the chat back when it can't help.
- **Push notifications.** Campaigns and transactional pushes to iOS (APNs), Android (FCM) and browsers (Web Push), from the dashboard, the REST API or an agent over MCP. Segments, tags, scheduling, each person's local time or usual hour, templates like `{{first_name|there}}`, daily caps and quiet hours.

Hosts you will see:

- `https://app.hailbell.com`: the dashboard, where the person signs up and signs in with Google or an emailed sign-in link.
- `https://api.hailbell.com`: the SDK API, web widget scripts, REST API (`/v1/...`) and MCP server (`/mcp`).

## How the pieces fit

- An **account** holds apps, a team, push keys, Discord servers, a Telegram bot and the AI replies budget. One person can belong to several accounts and switches between them in the dashboard's sidebar. MCP and API keys work inside one account.
- An **app** (one product) has up to one **platform** each for iOS, Android and web. Each platform has its own **App ID** (`app_...`), which its SDK sends. The App ID is public and lives in code.
- The app's name, Discord forum, AI replies, chat design and pinned fields belong to the app and apply to every platform. Bundle ID, review settings, offers, identity secret and the sign-in rule belong to each platform.
- Over MCP and REST, `list_apps` returns one entry per platform. `productId` and `productName` group the platforms of one app.
- A push campaign can go to one platform or to several platforms of one app at once (pass `platforms: "all"` or `productId`). Segments belong to the whole app. See [references/push.md](references/push.md).

## Who does what

You (the agent) can do these yourself:

- Check the account with `get_account`: its plan, whether it's in the free trial and how many days are left. Tell the person when the trial ends and where to pick a plan.
- Make the app in Hailbell with `create_app` (name, first platform, iOS bundle ID or Android package name), and add its other platforms with `add_platform`. Each platform gets an App ID (`app_...`) for its SDK. Call `list_apps` first, so you don't make an app that's already there. You can't delete apps.
- All code: add the SDK, wrap it in one file, add entry points, push handling, sign-in, account deletion, the web script tags.
- Everything on the Push page over MCP or REST: context, preview, send, schedule, test sends, segments, tags, test devices, images, Setup (limits, quiet hours, occasions, web prompt, Android Firebase project and offers channel).
- AI replies settings over MCP (`get_ai_replies`, `update_ai_replies`): the notes, the how-to guide, About the app, plans and prices, the "it should be free" answer, refunds, saved replies, the wait and the name. Turn AI replies on only when the person asks.
- Drafting text for the person to paste: App Store App Privacy answers, Google Play Data safety answers, notes for App Review, the privacy policy paragraph (take the provider list from https://hailbell.com/subprocessors).

The person has to do these in the dashboard or another console. You can't do them over MCP or REST. Ask for all of them in one message, with exact steps:

- Sign up: open `https://app.hailbell.com/?signup=1` and choose **Continue with Google**, or enter an email and press **Email me a sign-in link**. The first sign-in makes a Hailbell account with a 14 day free trial and no card. If a teammate invited them, they sign in as that email and join the teammate's account instead. The dashboard's first-run setup can make the first app too; if they skip it, you make it with `create_app`.
- Connect you: sign in when the MCP connector opens the Hailbell sign-in (Google or an emailed link), and pick the account you should work in. Only an admin or the owner of that account can connect an agent.
- Upload push keys in **Settings › Push keys**: for iOS an Apple `.p8` key with its Key ID and Team ID, for Android a Firebase service account JSON file per Firebase project. Hailbell checks each key with Apple or Google, stores it encrypted and never shows it again. Tell the person where to make the key (see [references/ios.md](references/ios.md) and [references/android.md](references/android.md)), but never ask for a `.p8` file or service account JSON in the chat, and never read, copy or commit one yourself.
- Make an identity secret, only if their backend will sign users in to the chat: **Settings**, the platform's **Edit**, **New identity secret**. It is shown once and goes straight into the backend's environment. `create_app` never returns it.
- Connect Discord, if wanted: **Settings › Discord › Connect Discord**, pick the server on Discord's page, then pick a forum for each app or **Create a forum for this app**. Or Telegram: make a bot with @BotFather, paste its token under **Settings › Telegram** and press **Start** in the bot chat. See [references/channels.md](references/channels.md).
- Invite teammates by email on the **Team** page, as an admin or an agent, if wanted. Agents only work the inbox; admins can change settings and Push.
- Make an API key, only if you need one besides the MCP sign-in: **Push › Setup**, under **Server API**, **New key**. The key (`hbk_...`) is shown once.
- Pay: the account owner picks a plan in **Settings › Plan** before the trial ends. The link `planUrl` from `get_account` (`https://app.hailbell.com/?plan=1`) opens it. When an unpaid trial or plan ends, the account pauses at once: chat goes offline for customers, replies aren't sent, and campaign pushes and AI replies stop (HTTP 402 or 503). Tell the person to pick a plan; nothing is deleted.
- Anything in Xcode, App Store Connect, Google Play Console, Firebase, Superwall or RevenueCat that needs their accounts.

Never ask the person to paste the identity secret, an API key, a bot token or a push key into the chat. The identity secret belongs on their backend only. An API key goes into an environment variable or the agent's MCP config.

## Order of work for a new app

1. **Connect the MCP server** (below). If the person has no Hailbell account yet, ask them to sign up first; connecting signs them in.
2. **Check the account and its apps.** Call `get_account` and `list_apps`. Tell the person how many trial days are left. If the app is listed, use its App IDs.
3. **Make the app if it's missing.** Read the project first: its name, which platforms it has, the iOS bundle ID (`PRODUCT_BUNDLE_IDENTIFIER`) and the Android `applicationId`. Call `create_app` with the first platform, then `add_platform` for each other one. Each call returns `nextSteps`: what to tell the person.
4. **Integrate the SDK** for each platform the app has:
   - iOS: [references/ios.md](references/ios.md)
   - Android: [references/android.md](references/android.md)
   - Flutter: [references/flutter.md](references/flutter.md)
   - React Native and Expo: [references/react-native.md](references/react-native.md)
   - Web: [references/web.md](references/web.md)
5. **Wire the basics in code**: configure at launch, at least one visible entry point ("Chat with us"), metadata (`appVersion`, `plan`), push token and tap handling, `reset()` on sign-out, `deleteData()` in account deletion.
6. **Ask the person for their part, in one message**: push keys in **Settings › Push keys**, Discord or Telegram if they want them (the dashboard inbox works with no setup), an identity secret if a backend signs users in, and a plan before the trial ends. See [references/channels.md](references/channels.md). For Android, set the Firebase project ID yourself with `update_setup` (`firebaseProject`, from `google-services.json`).
7. **Teach the AI**: write the How-to guide from the app's source code, then the notes, plans and prices and saved replies. Save with `update_ai_replies`. See [references/ai-replies.md](references/ai-replies.md).
8. **Test on real devices**: send a message from the app, reply from the dashboard with the chat closed, check the push arrives and opens the chat. `get_setup` says when iOS and Android are ready to send. In the customer's details panel, **Send test notification** says which kind of build the phone's token came from.
9. **Push campaigns**, if wanted: [references/push.md](references/push.md).
10. **Store paperwork**: draft the App Privacy and Data safety answers and the App Review notes from the platform reference. The person submits them.

Before you write code, read the app's project: which platforms exist, how it presents screens, whether it uses Superwall or RevenueCat, whether it uses Firebase Auth or its own backend, and where its settings or profile screen is. Match its style.

## Connect the MCP server

URL: `https://api.hailbell.com/mcp` (streamable HTTP).

Two ways to sign in:

- **OAuth.** Add the URL alone. The client registers itself and opens Hailbell's sign-in: the person signs in (Google or an emailed link) and picks which Hailbell account you work in. Hailbell then makes a key named "Connected agent" in that account that works for all its apps with every scope. The person can revoke it in the API keys list under **Push › Setup**. To work in another account, sign in again and pick it.
- **API key.** Send `Authorization: Bearer hbk_...`. A key has scopes (`read`, `send`, `manage`), a daily limit on the notifications it creates, and works for one app or every app. With an all-apps key, pass `appId` on each call. `update_ai_replies`, segments, tags and Setup changes need `manage`. `create_app` and `add_platform` need `manage` and an all-apps key, made by someone who is still an admin or the owner.

Claude Code:

```sh
# OAuth: add it, then run /mcp in Claude Code and choose hailbell to sign in
claude mcp add --transport http hailbell https://api.hailbell.com/mcp

# Or with an API key
claude mcp add --transport http hailbell https://api.hailbell.com/mcp --header "Authorization: Bearer hbk_..."
```

Codex (`~/.codex/config.toml`):

```toml
# OAuth: add this, then run `codex mcp login hailbell`
[mcp_servers.hailbell]
url = "https://api.hailbell.com/mcp"

# Or with an API key: put it in an environment variable and name the variable here
# bearer_token_env_var = "HAILBELL_API_KEY"
```

Codex can also add it from the terminal: `codex mcp add hailbell --url https://api.hailbell.com/mcp`, then `codex mcp login hailbell`.

Other clients: add the URL as a remote MCP server or connector. If the client can't do OAuth, use a key in the `Authorization` header.

No MCP client? Every tool has a REST twin at `https://api.hailbell.com/v1/...` with the same header. The spec is `https://api.hailbell.com/openapi.json`. Or download the one-file CLI, which calls the same tools: `curl -fsSL https://api.hailbell.com/hailbell.mjs -o hailbell.mjs && HAILBELL_API_KEY=hbk_... node hailbell.mjs tools` (see [references/push.md](references/push.md)).

### Tools

| Tool | Scope | What it does |
| --- | --- | --- |
| `get_account` | read | The account's name, plan and billing: `state` (trial, active, paused), `daysLeft`, `trialEndsAt`, prices, and `planUrl` for picking a plan |
| `list_apps` | read | Platforms this key can use, with App IDs, subscriber counts and whether each can send |
| `create_app` | manage | Makes an app with its first platform: `name`, `platform` (`ios`, `android`, `web`), `bundleId` and `appStoreId` (iOS) or `packageName` (Android), and `website`. Hailbell fetches the store icon from these at once. Returns the App ID, `productId` and `iconUrl`. Refuses a name or bundle ID already in the account |
| `add_platform` | manage | Adds iOS, Android or web to an app: `productId`, `platform`, `bundleId`, `appStoreId`, `packageName` or `website`. Returns the new App ID |
| `get_context` | read | Local time of the audience, countries, usual hours, upcoming occasions, caps, quiet hours, template variables |
| `estimate_audience` | read | Devices and people an audience reaches, per platform and per App ID |
| `preview_notification` | read | Checks a message, shows reach, samples and waves, returns a `confirmToken` |
| `send_notification` | send | Sends or schedules, to one platform or (with `platforms` or `productId`) one campaign across several. Broadcasts need the preview's `confirmToken` |
| `send_test` | send | Sends now to test devices only |
| `get_notification`, `list_notifications` | read | Status and numbers: sent, delivered, clicked |
| `cancel_notification` | send | Stops a scheduled or sending notification or campaign (`ngr_...`) |
| `coming_up` | read | Scheduled sends plus upcoming occasions |
| `list_segments`, `create_segment`, `update_segment`, `delete_segment` | read / manage | Saved audiences. Confirm with the person before deleting |
| `get_user`, `set_user_tags`, `list_tag_keys` | read / manage | Users by your own id, their tags and devices |
| `list_subscribers`, `set_test_device` | read / manage | Devices, and marking test devices |
| `upload_image` | send | Copies an image to Hailbell for `content.image` |
| `get_setup`, `update_setup` | read / manage | The Push Setup tab of one platform |
| `get_ai_replies`, `update_ai_replies` | read / manage | The app's AI replies settings |

The team, API keys, push keys, Discord, Telegram, the plan, chat design, offers, review settings and deleting apps are managed by the person in the dashboard. There is no MCP tool for them.

## Rules that protect the person's customers

- **Never broadcast without showing the preview.** Call `preview_notification`, show the person who it reaches and how it reads, and send only after they say yes. Sends to test devices or up to 100 named users need no preview.
- **Marketing vs transactional.** `kind: "marketing"` (the default) skips people who opted out. Use `transactional` only for receipts, replies, security and account messages.
- **Pass `idempotencyKey`** on any send that might be retried.
- **Each person gets a campaign once.** With `platforms` or `productId`, a signed-in person gets it on the device they used most recently, not on every device. The daily cap counts per person across all platforms of the app.
- **Write only what is true** in AI replies settings: from the app's source code, its store listing or website, and what the person tells you. Never invent prices, features, policies or steps.
- **Don't turn on AI replies** (`enabled: true`) unless the person asks. It makes the AI answer real customers.
- **Read before you write.** `update_ai_replies` and `update_setup` replace each field or part you pass. Call `get_ai_replies` or `get_setup` first and send the whole new text.
- **Don't make copies.** Call `list_apps` before `create_app`, and add platforms to the app that's there instead of making a second one. A retry with the same name is refused, and only the person can delete an app.
- **Keep secrets out of code.** The App ID is public. The identity secret, API keys, bot tokens and push keys are not. Never put the identity secret in an app binary or a web page.
- **App Store and Google Play rules.** Promotional pushes on iOS need an explicit opt-in and an in-app way to opt out (guideline 4.5.4). Apps with account deletion must delete the chat too (`deleteData()`, guideline 5.1.1(v)). The chat discloses AI replies on its own (guideline 5.1.2(i)). Never offer anything in return for a review.

## References

- [references/ios.md](references/ios.md): Swift package, wrapper file, entry points, sign-in, push, Notification Service Extension, offers, revenue, App Store privacy and review notes.
- [references/android.md](references/android.md): Kotlin and Compose library from JitPack, wrapper, entry points, FCM, channels and marketing opt-in, Google Play Data safety.
- [references/web.md](references/web.md): the chat widget, its options and API, CSP, signed-in users, web push.
- [references/channels.md](references/channels.md): replying from the dashboard, Discord and Telegram, and the thread commands.
- [references/ai-replies.md](references/ai-replies.md): how AI replies behave, every field, and the workflow for writing the how-to guide from source code.
- [references/push.md](references/push.md): the push workflow, campaigns across platforms, audiences, content, timing, segments and tags, the CLI, REST.

Docs for people: https://hailbell.com/docs. Help from a person: hello@hailbell.com.